@droponair/sdk-js 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.17.0], 2026-05-22
+
+### Added
+
+- **SFU media transport (opt-in per room).** Two new `RoomPolicy` fields choose how a room's live call moves media: `mediaMode: 'MESH' | 'SFU'` (default `'MESH'`) and `mediaEncryption: 'E2EE' | 'SFU'` (default `'E2EE'`). Mesh stays peer-to-peer; SFU routes through the platform's media server, suited to larger calls. With `E2EE` the media server forwards traffic it cannot decrypt, so the platform stays a blind relay even in routed mode.
+- **`getSfuToken(roomId)`** - fetches a short-lived access token to join a room's SFU media. Returns `{ url, token, room, mediaEncryption, expiresAt }`. Hand the URL + token to your SFU client (e.g. LiveKit) to connect; mesh-mode rooms don't need this call. New `SfuToken` type exported from the package root.
+
+### Notes
+
+- The SFU is one transport option you compose per room - mesh remains the default and is fine for small calls. SFU mode is required only when the participant count outgrows mesh or when you need server-side recording (`mediaEncryption: 'SFU'`).
+
+---
+
 ## [0.16.0], 2026-05-21
 
 ### Added

package/README.md

@@ -312,8 +312,9 @@ Available since SDK `0.14.0`. A **room** is an addressable container a live mult
 | `deleteRoom(roomId)` | `Promise<void>` | Delete a room (creator only) |
 | `joinRoom(roomId)` | `Promise<string>` | Join the room's live call, returns callId |
 | `leaveRoom(callId)` | `Promise<void>` | Leave the room's live call |
+| `getSfuToken(roomId)` | `Promise<SfuToken>` | Token to join the room's SFU media (SFU-mode rooms only) |
 
-Room policy (`RoomPolicy`, all optional): `waitingRoom` (non-hosts wait for host admit), `requireHost` (non-hosts cannot open the call), `maxParticipants` (per-room cap), `autoCloseWhenEmpty` (room flips to `CLOSED` when the last participant leaves).
+Room policy (`RoomPolicy`, all optional): `waitingRoom` (non-hosts wait for host admit), `requireHost` (non-hosts cannot open the call), `maxParticipants` (per-room cap), `autoCloseWhenEmpty` (room flips to `CLOSED` when the last participant leaves), `mediaMode` (`'MESH'` default | `'SFU'`), `mediaEncryption` (`'E2EE'` default | `'SFU'`).
 
 ```typescript
 const room = await client.createRoom({
@@ -362,6 +363,23 @@ client.onGroupCallEvent((e) => {
 
 Audience members are receive-only by convention: on `GROUP_CALL_ROLE_CHANGED` to `AUDIENCE`, your app simply does not publish a local media track. The platform signals the role; your app owns the WebRTC tracks.
 
+### Routed media (SFU)
+
+Available since SDK `0.17.0`. A room can opt out of peer-to-peer mesh and route its live-call media through the platform's media server. Set `policy.mediaMode` to `'SFU'` at create time, then ask the SDK for a join token; hand the token to your SFU client (e.g. LiveKit) to connect. `policy.mediaEncryption` controls whether the media server can decrypt the media: `'E2EE'` (default) keeps the platform blind, `'SFU'` lets the server terminate media so it can be recorded server-side.
+
+```typescript
+const room = await client.createRoom({
+  name: 'All hands',
+  policy: { mediaMode: 'SFU', mediaEncryption: 'E2EE' },
+});
+
+const sfu = await client.getSfuToken(room.roomId);
+// sfu = { url, token, room, mediaEncryption, expiresAt }
+// connect with your SFU client using sfu.url + sfu.token
+```
+
+Mesh remains the default; only switch to SFU once the participant count outgrows mesh or you specifically need server-side recording. The `getSfuToken` call returns `409` for mesh-mode rooms and `503` if the media server is not available.
+
 ### Call Recording
 
 Available since SDK `0.16.0`. The SDK **signals** recording state on a group or room call; your app does the actual media capture (`MediaRecorder`) and uploads the file to your own storage — the platform never holds the media. The recording signal is broadcast to every participant (including anyone who joins later); that transparency is enforced server-side.

package/dist/core/messaging-client.d.ts

@@ -1,6 +1,6 @@
 import { CryptoService } from '../crypto/crypto-service';
 import { SessionManager } from './session-manager';
-import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback } from './types';
 import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from '../attachment/attachment-types';
 export declare class MessagingClient implements DropOnAirClient {
     private readonly options;
@@ -233,6 +233,7 @@ export declare class MessagingClient implements DropOnAirClient {
     getRoom(roomId: string): Promise<Room>;
     updateRoom(roomId: string, update: UpdateRoomOptions): Promise<Room>;
     deleteRoom(roomId: string): Promise<void>;
+    getSfuToken(roomId: string): Promise<SfuToken>;
     /**
      * Join the live call in a room. Resolves with the callId once joined; that
      * callId works with the existing group-call signaling methods (pass an empty

package/dist/core/messaging-client.js

@@ -1018,6 +1018,13 @@ class MessagingClient {
         if (!res.ok)
             throw new Error(`deleteRoom failed (HTTP ${res.status})`);
     }
+    async getSfuToken(roomId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/rooms/${encodeURIComponent(roomId)}/sfu-token`, { method: 'POST', headers: { Authorization: `Bearer ${jwt}` } });
+        if (!res.ok)
+            throw new Error(`getSfuToken failed (HTTP ${res.status})`);
+        return res.json();
+    }
     /**
      * Join the live call in a room. Resolves with the callId once joined; that
      * callId works with the existing group-call signaling methods (pass an empty

package/dist/core/types.d.ts

@@ -165,6 +165,30 @@ export interface RoomPolicy {
      * hand to be promoted. Mesh-scale - suited to panels and small stages.
      */
     stageMode?: boolean;
