@tetrax/voice-sdk 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# @tetrax/voice-sdk
+
+Client SDK for TETRAX Communication Platform as a Service (CPaaS). Connects seamlessly to TETRAX Voice real-time audio signaling and SFU servers.
+
+## Installation
+
+```bash
+npm install @tetrax/voice-sdk
+```
+
+Or reference locally via your application's `package.json`:
+
+```json
+"dependencies": {
+  "@tetrax/voice-sdk": "file:../path/to/tetrax-sdk"
+}
+```
+
+## Basic Usage
+
+```javascript
+import { TetraxVoice } from '@tetrax/voice-sdk';
+
+// Initialize SDK
+const client = new TetraxVoice({
+  apiKey: 'trx_live_your_key',
+  apiUri: 'https://api.tetrax.io' // Optional: defaults to production TETRAX cloud
+});
+
+// Register Event Listeners
+client.on('track', ({ stream, userId }) => {
+  // Play remote audio
+  const audio = new Audio();
+  audio.srcObject = stream;
+  audio.play();
+});
+
+client.on('user-joined', ({ userId }) => {
+  console.log(`User ${userId} has joined the voice call`);
+});
+
+client.on('user-left', ({ userId }) => {
+  console.log(`User ${userId} has left the voice call`);
+});
+
+// Connect to signaling and join the call room
+await client.connect(voiceToken);
+await client.joinRoom('room_123');
+
+// Toggle microphone
+await client.mute();
+await client.unmute();
+
+// Leave room
+await client.leaveRoom();
+```
+
+---
+
+## Hosting & Distribution Options
+
+Because an SDK (Software Development Kit) is a client-side library rather than a running process, **it does not need server hosting** like a backend api or database does. 
+
+Instead of running on a server, it needs to be hosted on a **package registry** or **version control host** so that target front-end applications can install it.
+
+Here are the best ways to host and distribute the **`@[tetrax-sdk]`** package:
+
+---
+
+### Option 1: Publish to the NPM Registry (Standard Production Approach)
+This makes the SDK available via a simple `npm install @tetrax/voice-sdk` (like other packages such as `react` or `socket.io-client`).
+* **Where it is hosted:** [npmjs.com](https://www.npmjs.com/) (The global NPM registry).
+* **Cost:** Free for public packages; paid for private packages.
+* **How to distribute:**
+  1. Register an NPM account (or create an organization named `tetrax`).
+  2. Log in via your terminal inside the `tetrax-sdk` folder:
+     ```bash
+     npm login
+     ```
+  3. Publish the package:
+     ```bash
+     npm publish --access public
+     ```
+
+---
+
+### Option 2: Host on GitHub / Git Repository (Best for Private/Internal Use)
+If you want to keep the SDK private or share it easily without publishing to public NPM, you can host it in its own Git repository.
+* **Where it is hosted:** GitHub, GitLab, or Bitbucket.
+* **How to install:** Other projects can install it directly from the Git URL:
+  ```bash
+  npm install git+https://github.com/your-username/tetrax-voice-sdk.git
+  ```
+  Or add it directly to `package.json`:
+  ```json
+  "dependencies": {
+    "@tetrax/voice-sdk": "git+https://github.com/your-username/tetrax-voice-sdk.git"
+  }
+  ```
+
+---
+
+### Option 3: Monorepo / Local Workspace (Best for single-repository setups)
+If you are developing both the backend/frontend client and the SDK together, you can keep them in the same repository.
+* **Where it is hosted:** Included in your main project repository.
+* **How to install:** Keep using the local link in your `package.json`:
+  ```json
+  "dependencies": {
+    "@tetrax/voice-sdk": "file:../tetrax-sdk"
+  }
+  ```
+
+---
+
+### Summary
+* **Mediasoup/Signaling Backend:** Must be hosted on a server (like VPS, AWS, DigitalOcean) with raw ports open for WebRTC connections.
+* **Tetrax SDK:** Hosted on **NPM** or **GitHub** as a library of code that gets bundled directly into your client's web browser builds.

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@tetrax/voice-sdk",
+  "version": "1.0.0",
+  "description": "TETRAX Voice Client SDK for Mediasoup Real-Time Audio Rooms",
+  "main": "src/index.js",
+  "type": "module",
+  "dependencies": {
+    "mediasoup-client": "^3.20.0",
+    "socket.io-client": "^4.8.3"
+  }
+}

