nport 1.0.6 → 2.0.2

package/README.md

@@ -1,68 +1,263 @@
 # <img src="https://nport.link/assets/imgs/nport-logo.png" height="30" style="vertical-align: middle;"> NPort
 
-> A Node.js tool for exposing local servers through Socket.IO tunnels
+> 🚀 Free & open source ngrok alternative - Tunnel localhost to the internet via Cloudflare Edge
 
 [![GitHub](https://img.shields.io/github/stars/tuanngocptn/nport?style=social)](https://github.com/tuanngocptn/nport)
 [![NPM](https://img.shields.io/npm/v/nport?color=red&logo=npm)](https://www.npmjs.com/package/nport)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fnport.link&up_message=nport.link&up_color=blue&down_color=lightgrey&down_message=offline)](https://nport.link)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 ## What is NPort?
 
 [![nport](https://github.com/user-attachments/assets/6e188d75-4633-4efa-a7f4-63df6a4a7ac8)](https://nport.link)
 
-NPort allows you to expose your local HTTP servers to the internet using Socket.IO streams. Perfect for:
-- Development environments
-- Testing webhooks
-- Sharing local projects
+NPort is a powerful, lightweight **ngrok alternative** that creates secure HTTP/HTTPS tunnels from your localhost to public URLs using **Cloudflare's global edge network**. No configuration, no accounts, just instant tunnels with custom subdomains!
+
+Perfect for:
+- 🚀 **Development environments** - Share your local work instantly
+- 🔒 **Testing webhooks** - Receive webhooks from GitHub, Stripe, PayPal, etc.
+- 📱 **Mobile testing** - Test your web app on real devices
+- 🛠️ **API development** - Debug integrations with external services
+- 👥 **Demo to clients** - Show your progress without deployment
 
 ## ✨ Features
 
-- 🔒 **Secure Tunneling**: Share your local server safely using Socket.IO
-- 🚀 **Easy Setup**: Minimal configuration required
-- 🌐 **Custom Domains**: Get readable URLs like `https://yourname.nport.link`
-- 📡 **WebSocket Ready**: Full WebSocket connection support
-- 💻 **Cross-Platform**: Runs on Windows, macOS, and Linux
+- ⚡ **Instant Setup**: One command to expose your localhost
+- 🌐 **Custom Subdomains**: Choose your own URL (e.g., `myapp.nport.link`)
+- 🔒 **Automatic HTTPS**: SSL/TLS encryption via Cloudflare
+- 🌍 **Global Edge Network**: Fast connections worldwide via Cloudflare
+- 📡 **WebSocket Support**: Full WebSocket and Server-Sent Events support
+- 🎯 **No Configuration**: Works out of the box
+- 💻 **Cross-Platform**: Windows, macOS, and Linux support
+- 🆓 **100% Free**: No accounts, no limits, no paywalls
+- 🔓 **Open Source**: MIT licensed
 
 ## 📦 Installation
 
-**NPM Package**
-```bash
-# Local installation
-npm install nport
+### NPM (Recommended)
 
+```bash
 # Global installation
 npm install -g nport
+
+# Or use npx without installation
+npx nport 3000 -s myapp
 ```
 
-**From GitHub**
-```bash
-# Local installation
-npm install git+https://github.com/tuanngocptn/nport.git
+### From GitHub
 
-# Global installation
+```bash
 npm install -g git+https://github.com/tuanngocptn/nport.git
 ```
 
 ## 🚀 Quick Start
 
 ### Basic Usage
+
+Expose port 3000 with a random subdomain:
 ```bash
-# Local installation
-npx nport -s myapp -p 3000
+nport 3000
+```
 
-# Global installation
-nport -s myapp -p 3000
+Output:
 ```
-This will create a tunnel at `https://myapp.nport.link`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  NPort - Free & Open Source ngrok Alternative
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🌐 Website: https://nport.link
+  📦 NPM:     https://www.npmjs.com/package/nport
+  💻 GitHub:  https://github.com/tuanngocptn/nport
+  ☕ Support: https://buymeacoffee.com/tuanngocptn
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-### Advanced Options
+🚀 Starting Tunnel for port 3000...
+✔ Tunnel created!
+🌍 Public URL: https://user-1234.nport.link
+```
+
+### Custom Subdomain
+
+Choose your own subdomain:
+```bash
+nport 3000 -s myapp
+# Creates: https://myapp.nport.link
+```
+
+Or using long form:
 ```bash
-# Full configuration
-npx nport --server https://server.nport.link \
-         --subdomain myapp \
-         --hostname 127.0.0.1 \
-         --port 3000
+nport 3000 --subdomain myapp
 ```
 
-## 📝 Credits
-Inspired by [Socket Tunnel](https://github.com/ericbarch/socket-tunnel). Read more about the concept in this [blog post](https://ericbarch.com/post/sockettunnel/).
+## 📖 Usage Examples
+
+### Web Development
+
+```bash
+# Next.js
+npm run dev
+nport 3000 -s my-nextjs-app
+
+# React (Create React App)
+npm start
+nport 3000 -s my-react-app
+
+# Vue.js
+npm run dev
+nport 8080 -s my-vue-app
+
+# Express.js
+node server.js
+nport 3000 -s my-api
+```
+
+### Webhook Testing
+
+```bash
+# Start your local webhook receiver
+node webhook-receiver.js
+
+# Expose it to the internet
+nport 4000 -s my-webhooks
+
+# Use in GitHub webhook settings:
+# https://my-webhooks.nport.link/webhook
+```
+
+### Mobile Device Testing
+
+```bash
+# Start your local dev server
+npm run dev
+
+# Create tunnel
+nport 3000 -s mobile-test
+
+# Open on your phone:
+# https://mobile-test.nport.link
+```
+
+## 🎯 CLI Options
+
+```bash
+nport <port> [options]
+```
+
+| Option | Short | Description | Example |
+|--------|-------|-------------|---------|
+| `<port>` | - | Local port to tunnel (default: 8080) | `nport 3000` |
+| `--subdomain` | `-s` | Custom subdomain | `nport 3000 -s myapp` |
+| `-s=value` | - | Alternative format | `nport 3000 -s=myapp` |
+
+## 🔧 How It Works
+
+1. **You run** `nport 3000 -s myapp`
+2. **NPort creates** a Cloudflare Tunnel
+3. **DNS record** is created: `myapp.nport.link` → Cloudflare Edge
+4. **Cloudflared binary** connects your localhost:3000 to Cloudflare
+5. **Traffic flows** through Cloudflare's global network to your machine
+6. **On exit** (Ctrl+C), tunnel and DNS are automatically cleaned up
+
+```
+Internet → Cloudflare Edge → Cloudflare Tunnel → Your localhost:3000
+         (https://myapp.nport.link)
+```
+
+## 🛡️ Security
+
+- **HTTPS by default**: All tunnels use SSL/TLS encryption
+- **Cloudflare protection**: DDoS protection and security features
+- **Automatic cleanup**: Tunnels are removed when you stop the process
+- **No data logging**: We don't store or log your traffic
+
+## 🆚 Comparison with ngrok
+
+| Feature | NPort | ngrok |
+|---------|-------|-------|
+| Price | 100% Free | Free tier limited |
+| Custom subdomains | ✅ Always | ❌ Paid only |
+| HTTPS | ✅ Always | ✅ |
+| Account required | ❌ No | ✅ Yes |
+| Time limits | ❌ None | ⚠️ Free tier limited |
+| Open source | ✅ MIT | ❌ Proprietary |
+| Global network | ✅ Cloudflare | ✅ ngrok Edge |
+
+## 🧹 Cleanup
+
+NPort automatically cleans up resources when you:
+- Press **Ctrl+C** to exit
+- Kill the process
+- Terminal closes
+
+The cleanup process:
+1. ✅ Deletes DNS record (`myapp.nport.link`)
+2. ✅ Removes Cloudflare Tunnel
+3. ✅ Stops cloudflared process
+
+## 🐛 Troubleshooting
+
+### Binary not found
+
+If you see "Cloudflared binary not found":
+```bash
+npm install -g nport --force
+```
+
+### Port already in use
+
+Make sure your local server is running on the specified port:
+```bash
+# Check if something is listening on port 3000
+lsof -i :3000  # macOS/Linux
+netstat -ano | findstr :3000  # Windows
+```
+
+### Subdomain already taken
+
+Choose a different subdomain name:
+```bash
+nport 3000 -s myapp-v2
+```
+
+### Connection issues
+
+The `ERR Cannot determine default origin certificate path` warning is harmless and can be ignored. It appears because cloudflared checks for certificate-based authentication (we use token-based instead).
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 💖 Support
+
+If you find NPort useful, please consider supporting the project:
+
+- ⭐ [Star on GitHub](https://github.com/tuanngocptn/nport)
+- ☕ [Buy me a coffee](https://buymeacoffee.com/tuanngocptn)
+- 💬 Share with your friends and colleagues
+- 🐛 [Report bugs](https://github.com/tuanngocptn/nport/issues)
+
+## 📄 License
+
+[MIT License](LICENSE) - Feel free to use NPort in your projects!
+
+## 🙏 Credits
+
+- Created by [Nick Pham](https://github.com/tuanngocptn) 🇻🇳
+- Powered by [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
+- Inspired by [ngrok](https://ngrok.com) and [localtunnel](https://github.com/localtunnel/localtunnel)
+
+## 🔗 Links
+
+- 🌐 Website: [https://nport.link](https://nport.link)
+- 📦 NPM: [https://www.npmjs.com/package/nport](https://www.npmjs.com/package/nport)
+- 💻 GitHub: [https://github.com/tuanngocptn/nport](https://github.com/tuanngocptn/nport)
+- 📧 Email: tuanngocptn@gmail.com
+
+---
+
+Made with ❤️ by [Nick Pham](https://github.com/tuanngocptn)

package/analytics.js

@@ -0,0 +1,259 @@
+// ============================================================================
+// Firebase Analytics for CLI
+// Using Google Analytics 4 Measurement Protocol
+// ============================================================================
+
+import axios from "axios";
+import { createHash, randomUUID } from "crypto";
+import os from "os";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Firebase/GA4 Configuration (from website/home.html)
+// Full Firebase config for reference (if needed for future features)
+const FIREBASE_WEB_CONFIG = {
+  apiKey: "AIzaSyArRxHZJUt4o2RxiLqX1yDSkuUd6ZFy45I",
+  authDomain: "nport-link.firebaseapp.com",
+  projectId: "nport-link",
+  storageBucket: "nport-link.firebasestorage.app",
+  messagingSenderId: "515584605320",
+  appId: "1:515584605320:web:88daabc8d77146c6e7f33d",
+  measurementId: "G-8MYXZL6PGD"
+};
+
+// Analytics-specific config (for GA4 Measurement Protocol)
+const FIREBASE_CONFIG = {
+  measurementId: FIREBASE_WEB_CONFIG.measurementId,
+  apiSecret: process.env.NPORT_ANALYTICS_SECRET || "YOUR_API_SECRET_HERE", // Get from Firebase Console
+};
+
+// Analytics Configuration
+const ANALYTICS_CONFIG = {
+  enabled: true, // Can be disabled by environment variable
+  debug: process.env.NPORT_DEBUG === "true",
+  timeout: 2000, // Don't block CLI for too long
+  userIdFile: path.join(os.homedir(), ".nport-analytics"),
+};
+
+// ============================================================================
+// Analytics Manager
+// ============================================================================
+
+class AnalyticsManager {
+  constructor() {
+    this.userId = null;
+    this.sessionId = null;
+    this.disabled = false;
+    
+    // Disable analytics if environment variable is set
+    if (process.env.NPORT_ANALYTICS === "false") {
+      this.disabled = true;
+    }
+  }
+
+  /**
+   * Initialize analytics - must be called before tracking
+   */
+  async initialize() {
+    if (this.disabled) return;
+
+    // Check if API secret is configured
+    if (!FIREBASE_CONFIG.apiSecret || FIREBASE_CONFIG.apiSecret === "YOUR_API_SECRET_HERE") {
+      if (ANALYTICS_CONFIG.debug) {
+        console.warn("[Analytics] API secret not configured. Analytics disabled.");
+        console.warn("[Analytics] Set NPORT_ANALYTICS_SECRET environment variable.");
+      }
+      this.disabled = true;
+      return;
+    }
+
+    try {
+      this.userId = await this.getUserId();
+      this.sessionId = this.generateSessionId();
+      
+      if (ANALYTICS_CONFIG.debug) {
+        console.log("[Analytics] Initialized successfully");
+        console.log("[Analytics] User ID:", this.userId.substring(0, 8) + "...");
+      }
+    } catch (error) {
+      if (ANALYTICS_CONFIG.debug) {
+        console.error("[Analytics] Initialization failed:", error.message);
+      }
+      this.disabled = true;
+    }
+  }
+
+  /**
+   * Get or create a persistent user ID
+   */
+  async getUserId() {
+    try {
+      // Try to read existing user ID
+      if (fs.existsSync(ANALYTICS_CONFIG.userIdFile)) {
+        const userId = fs.readFileSync(ANALYTICS_CONFIG.userIdFile, "utf8").trim();
+        if (userId) return userId;
+      }
+
+      // Generate new anonymous user ID
+      const userId = this.generateAnonymousId();
+      
+      // Save for future use
+      fs.writeFileSync(ANALYTICS_CONFIG.userIdFile, userId, "utf8");
+      
+      return userId;
+    } catch (error) {
+      // If file operations fail, use session-based ID
+      return this.generateAnonymousId();
+    }
+  }
+
+  /**
+   * Generate anonymous user ID based on machine characteristics
+   */
+  generateAnonymousId() {
+    const machineId = [
+      os.hostname(),
+      os.platform(),
+      os.arch(),
+      os.homedir(),
+    ].join("-");
+    
+    return createHash("sha256").update(machineId).digest("hex").substring(0, 32);
+  }
+
+  /**
+   * Generate session ID
+   */
+  generateSessionId() {
+    return randomUUID();
+  }
+
+  /**
+   * Track an event
+   */
+  async trackEvent(eventName, params = {}) {
+    if (this.disabled || !ANALYTICS_CONFIG.enabled) return;
+
+    try {
+      const payload = this.buildPayload(eventName, params);
+      
+      // Send to GA4 Measurement Protocol (non-blocking)
+      axios.post(
+        `https://www.google-analytics.com/mp/collect?measurement_id=${FIREBASE_CONFIG.measurementId}&api_secret=${FIREBASE_CONFIG.apiSecret}`,
+        payload,
+        {
+          timeout: ANALYTICS_CONFIG.timeout,
+          headers: { "Content-Type": "application/json" },
+        }
+      ).catch((error) => {
+        // Silently fail - don't interrupt CLI operations
+        if (ANALYTICS_CONFIG.debug) {
+          console.error("[Analytics] Failed to send event:", error.message);
+        }
+      });
+
+      if (ANALYTICS_CONFIG.debug) {
+        console.log("[Analytics] Event tracked:", eventName, params);
+      }
+    } catch (error) {
+      // Silently fail
+      if (ANALYTICS_CONFIG.debug) {
+        console.error("[Analytics] Error tracking event:", error.message);
+      }
+    }
+  }
+
+  /**
+   * Build GA4 Measurement Protocol payload
+   */
+  buildPayload(eventName, params) {
+    return {
+      client_id: this.userId,
+      events: [
+        {
+          name: eventName,
+          params: {
+            session_id: this.sessionId,
+            engagement_time_msec: "100",
+            ...this.getSystemInfo(),
+            ...params,
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Get system information for context
+   */
+  getSystemInfo() {
+    return {
+      os_platform: os.platform(),
+      os_version: os.release(),
+      os_arch: os.arch(),
+      node_version: process.version,
+    };
+  }
+
+  /**
+   * Track CLI start
+   */
+  async trackCliStart(port, subdomain, version) {
+    await this.trackEvent("cli_start", {
+      port: String(port),
+      has_custom_subdomain: subdomain && !subdomain.startsWith("user-"),
+      cli_version: version,
+    });
+  }
+
+  /**
+   * Track tunnel creation
+   */
+  async trackTunnelCreated(subdomain, port) {
+    await this.trackEvent("tunnel_created", {
+      subdomain_type: subdomain.startsWith("user-") ? "random" : "custom",
+      port: String(port),
+    });
+  }
+
+  /**
+   * Track tunnel error
+   */
+  async trackTunnelError(errorType, errorMessage) {
+    await this.trackEvent("tunnel_error", {
+      error_type: errorType,
+      error_message: errorMessage.substring(0, 100), // Limit length
+    });
+  }
+
+  /**
+   * Track tunnel shutdown
+   */
+  async trackTunnelShutdown(reason, durationSeconds) {
+    await this.trackEvent("tunnel_shutdown", {
+      shutdown_reason: reason, // "manual", "timeout", "error"
+      duration_seconds: String(Math.floor(durationSeconds)),
+    });
+  }
+
+  /**
+   * Track CLI update notification shown
+   */
+  async trackUpdateAvailable(currentVersion, latestVersion) {
+    await this.trackEvent("update_available", {
+      current_version: currentVersion,
+      latest_version: latestVersion,
+    });
+  }
+}
+
+// ============================================================================
+// Export singleton instance
+// ============================================================================
+
+export const analytics = new AnalyticsManager();
+