@johnhenry/browsermesh-transport 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clawser Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# browsermesh-transport
+
+WebSocket, WebRTC, WebTransport, relay, and streaming adapters for BrowserMesh.
+
+## Provenance
+
+Extracted from the private `clawser` monorepo (previously `packages/browsermesh-transport`), where it was manually published to npm, unscoped, as `browsermesh-transport@0.1.0` (2026-07-17) with no CI ever automating that publish. This is its first release as part of the `@johnhenry/browsermesh` monorepo; the version restarts at `0.0.0` per family convention.
+
+
+## Modules
+
+| Module | Key Exports |
+|--------|-------------|
+| transport | `MeshTransport`, `MockMeshTransport`, `MeshTransportNegotiator` |
+| websocket | `WebSocketTransport`, `WebRTCTransport`, `WebTransportTransport`, `NATTraversal`, `TransportFactory` |
+| webrtc | `WebRTCPeerConnection`, `WebRTCMeshManager`, `WebRTCTransportAdapter` |
+| webtransport | `WebTransportBridge`, `WebTransportAdapterFactory` |
+| relay | `MeshRelayClient`, `MockRelayServer` |
+| gateway | `GatewayNode`, `GatewayDiscovery`, `RouteTable` |
+| streams | `MeshStream`, `StreamMultiplexer` |
+| cross-origin | `CrossOriginBridge`, `CrossOriginHandshake`, `RateLimiter` |
+| wsh-bridge | `MeshWshBridge` |
+| wisp | `WispTransport` |
+| channel-relay | `ChannelRelay` |
+
+## Install
+
+```bash
+npm install @johnhenry/browsermesh-transport @johnhenry/browsermesh-primitives
+```
+
+## Usage
+
+```js
+import { MeshTransport, WebSocketTransport, StreamMultiplexer } from 'browsermesh-transport';
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@johnhenry/browsermesh-transport",
+  "version": "0.0.0",
+  "description": "WebSocket, WebRTC, WebTransport, and relay adapters for BrowserMesh",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/johnhenry/browsermesh",
+    "directory": "packages/browsermesh-transport"
+  },
+  "peerDependencies": {
+    "@johnhenry/browsermesh-primitives": ">=0.0.0"
+  },
+  "scripts": {
+    "test": "node --import ./test/_setup-globals.mjs --test test/*.test.mjs"
+  },
+  "homepage": "https://opensource.johnhenry.me/browsermesh/",
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/src/channel-relay.mjs

@@ -0,0 +1,225 @@
+import { silentCatch } from './silent-catch.mjs'
+// clawser-channel-relay.js — Channel Relay Plugin
+//
+// Virtual server route for webhooks + BroadcastChannel relay.
+// Normalizes inbound messages via createInboundMessage().
+// Supports named routes for dispatching webhook payloads.
+
+// ── Helpers ──────────────────────────────────────────────────
+
+let relayCounter = 0;
+
+function generateId() {
+  return `relay_${Date.now()}_${++relayCounter}`;
+}
+
+// ── ChannelRelay ─────────────────────────────────────────────
+
+/**
+ * Virtual webhook server + BroadcastChannel relay.
+ * Receives inbound webhooks via handleWebhook() and relays via BroadcastChannel.
+ * Supports named routes for dispatching different webhook types.
+ */
+export class ChannelRelay {
+  /** @type {object} */
+  config;
+
+  /** @type {boolean} */
+  running = false;
+
+  /** @type {Function|null} */
+  _callback = null;
+
+  /** @type {object|null} BroadcastChannel instance */
+  _bc = null;
+
+  /** @type {Map<string, Function>} named route handlers */
+  #routes = new Map();
+
+  /**
+   * @param {object} opts
+   * @param {number} [opts.port=0] — virtual port (for documentation/config)
+   * @param {string} [opts.path='/webhook'] — webhook path
+   * @param {string} [opts.bcName='clawser-relay'] — BroadcastChannel name
+   */
+  constructor(opts = {}) {
+    this.config = {
+      port: opts.port || 0,
+      path: opts.path || '/webhook',
+      bcName: opts.bcName || 'clawser-relay',
+    };
+  }
+
+  // ── Message normalization ───────────────────────────────
+
+  /**
+   * Normalize a raw webhook payload into standard inbound message format.
+   * @param {object} raw
+   * @returns {object} Standard InboundMessage
+   */
+  createInboundMessage(raw) {
+    const senderRaw = raw.sender;
+    const senderObj = (typeof senderRaw === 'object' && senderRaw !== null)
+      ? senderRaw
+      : { id: senderRaw || 'unknown', name: senderRaw || 'Unknown' };
+
+    return {
+      id: raw.id || generateId(),
+      channel: 'relay',
+      channelId: raw.channelId || null,
+      sender: {
+        id: senderObj.id || 'unknown',
+        name: senderObj.name || 'Unknown',
+        username: senderObj.username || null,
+      },
+      content: raw.body || raw.text || raw.content || '',
+      attachments: raw.attachments || [],
+      replyTo: raw.replyTo || null,
+      timestamp: raw.timestamp || Date.now(),
+    };
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────
+
+  /**
+   * Start the relay — creates BroadcastChannel and begins listening.
+   */
+  start() {
+    if (this.running) return;
+    this.running = true;
+
+    // Create BroadcastChannel for cross-tab relay
+    if (typeof BroadcastChannel !== 'undefined' && !this._bc) {
+      try {
+        this._bc = new BroadcastChannel(this.config.bcName);
+        this._bc.onmessage = (event) => this._handleBcMessage(event);
+      } catch {
+        // BroadcastChannel not available — proceed without
+      }
+    }
+  }
+
+  /**
+   * Stop the relay — closes BroadcastChannel.
+   */
+  stop() {
+    if (!this.running) return;
+    this.running = false;
+
+    if (this._bc) {
+      try { this._bc.close(); } catch (e) { silentCatch('clawser-channel-relay', 'this._bc.close', e) }
+      this._bc = null;
+    }
+  }
+
+  // ── Inbound handling ────────────────────────────────────
+
+  /**
+   * Register a callback for inbound messages.
+   * @param {Function} callback — (msg: InboundMessage) => void
+   */
+  onMessage(callback) {
+    this._callback = callback;
+  }
+
+  /**
+   * Handle an incoming webhook payload.
+   * Dispatches to named route if payload has a `route` property,
+   * otherwise normalizes and forwards to onMessage callback.
+   * @param {object} payload
+   */
+  handleWebhook(payload) {
+    if (!this.running) return;
+
+    // Check for named route
+    if (payload.route && this.#routes.has(payload.route)) {
+      this.#routes.get(payload.route)(payload);
+      return;
+    }
+
+    // Normalize and dispatch
+    const msg = this.createInboundMessage(payload);
+    if (this._callback) {
+      this._callback(msg);
+    }
+  }
+
+  /**
+   * Handle a message received from BroadcastChannel.
+   * @param {object} event — MessageEvent-like {data: ...}
+   */
+  _handleBcMessage(event) {
+    if (!this.running) return;
+    const raw = event.data || event;
+    const msg = this.createInboundMessage(raw);
+    if (this._callback) {
+      this._callback(msg);
+    }
+  }
+
+  // ── Outbound ────────────────────────────────────────────
+
+  /**
+   * Send a message via BroadcastChannel relay.
+   * @param {string} text
+   * @param {object} [opts]
+   * @returns {boolean}
+   */
+  sendMessage(text, opts = {}) {
+    if (!this.running) return false;
+
+    const msg = {
+      text,
+      channel: 'relay',
+      sender: opts.sender || 'clawser',
+      timestamp: Date.now(),
+    };
+
+    if (this._bc) {
+      try {
+        this._bc.postMessage(msg);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  // ── Route table ─────────────────────────────────────────
+
+  /**
+   * Add a named route handler.
+   * @param {string} name
+   * @param {Function} handler — (payload) => void
+   */
+  addRoute(name, handler) {
+    this.#routes.set(name, handler);
+  }
+
+  /**
+   * Remove a named route handler.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  removeRoute(name) {
+    return this.#routes.delete(name);
+  }
+
+  /**
+   * Check if a named route exists.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  hasRoute(name) {
+    return this.#routes.has(name);
+  }
+
+  /**
+   * List all registered route names.
+   * @returns {string[]}
+   */
+  listRoutes() {
+    return [...this.#routes.keys()];
+  }
+}