package/src/index.js

@@ -0,0 +1,273 @@
+import { io } from 'socket.io-client';
+import { Device } from 'mediasoup-client';
+
+class EventEmitter {
+  constructor() {
+    this.listeners = {};
+  }
+
+  on(event, cb) {
+    if (!this.listeners[event]) this.listeners[event] = [];
+    this.listeners[event].push(cb);
+  }
+
+  off(event, cb) {
+    if (!this.listeners[event]) return;
+    this.listeners[event] = this.listeners[event].filter(l => l !== cb);
+  }
+
+  emit(event, ...args) {
+    if (!this.listeners[event]) return;
+    this.listeners[event].forEach(cb => cb(...args));
+  }
+}
+
+export class TetraxVoice extends EventEmitter {
+  constructor({ apiKey, apiUri }) {
+    super();
+    this.apiKey = apiKey;
+    this.apiUri = apiUri;
+    this.socket = null;
+    this.device = null;
+    this.roomId = null;
+    this.localStream = null;
+
+    // Transports and Media references
+    this.sendTransport = null;
+    this.recvTransport = null;
+    this.audioProducer = null;
+    this.consumers = new Map();
+  }
+
+  /**
+   * Connects to the TETRAX signaling server using the token
+   */
+  async connect(token) {
+    return new Promise((resolve, reject) => {
+      this.socket = io(this.apiUri, {
+        auth: { token }
+      });
+
+      this.socket.on('connect', () => {
+        this.emit('connected');
+        resolve();
+      });
+
+      this.socket.on('connect_error', (error) => {
+        this.emit('error', error);
+        reject(error);
+      });
+
+      this.socket.on('new-producer', async ({ producerId, userId }) => {
+        await this._consumeProducer(producerId, userId);
+      });
+
+      this.socket.on('user-joined', ({ userId }) => {
+        this.emit('user-joined', { userId });
+      });
+
+      this.socket.on('user-left', ({ userId }) => {
+        this.emit('user-left', { userId });
+      });
+
+      this.socket.on('user-muted', ({ userId }) => {
+        this.emit('user-muted', { userId });
+      });
+
+      this.socket.on('user-unmuted', ({ userId }) => {
+        this.emit('user-unmuted', { userId });
+      });
+    });
+  }
+
+  /**
+   * Joins a specific audio room and sets up sending/receiving audio
+   */
+  async joinRoom(roomId) {
+    this.roomId = roomId;
+
+    return new Promise((resolve, reject) => {
+      this.socket.emit('join-room', { roomId }, async (res) => {
+        if (res?.error) {
+          return reject(new Error(res.error));
+        }
+
+        try {
+          // 1. Initialize Mediasoup Device
+          this.device = new Device();
+          await this.device.load({ routerRtpCapabilities: res.rtpCapabilities });
+
+          // 2. Setup Transports and Media
+          await this._setupSendTransport(roomId);
+          await this._setupRecvTransport(roomId, res.existingProducers || []);
+
+          this.emit('joined', res);
+          resolve(res);
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  /**
+   * Mute the microphone stream
+   */
+  async mute() {
+    if (this.audioProducer) {
+      await this.audioProducer.pause();
+      this.socket.emit('mute', { roomId: this.roomId });
+      this.emit('local-mute-changed', true);
+    }
+  }
+
+  /**
+   * Unmute the microphone stream
+   */
+  async unmute() {
+    if (this.audioProducer) {
+      await this.audioProducer.resume();
+      this.socket.emit('unmute', { roomId: this.roomId });
+      this.emit('local-mute-changed', false);
+    }
+  }
+
+  /**
+   * Leave current room and clean up media and signaling state
+   */
+  async leaveRoom() {
+    if (this.roomId && this.socket) {
+      this.socket.emit('leave-room', { roomId: this.roomId });
+    }
+
+    if (this.localStream) {
+      this.localStream.getTracks().forEach(track => track.stop());
+      this.localStream = null;
+    }
+
+    if (this.sendTransport) {
+      try { this.sendTransport.close(); } catch (_) {}
+      this.sendTransport = null;
+    }
+
+    if (this.recvTransport) {
+      try { this.recvTransport.close(); } catch (_) {}
+      this.recvTransport = null;
+    }
+
+    if (this.audioProducer) {
+      try { this.audioProducer.close(); } catch (_) {}
+      this.audioProducer = null;
+    }
+
+    this.consumers.forEach(consumer => {
+      try { consumer.close(); } catch (_) {}
+    });
+    this.consumers.clear();
+    this.device = null;
+    this.roomId = null;
+  }
+
+  /**
+   * Disconnect entirely from signaling server
+   */
+  disconnect() {
+    this.leaveRoom();
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+  }
+
+  // --- Internal WebRTC Helpers ---
+
+  async _setupSendTransport(roomId) {
+    return new Promise((resolve) => {
+      this.socket.emit('create-transport', { roomId, direction: 'send' }, async (sendRes) => {
+        if (sendRes?.error) throw new Error(sendRes.error);
+
+        this.sendTransport = this.device.createSendTransport(sendRes.params);
+
+        this.sendTransport.on('connect', ({ dtlsParameters }, callback, errback) => {
+          this.socket.emit('connect-transport', { roomId, transportId: this.sendTransport.id, dtlsParameters }, (connRes) => {
+            if (connRes?.error) errback(connRes.error);
+            else callback();
+          });
+        });
+
+        this.sendTransport.on('produce', ({ kind, rtpParameters }, callback, errback) => {
+          this.socket.emit('produce', { roomId, transportId: this.sendTransport.id, kind, rtpParameters }, (prodRes) => {
+            if (prodRes?.error) errback(prodRes.error);
+            else callback({ id: prodRes.id });
+          });
+        });
+
+        // Initialize Local Capture
+        try {
+          this.localStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
+          const track = this.localStream.getAudioTracks()[0];
+          if (track) {
+            this.audioProducer = await this.sendTransport.produce({ track });
+          }
+        } catch (err) {
+          this.emit('warning', 'Microphone access denied or unavailable. Joined in listen-only mode.');
+        }
+
+        resolve();
+      });
+    });
+  }
+
+  async _setupRecvTransport(roomId, existingProducers) {
+    return new Promise((resolve) => {
+      this.socket.emit('create-transport', { roomId, direction: 'recv' }, async (recvRes) => {
+        if (recvRes?.error) throw new Error(recvRes.error);
+
+        this.recvTransport = this.device.createRecvTransport(recvRes.params);
+
+        this.recvTransport.on('connect', ({ dtlsParameters }, callback, errback) => {
+          this.socket.emit('connect-transport', { roomId, transportId: this.recvTransport.id, dtlsParameters }, (connRes) => {
+            if (connRes?.error) errback(connRes.error);
+            else callback();
+          });
+        });
+
+        // Consume all initial users
+        for (const p of existingProducers) {
+          await this._consumeProducer(p.producerId, p.userId);
+        }
+
+        resolve();
+      });
+    });
+  }
+
+  async _consumeProducer(producerId, userId) {
+    if (!this.device || !this.recvTransport) return;
+
+    this.socket.emit('consume', {
+      roomId: this.roomId,
+      transportId: this.recvTransport.id,
+      producerId,
+      rtpCapabilities: this.device.rtpCapabilities
+    }, async (res) => {
+      if (res?.error) return;
+
+      const consumer = await this.recvTransport.consume({
+        id: res.id,
+        producerId: res.producerId,
+        kind: res.kind,
+        rtpParameters: res.rtpParameters
+      });
+
+      this.consumers.set(consumer.id, consumer);
+
+      this.socket.emit('resume-consumer', { roomId: this.roomId, consumerId: consumer.id }, (resumedRes) => {
+        if (resumedRes?.error) return;
+
+        const stream = new MediaStream([consumer.track]);
+        this.emit('track', { track: consumer.track, stream, userId, consumerId: consumer.id });
+      });
+    });
+  }
+}