# Changelog

All notable changes to the ODIN Node.js SDK will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.11.0] - 2026-01-14

This major update brings the ODIN Node.js bindings to SDK version 1.8.2 and includes a significant internal rewrite to support the latest ODIN SDK features like End-to-End Encryption.

### Breaking Changes

- **Token Generation**: Access tokens are no longer generated in the native layer (as of SDK 1.8.2). Use the new `OdinClient.generateToken(accessKey, roomId, userId)` method which leverages `@4players/odin-tokens`.
- **Room Creation**: Direct instantiation with `new OdinRoom(token)` is discouraged. Use `OdinClient.createRoom(token)` or `OdinClient.createRoomWithToken(token)` factory methods to ensure proper JavaScript event wrapping.
- **Audio Stream Creation**: `createAudioStream()` now requires explicit `sampleRate` and `channels` parameters, with optional `apmSettings`.
- **Event Payload Changes**: Standardized on `Joined` event name (matching core SDK). Removed `RoomJoined` alias and duplicate `RoomLeft` event. The `Joined` event provides `roomId`, `ownPeerId`, `room` object, and `mediaIds` array.

### Added

- **End-to-End Encryption (E2EE)**: Full support for `OdinCipher` to protect audio data and messages between peers.
- **OdinClient Factory Pattern**: New recommended way to create rooms via `client.createRoom(token)` or `client.createRoomWithToken(token)`.
- **High-Level Audio API**: Simplified audio streaming with automatic setup:
  - `media.sendMP3(filePath)` - Stream MP3 files with automatic decoding
  - `media.sendWAV(filePath)` - Stream WAV files with automatic decoding  
  - `media.sendBuffer(audioBuffer)` - Stream decoded AudioBuffer
- **Diagnostic & Monitoring Methods**:
  - `room.getConnectionStats()` - RTT and packet loss metrics
  - `room.getConnectionId()` - Retrieve connection identifier
  - `room.getJitterStats(mediaId)` - Jitter buffer statistics for audio streams
  - `cipher.getPeerStatus(peerId)` - E2EE verification status for peers
- **Convenience Event Handlers**: Typed methods for common events:
  - `onJoined`, `onLeft`
  - `onPeerJoined`, `onPeerLeft`
  - `onMediaStarted`, `onMediaStopped`
  - `onMediaActivity` (Voice Activity Detection)
  - `onMessageReceived`
  - `onAudioDataReceived`
  - `onPeerUserDataChanged`, `onRoomUserDataChanged`
  - `onPeerTagsChanged`
- **Removed RoomJoined Alias**: `RoomJoined` was previously supported as an alias for `Joined`. This has been removed to match core SDK naming. Use `Joined` event (or `onJoined()` convenience method) exclusively.
- **Synchronous Event Polling**: `room.pollEvents()` for processing server events on the main thread.
- **TypeScript Definitions**: Comprehensive type definitions for all event payloads in `odin.room.d.ts`.

### Changed

- **SDK Initialization**: Refactored internal initialization with `OdinClient` as the primary entry point.
- **Audio Output**: Fixed stereo recording capability with proper interleaved samples.

### Deprecated

- `generateAccessToken()` - Use `generateToken()` instead.
- `createRoomWithAccessToken()` - Use `createRoomWithToken()` instead.

### Fixed

- **Audio Transmission**: Resolved ErrorCode=-3 issues where transmitters weren't using server-allocated media IDs.
- **SDK Lifecycle**: Fixed premature `odin_shutdown()` during garbage collection with proper reference counting.
- **Spatial Audio**: `setPositionScale()` and `updatePosition()` now correctly apply coordinates set before `join()`.
- **Event Dispatching**: Corrected missing `mediaId` and `userData` in events.
- **macOS ARM64 Stability**: Resolved `SIGBUS` and `SIGSEGV` crashes during high-frequency audio transmission using main-thread poll pattern.
- **Null Safety**: Fixed potential crashes when handling peers without user data.

## [0.10.3] - Previous Release

See git history for earlier changes.

[Unreleased]: https://github.com/4Players/odin-nodejs/compare/v0.11.0...HEAD
[0.11.0]: https://github.com/4Players/odin-nodejs/compare/v0.10.3...v0.11.0
[0.10.3]: https://github.com/4Players/odin-nodejs/releases/tag/v0.10.3