@4players/odin-nodejs 0.10.3 → 0.11.1

package/tests/connection-test/README.md

@@ -0,0 +1,97 @@
+# ODIN Connection Test Example
+
+This example demonstrates how to connect to an ODIN room and use the SDK's event system and diagnostic methods.
+
+## Features Demonstrated
+
+- **Room Connection**: Connecting to an ODIN room using the factory pattern
+- **Event Handling**: All major event types (Joined, PeerJoined, MediaStarted, etc.)
+- **End-to-End Encryption**: Optional E2EE configuration with OdinCipher
+- **Diagnostic Methods**: Connection stats, jitter stats, and peer encryption status
+
+## Prerequisites
+
+You need an ODIN access key. Get one for free at [4Players ODIN](https://docs.4players.io/voice/introduction/access-keys/).
+
+## Configuration
+
+Edit `index.js` and replace the placeholder values:
+
+```javascript
+const accessKey = "__YOUR_ACCESS_KEY__";  // Your ODIN access key
+const roomId = "__YOUR_ROOM_ID__";        // Room to join
+const userId = "TestUser-123";            // Your user ID
+```
+
+To enable E2EE, set a password:
+
+```javascript
+const cipherPassword = "my-secret-password";  // All peers must use the same password
+```
+
+## Running the Example
+
+```bash
+cd tests/connection-test
+node index.js
+```
+
+## What This Example Does
+
+1. **Initializes** the ODIN client
+2. **Generates** a room token from your access key
+3. **Configures** E2EE (if password is set)
+4. **Sets up** event handlers for all room events
+5. **Joins** the room and waits for 15 seconds
+6. **Runs** diagnostic tests:
+   - `getConnectionId()` - Connection identifier
+   - `getConnectionStats()` - RTT, packet loss, bandwidth
+   - `getJitterStats()` - Audio jitter buffer metrics
+   - `getPeerStatus()` - E2EE peer verification
+7. **Closes** the room and exits
+
+## Expected Output
+
+```
+=== ODIN NodeJS SDK Connection Test ===
+
+1. Initializing Odin Client...
+2. Generating token from access key...
+   Token generated successfully.
+
+3. Setting up Cipher (E2EE)...
+   E2EE disabled (no password configured).
+
+4. Creating Room via client.createRoom()...
+5. Setting up event handlers...
+
+6. Joining room...
+   Join initiated.
+
+[Event] ConnectionStateChanged: Connecting
+[Event] ConnectionStateChanged: Joined
+[Event] Joined room!
+   Room ID: my-room
+   Own Peer ID: 12345
+   Available Media IDs: [1, 2, 3, 4]
+
+8. Testing diagnostic methods...
+
+   8a. getConnectionId():
+       Connection ID: 567890
+       ✅ Connection ID retrieved successfully
+
+   8b. getConnectionStats():
+       ✅ Connection stats retrieved:
+       - RTT:              25.50 ms
+       - TX Bytes:         1234
+       - RX Bytes:         5678
+       ...
+
+=== Test Complete ===
+```
+
+## Related Examples
+
+- [audio-recording](../audio-recording/) - Record audio from peers
+- [sending-audio](../sending-audio/) - Send audio to the room

package/tests/connection-test/index.js

@@ -0,0 +1,273 @@
+/**
+ * ODIN Node.js SDK - Connection Test Example
+ * 
+ * This example demonstrates how to:
+ * - Connect to an ODIN room using the SDK
+ * - Handle various room and peer events
+ * - Use the new diagnostic methods (getConnectionStats, getJitterStats, etc.)
+ * - Configure End-to-End Encryption (E2EE) with OdinCipher
+ * 
+ * Prerequisites:
+ * - Replace __YOUR_ACCESS_KEY__ with your ODIN access key
+ * - Get a free access key at https://www.4players.io/odin
+ */
+
+import odin from '../../index.cjs';
+const { OdinClient, OdinCipher } = odin;
+
+// ============================================
+// Configuration - Replace with your values
+// ============================================
+
+/** 
+ * Your ODIN access key. Get one for free at https://www.4players.io/odin
+ * @type {string}
+ */
+const accessKey = "__YOUR_ACCESS_KEY__";
+
+/**
+ * The room ID to join. All users joining the same room can communicate.
+ * @type {string}
+ */
+const roomId = "__YOUR_ROOM_ID__";
+
+/**
+ * Your unique user identifier. Used to identify this connection.
+ * @type {string}
+ */
+const userId = "TestUser-" + Math.floor(Math.random() * 10000);
+
+/**
+ * Optional: Password for End-to-End Encryption. 
+ * Set to null to disable E2EE, or set a string that all peers must share.
+ * @type {string|null}
+ */
+const cipherPassword = null;
+
+// ============================================
+// Main Test Function
+// ============================================
+
+async function run() {
+    console.log("=== ODIN NodeJS SDK Connection Test ===\n");
+
+    // Step 1: Create the ODIN client
+    console.log("1. Initializing Odin Client...");
+    const client = new OdinClient();
+
+    // Step 2: Generate token locally using access key
+    // This replaces the old REST API token creation method
+    console.log("2. Generating token from access key...");
+    const token = client.generateToken(accessKey, roomId, userId);
+    console.log("   Token generated successfully.\n");
+
+    // Step 3: Set up E2EE cipher (optional)
+    console.log("3. Setting up Cipher (E2EE)...");
+    let cipher = null;
+    try {
+        if (cipherPassword && typeof OdinCipher === 'function') {
+            cipher = new OdinCipher();
+            const key = new TextEncoder().encode(cipherPassword);
+            cipher.setPassword(key);
+            console.log("   Cipher created and password set.\n");
+        } else {
+            console.log("   E2EE disabled (no password configured).\n");
+        }
+    } catch (e) {
+        console.log("   OdinCipher creation failed:", e.message, "\n");
+    }
+
+    // Step 4: Create room using factory pattern (recommended)
+    console.log("4. Creating Room via client.createRoom()...");
+    const room = client.createRoom(token);
+    if (cipher) {
+        room.setCipher(cipher);
+    }
+
+    // Step 5: Set up event handlers
+    console.log("5. Setting up event handlers...\n");
+
+    // Connection state handler - tracks connection lifecycle
+    room.onConnectionStateChanged((event) => {
+        console.log(`[Event] ConnectionStateChanged: ${event.state}${event.message ? ` (${event.message})` : ''}`);
+    });
+
+    // Joined handler - fires when successfully connected to the room
+    room.onJoined((event) => {
+        console.log("[Event] Joined room!");
+        console.log(`   Room ID: ${event.roomId}`);
+        console.log(`   Own Peer ID: ${event.ownPeerId}`);
+        console.log(`   Available Media IDs: ${JSON.stringify(event.mediaIds)}`);
+        if (event.room?.peers?.length > 0) {
+            console.log(`   Existing peers: ${event.room.peers.length}`);
+        }
+    });
+
+    // Left handler - fires when disconnected from room
+    room.onLeft((event) => {
+        console.log(`[Event] Left room. Reason: ${event.reason}`);
+    });
+
+    // Peer joined handler - fires when another user joins
+    room.onPeerJoined((event) => {
+        console.log(`[Event] Peer joined: ID=${event.peerId}, UserID=${event.userId}`);
+        if (event.userData) {
+            try {
+                const userData = JSON.parse(new TextDecoder().decode(new Uint8Array(event.userData)));
+                console.log(`   User data:`, userData);
+            } catch (e) {
+                console.log(`   User data: (binary, ${event.userData?.length || 0} bytes)`);
+            }
+        }
+    });
+
+    // Peer left handler - fires when another user leaves
+    room.onPeerLeft((event) => {
+        console.log(`[Event] Peer left: ID=${event.peerId}`);
+    });
+
+    // Media started handler - fires when a peer starts streaming audio
+    room.onMediaStarted((event) => {
+        console.log(`[Event] Media started: Peer=${event.peerId}, MediaID=${event.media?.id}`);
+    });
+
+    // Media stopped handler - fires when a peer stops streaming
+    room.onMediaStopped((event) => {
+        console.log(`[Event] Media stopped: Peer=${event.peerId}, MediaID=${event.mediaId}`);
+    });
+
+    // Message received handler - fires when a peer sends a message
+    room.onMessageReceived((event) => {
+        console.log(`[Event] Message received from Peer=${event.senderPeerId}`);
+        try {
+            const message = JSON.parse(new TextDecoder().decode(new Uint8Array(event.message)));
+            console.log(`   Message:`, message);
+        } catch (e) {
+            console.log(`   Message: (binary, ${event.message?.length || 0} bytes)`);
+        }
+    });
+
+    // Audio data handler - fires for each audio frame received
+    // Note: This fires frequently, so we only log occasionally to avoid spam
+    room.onAudioDataReceived((data) => {
+        if (Math.random() < 0.01) {
+            console.log(`[Event] Audio data: MediaID=${data.mediaId}, samples=${data.samples16?.length || 0}`);
+        }
+    });
+
+    // Step 6: Join the room
+    console.log("6. Joining room...");
+    try {
+        room.join("https://gateway.odin.4players.io");
+        console.log("   Join initiated.\n");
+    } catch (e) {
+        console.error("   Join failed:", e.message);
+        process.exit(1);
+    }
+
+    // Step 7: Wait for connection to establish and events to arrive
+    console.log("7. Waiting 15 seconds for events...\n");
+    await new Promise(resolve => setTimeout(resolve, 15000));
+
+    // =========================================
+    // Step 8: Test Diagnostic Methods
+    // =========================================
+    console.log("\n8. Testing diagnostic methods...\n");
+
+    // Test getConnectionId() - retrieves the underlying connection identifier
+    console.log("   8a. getConnectionId():");
+    try {
+        const connectionId = room.getConnectionId();
+        console.log(`       Connection ID: ${connectionId}`);
+        if (connectionId === 0) {
+            console.log("       ⚠️  Connection ID is 0 (might indicate disconnected state)");
+        } else {
+            console.log("       ✅ Connection ID retrieved successfully");
+        }
+    } catch (e) {
+        console.log(`       ❌ Error: ${e.message}`);
+    }
+
+    // Test getConnectionStats() - retrieves network quality metrics
+    console.log("\n   8b. getConnectionStats():");
+    try {
+        const stats = room.getConnectionStats();
+        if (stats) {
+            console.log("       ✅ Connection stats retrieved:");
+            console.log(`       - RTT:              ${stats.rtt.toFixed(2)} ms`);
+            console.log(`       - TX Datagrams:     ${stats.udpTxDatagrams}`);
+            console.log(`       - TX Bytes:         ${stats.udpTxBytes}`);
+            console.log(`       - TX Loss:          ${(stats.udpTxLoss * 100).toFixed(2)}%`);
+            console.log(`       - RX Datagrams:     ${stats.udpRxDatagrams}`);
+            console.log(`       - RX Bytes:         ${stats.udpRxBytes}`);
+            console.log(`       - RX Loss:          ${(stats.udpRxLoss * 100).toFixed(2)}%`);
+            console.log(`       - Cwnd:             ${stats.cwnd}`);
+            console.log(`       - Congestion Events: ${stats.congestionEvents}`);
+        } else {
+            console.log("       ⚠️  Stats returned null (room might be disconnected)");
+        }
+    } catch (e) {
+        console.log(`       ❌ Error: ${e.message}`);
+    }
+
+    // Test getJitterStats() - retrieves audio jitter buffer statistics
+    console.log("\n   8c. getJitterStats(mediaId):");
+    try {
+        // Try to get jitter stats for media ID 1 (may not exist if no audio received)
+        const jitterStats = room.getJitterStats(1);
+        if (jitterStats) {
+            console.log("       ✅ Jitter stats retrieved for media ID 1:");
+            console.log(`       - Packets Total:      ${jitterStats.packetsTotal}`);
+            console.log(`       - Packets Buffered:   ${jitterStats.packetsBuffered}`);
+            console.log(`       - Packets Processed:  ${jitterStats.packetsProcessed}`);
+            console.log(`       - Packets Too Early:  ${jitterStats.packetsArrivedTooEarly}`);
+            console.log(`       - Packets Too Late:   ${jitterStats.packetsArrivedTooLate}`);
+            console.log(`       - Packets Dropped:    ${jitterStats.packetsDropped}`);
+            console.log(`       - Packets Invalid:    ${jitterStats.packetsInvalid}`);
+            console.log(`       - Packets Repeated:   ${jitterStats.packetsRepeated}`);
+            console.log(`       - Packets Lost:       ${jitterStats.packetsLost}`);
+        } else {
+            console.log("       ⚠️  Jitter stats returned null (no decoder for media ID 1 - this is expected if no audio received)");
+        }
+    } catch (e) {
+        console.log(`       ❌ Error: ${e.message}`);
+    }
+
+    // Test cipher.getPeerStatus() - verifies E2EE status for peers
+    console.log("\n   8d. cipher.getPeerStatus(peerId):");
+    if (cipher) {
+        try {
+            // Test with own peer ID
+            const ownPeerId = room.ownPeerId;
+            if (ownPeerId) {
+                const status = cipher.getPeerStatus(ownPeerId);
+                console.log(`       ✅ Peer status for own ID (${ownPeerId}): "${status}"`);
+            }
+
+            // Test with a non-existent peer ID
+            const unknownStatus = cipher.getPeerStatus(99999);
+            console.log(`       ✅ Peer status for unknown peer (99999): "${unknownStatus}"`);
+        } catch (e) {
+            console.log(`       ❌ Error: ${e.message}`);
+        }
+    } else {
+        console.log("       ⚠️  Cipher not available, skipping getPeerStatus test");
+    }
+
+    // Step 9: Clean up
+    console.log("\n9. Closing room...");
+    room.close();
+    console.log("   Room closed.\n");
+
+    console.log("=== Test Complete ===");
+    process.exit(0);
+}
+
+// ============================================
+// Entry Point
+// ============================================
+
+run().catch(err => {
+    console.error("Error:", err);
+    process.exit(1);
+});

package/tests/lifecycle/test-room-cycle.js

@@ -0,0 +1,169 @@
+/**
+ * ODIN Node.js SDK - Room Lifecycle Stress Test
+ * 
+ * This test mimics the user's transcription bot architecture:
+ * - Single OdinClient (singleton, lives for entire process)
+ * - Multiple rooms created/destroyed over time
+ * - MP3 playback on each join
+ * - Tests for memory leaks and native crashes
+ * 
+ * If this test completes without crashes, the SDK handles the lifecycle correctly.
+ */
+
+import odin from '../../index.cjs';
+const { OdinClient, OdinCipher } = odin;
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get the directory of the current script
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================
+// Configuration
+// ============================================
+
+const accessKey = "__YOUR_ACCESS_KEY__/kTC2Yhitf4fJSx95jpN3F9Xac3";
+const roomId = "__YOUR_ROOM_ID__";
+const cipherPassword = "__YOUR_CIPHER_PASSWORD_OR_NULL__";
+
+// Number of room create/destroy cycles
+const CYCLE_COUNT = 5;
+
+// Delay between cycles (milliseconds)
+const DELAY_BETWEEN_CYCLES = 2000;
+
+// Audio file to play (optional - skip if not found)
+const audioFile = path.join(__dirname, '../sending-audio/canBounce.mp3');
+
+// ============================================
+// Main Test Function
+// ============================================
+
+async function main() {
+    console.log("=== ODIN Node.js SDK - Room Lifecycle Stress Test ===\n");
+    console.log(`Testing ${CYCLE_COUNT} room create/destroy cycles with ${DELAY_BETWEEN_CYCLES}ms delay.\n`);
+
+    // Step 1: Create ODIN client (singleton - lives for entire test)
+    console.log("1. Creating OdinClient (singleton)...");
+    const client = new OdinClient();
+    console.log("   OdinClient created.\n");
+
+    // Run multiple cycles
+    for (let cycle = 1; cycle <= CYCLE_COUNT; cycle++) {
+        console.log(`\n========== CYCLE ${cycle}/${CYCLE_COUNT} ==========\n`);
+
+        try {
+            await runCycle(client, cycle);
+        } catch (error) {
+            console.error(`   ❌ CYCLE ${cycle} FAILED: ${error.message}`);
+            console.error(error.stack);
+            // Continue to next cycle to see if it's recoverable
+        }
+
+        // Wait between cycles
+        if (cycle < CYCLE_COUNT) {
+            console.log(`\n   ⏳ Waiting ${DELAY_BETWEEN_CYCLES}ms before next cycle...`);
+            await new Promise(r => setTimeout(r, DELAY_BETWEEN_CYCLES));
+        }
+    }
+
+    console.log("\n========== TEST COMPLETE ==========\n");
+    console.log("✅ All cycles completed without native crash!");
+    console.log("   If you see this message, the lifecycle fixes are working.\n");
+
+    process.exit(0);
+}
+
+/**
+ * Run a single room create/join/play/close cycle
+ */
+async function runCycle(client, cycleNum) {
+    const userId = `LifecycleBot-Cycle${cycleNum}-${Math.floor(Math.random() * 10000)}`;
+
+    // Step A: Generate token
+    console.log(`${cycleNum}.A Generating token...`);
+    const token = client.generateToken(accessKey, roomId, userId);
+
+    // Step B: Create room
+    console.log(`${cycleNum}.B Creating room...`);
+    const room = client.createRoom(token);
+
+    // Step C: Set up cipher (E2EE)
+    console.log(`${cycleNum}.C Setting up cipher...`);
+    const cipher = new OdinCipher();
+    cipher.setPassword(new TextEncoder().encode(cipherPassword));
+    room.setCipher(cipher);
+
+    // Step D: Set up event handlers
+    const joinPromise = new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error('Join timeout')), 10000);
+        room.onJoined((event) => {
+            clearTimeout(timeout);
+            resolve(event);
+        });
+    });
+
+    // Track if we received any audio
+    let audioPacketsReceived = 0;
+    room.onAudioDataReceived(() => {
+        audioPacketsReceived++;
+    });
+
+    // Step E: Join room
+    console.log(`${cycleNum}.D Joining room...`);
+    const userData = new TextEncoder().encode(JSON.stringify({
+        name: `Lifecycle Test Bot (Cycle ${cycleNum})`,
+        platform: "ODIN Node.js SDK"
+    }));
+    room.join("https://gateway.odin.4players.io", userData);
+
+    // Wait for join
+    const joinEvent = await joinPromise;
+    console.log(`   ✓ Joined! Peer ID: ${joinEvent.ownPeerId}, Media IDs: ${room.availableMediaIds.length}`);
+
+    // Step F: Play MP3 (if file exists)
+    let audioPlayed = false;
+    try {
+        const fs = await import('fs');
+        if (fs.existsSync(audioFile)) {
+            console.log(`${cycleNum}.E Creating audio stream and playing MP3...`);
+            const media = room.createAudioStream(44100, 2);
+            await media.sendMP3(audioFile);
+            console.log(`   ✓ MP3 playback complete`);
+
+            // Small delay before closing
+            await new Promise(r => setTimeout(r, 200));
+
+            console.log(`${cycleNum}.F Closing audio stream...`);
+            media.close();
+            console.log(`   ✓ Audio stream closed. Available IDs: ${room.availableMediaIds.length}`);
+            audioPlayed = true;
+        } else {
+            console.log(`${cycleNum}.E Skipping MP3 playback (file not found)`);
+        }
+    } catch (err) {
+        console.log(`   ⚠ MP3 playback error: ${err.message}`);
+    }
+
+    // Step G: Wait a moment to simulate session activity
+    console.log(`${cycleNum}.G Simulating session activity (500ms)...`);
+    await new Promise(r => setTimeout(r, 500));
+    console.log(`   ✓ Received ${audioPacketsReceived} audio packets`);
+
+    // Step H: Close room
+    console.log(`${cycleNum}.H Closing room...`);
+    room.close();
+    console.log(`   ✓ Room closed`);
+
+    console.log(`\n   ✅ Cycle ${cycleNum} completed successfully!`);
+}
+
+// ============================================
+// Entry Point
+// ============================================
+
+main().catch(err => {
+    console.error("\n❌ TEST FAILED WITH ERROR:", err);
+    process.exit(1);
+});