+    /**
+     * Media transport for the room's live call. 'MESH' (default) is peer-to-peer;
+     * 'SFU' routes media through the platform's media server, suited to larger calls.
+     */
+    mediaMode?: 'MESH' | 'SFU';
+    /**
+     * Media encryption for an SFU-mode call. 'E2EE' (default) keeps media encrypted
+     * past the media server; 'SFU' lets the server terminate media (enables
+     * server-side recording). Ignored when mediaMode is 'MESH'.
+     */
+    mediaEncryption?: 'E2EE' | 'SFU';
+}
+/** Access credentials to join a room's SFU (routed) media. Returned by getSfuToken. */
+export interface SfuToken {
+    /** WebSocket URL of the media server to connect your SFU client to. */
+    url: string;
+    /** Signed, short-lived access token for the media room. */
+    token: string;
+    /** Media room name to join. */
+    room: string;
+    /** Media encryption in effect for the room: 'E2EE' or 'SFU'. */
+    mediaEncryption: 'E2EE' | 'SFU';
+    /** Token expiry, Unix epoch millis. */
+    expiresAt: number;
 }
 export interface Room {
     roomId: string;
@@ -492,6 +516,12 @@ export interface DropOnAirClient {
     joinRoom(roomId: string): Promise<string>;
     /** Leave the live call in a room. */
     leaveRoom(callId: string): Promise<void>;
+    /**
+     * Fetch an access token to join a room's SFU (routed) media. Only valid for
+     * rooms whose policy sets mediaMode 'SFU'; mesh-mode rooms run peer-to-peer
+     * and need no token. Hand the returned url + token to your SFU client.
+     */
+    getSfuToken(roomId: string): Promise<SfuToken>;
     /** Raise your hand to request promotion to speaker (any participant). */
     raiseHand(callId: string): void;
     /** Lower your previously raised hand. */

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { InitializeOptions, DropOnAirClient } from './core/types';
 export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version';
 export declare function initialize(options: InitializeOptions): Promise<DropOnAirClient>;
-export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, Room, RoomPolicy, CreateRoomOptions, UpdateRoomOptions, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, NotificationClearEvent, NotificationClearCallback, DraftSyncEvent, DraftSyncCallback, } from './core/types';
+export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, Room, RoomPolicy, CreateRoomOptions, UpdateRoomOptions, SfuToken, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, NotificationClearEvent, NotificationClearCallback, DraftSyncEvent, DraftSyncCallback, } from './core/types';
 export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
 declare const _default: {
     initialize: typeof initialize;

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-export declare const SDK_VERSION = "0.16.0";
+export declare const SDK_VERSION = "0.17.0";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.16.0';
+exports.SDK_VERSION = '0.17.0';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",