@dpkrn/nodetunnel 1.0.0 → 1.0.3

package/README.md

@@ -1,31 +1,60 @@
 # @dpkrn/nodetunnel
 
-**nodetunnel** is a Node.js library for exposing a local HTTP server through a compatible tunnel server (yamux + JSON wire format). It is published on npm as **`@dpkrn/nodetunnel`**.
+Give your **local** HTTP server a **public URL** from Node.js — useful for webhooks, demos, sharing a dev server, or testing from another device.
 
-```
-Internet ──► Tunnel Server ──► yamux stream ──► nodetunnel ──► localhost:<port>
-```
+---
+
+## Why use it
+
+- **No separate tunnel process** — call one function from your app.
+- **Works with your existing server** — Express, Fastify, or plain `http`.
+- **Simple API** — you get a public `url` and a `stop()` when you are done.
+
+You need a **tunnel server** running that this library can connect to (host and port are configurable; defaults suit a typical local setup).
+
+---
+
+## Requirements
 
-**Requirements**
+- **Node.js 18+**
+- Your app listening on a port (e.g. `8080`)
+- A **tunnel server** reachable from your machine (default: `localhost:9000`)
 
-- **Node.js 18+** (uses global `fetch` / `Headers`)
-- A running tunnel **server** reachable at `localhost:9000` (for example the [devtunnel](https://github.com/DpkRn/devtunnel) server)
+---
 
-### Install from npm
+## Install
 
 ```bash
 npm install @dpkrn/nodetunnel
 ```
 
-When developing **in this repository**, import with a relative path instead, for example:
-
-`import { startTunnel } from "./pkg/tunnel/tunnel.js"`.
+This package is **ESM** (`import` / `export`).
 
 ---
 
-## Quick start (ESM)
 
-This package is **`"type": "module"`**. Use `import`, not `require`.
+
+## Quick Example
+
+```js
+import express from "express";
+import { startTunnel } from "@dpkrn/nodetunnel";
+
+const app = express();
+const PORT = 8080;
+
+app.get("/", (req, res) => res.send("OK"));
+
+app.listen(PORT, async () => {
+  const { url, stop } = await startTunnel(String(PORT));
+  //url is your public url using you can access publicly your server
+  //stop() is method that will close your connection on error
+});
+```
+
+---
+
+## Easiest example
 
 ```js
 import http from "node:http";
@@ -34,8 +63,7 @@ import { startTunnel } from "@dpkrn/nodetunnel";
 const PORT = 8080;
 
 const server = http.createServer((req, res) => {
-  res.writeHead(200, { "Content-Type": "text/plain" });
-  res.end("Hello from localhost\n");
+  res.end("Hello\n");
 });
 
 server.listen(PORT, async () => {
@@ -53,49 +81,22 @@ server.listen(PORT, async () => {
 });
 ```
 
-1. Start your tunnel **server** (port **9000**).
-2. Run your script: `node app.js`
-3. Open the printed **public URL** in a browser or `curl` it.
+Run with `node app.js`. Open the printed URL in a browser or share it for webhooks.
 
 ---
 
-## API
-
-### `startTunnel(port, options?)`
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `port` | `string` | Local port your HTTP server listens on (e.g. `"8080"`). |
-| `options` | `object` (optional) | `{ host?: string, serverPort?: number }` — tunnel server address (default `localhost:9000`). |
-
-**Returns** a `Promise` resolving to:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `url` | `string` | Public URL assigned by the server (e.g. `http://subdomain.localhost:3000`). |
-| `stop` | `() => void` | Stops the tunnel and closes the connection. |
-
-On failure (cannot connect, handshake error), the promise **rejects**. Use `try/catch`.
-
----
-
-## Express example
-
-Start the HTTP server first, then call `startTunnel` with the **same port**.
+## Express (same idea)
 
 ```js
 import express from "express";
 import { startTunnel } from "@dpkrn/nodetunnel";
 
 const app = express();
-const PORT = process.env.PORT || 8080;
+const PORT = 8080;
 
-app.get("/", (req, res) => {
-  res.send("OK");
-});
+app.get("/", (req, res) => res.send("OK"));
 
 app.listen(PORT, async () => {
-  console.log(`http://127.0.0.1:${PORT}`);
   try {
     const { url, stop } = await startTunnel(String(PORT));
     console.log("Public:", url);
@@ -104,91 +105,38 @@ app.listen(PORT, async () => {
       process.exit(0);
     });
   } catch (e) {
-    console.error("Tunnel error:", e.message);
+    console.error(e.message);
   }
 });
 ```
 
 ---
 
-## Troubleshooting
-
-- **`Tunnel failed` / connection refused** — Start the tunnel server on the host/port you pass in `options` (default `localhost:9000`).
-- **Wrong path when running scripts** — Run from the `nodetunnel` directory, or use `node nodetunnel/cmd/test-lib/main.js` from the repo root.
-- **Port already in use** — Another process may be bound to your app port; stop it or change `PORT`.
-
----
-
-## CLI — `mytunnel` (release install, ngrok-style)
-
-Besides embedding **nodetunnel** in a Node app, you can install the **`mytunnel`** CLI from **[devtunnel](https://github.com/DpkRn/devtunnel) releases** — same idea as **ngrok**: one binary, one command, expose a local port. It speaks the same tunnel server + yamux protocol as this library.
-
-```
-Internet ──► Tunnel Server ──► yamux stream ──► mytunnel ──► localhost:<port>
-```
-
-The **`mytunnel`** binary lets you expose any local port with a single command (no Node required for the client).
-
-### Install
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/DpkRn/devtunnel/master/install.sh | bash
-```
-
-Auto-detects your OS and CPU architecture (macOS Apple Silicon, macOS Intel, Linux x86_64) and installs to `/usr/local/bin`.
-
-**Or build the Go client from source** (from the [devtunnel](https://github.com/DpkRn/devtunnel) or [gotunnel](https://github.com/DpkRn/gotunnel) repo):
-
-```bash
-go build -o mytunnel ./cmd/client
-sudo mv mytunnel /usr/local/bin/
-```
-
-### Usage
-
-```bash
-mytunnel http <port>
-```
-
-**Example — expose a dev server on port 3000:**
+## API
 
-```
-$ mytunnel http 3000
-
-  ╔══════════════════════════════════════════════════╗
-  ║   🚇  mytunnel — tunnel is live                  ║
-  ╠══════════════════════════════════════════════════╣
-  ║  🌍  Public   →  http://abc123.example.com        ║
-  ║  💻  Local    →  http://localhost:3000            ║
-  ╠══════════════════════════════════════════════════╣
-  ║  ⚡  Forwarding requests...                      ║
-  ║  🛑  Press Ctrl+C to stop                        ║
-  ╚══════════════════════════════════════════════════╝
-```
+### `await startTunnel(port, options?)`
 
-Press `Ctrl+C` to stop.
+| Argument | Description |
+|----------|-------------|
+| `port` | String, e.g. `"8080"` — must match the port your HTTP server uses. |
+| `options` | Optional. `{ host?: string, serverPort?: number }` — where to reach your tunnel server (defaults: `localhost` and `9000`). |
 
-### Commands
+**Returns:** `{ url, stop }`
 
-| Command | Description |
-|---------|-------------|
-| `mytunnel http <port>` | Forward public HTTP traffic to `localhost:<port>` |
-| `mytunnel help` | Show help |
+| Field | Description |
+|-------|-------------|
+| `url` | Public URL people can hit. |
+| `stop` | Call to tear down the tunnel. |
 
-You still need the **tunnel server** running (e.g. on `localhost:9000`) for both **nodetunnel** and **mytunnel**.
+Errors **reject** the promise — use `try/catch`.
 
 ---
 
-## Publishing to npm (maintainers)
-
-This package is published as **`@dpkrn/nodetunnel`** ([scoped package](https://docs.npmjs.com/about-scopes)). **`publishConfig.access`** is set to **`"public"`** so anyone can install it without an npm org.
-
-1. Bump **`version`** in `package.json` (semver).
-2. Dry run: `npm pack` — inspect the tarball.
-3. Log in: `npm login` (account must have permission to publish under the **`@dpkrn`** scope).
-4. From the **`nodetunnel`** directory: `npm publish`
+## Troubleshooting
 
-Adjust **`repository`**, **`bugs`**, and **`homepage`** in `package.json` if your Git remote or default branch differs.
+- **Connection / tunnel failed** — Confirm your tunnel server is running and that `host` / `serverPort` match your setup.
+- **Nothing loads on the public URL** — Confirm your local server is already listening on the port you passed to `startTunnel`.
+- **Port in use** — Pick another port or stop the other process using it.
 
 ---
 

package/cmd/test-lib/main.js

@@ -1,5 +1,6 @@
 import express from "express";
-import { startTunnel } from "../../pkg/tunnel/tunnel.js";
+import { startTunnel } from "@dpkrn/nodetunnel";
+
 
 const app = express();
 app.set("etag", false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpkrn/nodetunnel",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Expose a local HTTP server through a devtunnel/gotunnel-compatible server (yamux + JSON). Node.js 18+.",
   "keywords": [
     "tunnel",
@@ -49,6 +49,7 @@
     "prepublishOnly": "node -e \"import('./pkg/tunnel/tunnel.js').then(() => console.log('pack ok')).catch(e => { console.error(e); process.exit(1); })\""
   },
   "dependencies": {
+    "@dpkrn/nodetunnel": "^1.0.2",
     "yamux-js": "^0.2.0"
   },
   "devDependencies": {