@droponair/sdk-js 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.18.0], 2026-05-23
+
+### Added
+
+- **SFU recording (Phase 3.7.5).** Server-side recording for SFU-mode rooms with `mediaEncryption: 'SFU'`. The platform's media server records the composite of every track in the room and uploads the finalized file directly to the customer's storage bucket - the platform never holds the recorded bytes. Storage destinations (S3 / GCS / Azure) are registered once in the panel; the SDK references each by an opaque `destinationId`.
+- Three new client methods:
+  - `startSfuRecording(roomId, destinationId)` -> `SfuRecording`
+  - `stopSfuRecording(roomId, recordingId)` -> `SfuRecording`
+  - `listSfuRecordings(roomId)` -> `SfuRecording[]`
+- New `SfuRecording` type exported from the package root.
+- Completion is also observable via the new runtime webhooks: `sfu-recording.started`, `sfu-recording.completed`, `sfu-recording.failed`.
+
+### Notes
+
+- Only rooms with both `policy.mediaMode: 'SFU'` and `policy.mediaEncryption: 'SFU'` are server-recordable; E2EE-encrypted SFU rooms cannot be recorded by design (the media server forwards traffic it cannot decrypt). For E2EE rooms, continue using the client-side `startRecording` (0.16.0).
+
+---
+
 ## [0.17.0], 2026-05-22
 
 ### Added

package/README.md

@@ -313,6 +313,9 @@ Available since SDK `0.14.0`. A **room** is an addressable container a live mult
 | `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) |
+| `startSfuRecording(roomId, destinationId)` | `Promise<SfuRecording>` | Start server-side recording (SFU + `mediaEncryption: 'SFU'` only) |
+| `stopSfuRecording(roomId, recordingId)` | `Promise<SfuRecording>` | Stop a running SFU recording |
+| `listSfuRecordings(roomId)` | `Promise<SfuRecording[]>` | List SFU recordings for a room, newest first |
 
 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'`).
 
@@ -380,6 +383,20 @@ const sfu = await client.getSfuToken(room.roomId);
 
 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.
 
+### SFU recording
+
+Available since SDK `0.18.0`. Server-side recording for SFU-mode rooms with `mediaEncryption: 'SFU'`. The platform's media server captures the room composite and uploads the finalized file directly to your storage bucket (S3, GCS, or Azure); the platform never holds the recorded bytes. Storage destinations are registered in the panel; the SDK references each by an opaque `destinationId`.
+
+```typescript
+const rec = await client.startSfuRecording(room.roomId, 'dst_aBc123');
+// { recordingId, status: 'STARTING', startedAt, ... }
+
+// Later, when the host ends the recording:
+await client.stopSfuRecording(room.roomId, rec.recordingId);
+```
+
+Completion lands as the `sfu-recording.completed` webhook (or by polling `listSfuRecordings`) and carries `locationUri` pointing at the finalized file in your bucket. E2EE-encrypted SFU rooms cannot be server-recorded by design (the media server forwards traffic it cannot decrypt) - use the client-side `startRecording` for those.
+
 ### 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, SfuToken, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, SfuRecording, 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;
@@ -234,6 +234,9 @@ export declare class MessagingClient implements DropOnAirClient {
     updateRoom(roomId: string, update: UpdateRoomOptions): Promise<Room>;
     deleteRoom(roomId: string): Promise<void>;
     getSfuToken(roomId: string): Promise<SfuToken>;
+    startSfuRecording(roomId: string, destinationId: string): Promise<SfuRecording>;
+    stopSfuRecording(roomId: string, recordingId: string): Promise<SfuRecording>;
+    listSfuRecordings(roomId: string): Promise<SfuRecording[]>;
     /**
      * 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

@@ -1025,6 +1025,31 @@ class MessagingClient {
             throw new Error(`getSfuToken failed (HTTP ${res.status})`);
         return res.json();
     }
+    async startSfuRecording(roomId, destinationId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/rooms/${encodeURIComponent(roomId)}/sfu-recordings`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ destinationId }),
+        });
+        if (!res.ok)
+            throw new Error(`startSfuRecording failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async stopSfuRecording(roomId, recordingId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/rooms/${encodeURIComponent(roomId)}/sfu-recordings/${encodeURIComponent(recordingId)}`, { method: 'DELETE', headers: { Authorization: `Bearer ${jwt}` } });
+        if (!res.ok)
+            throw new Error(`stopSfuRecording failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async listSfuRecordings(roomId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/rooms/${encodeURIComponent(roomId)}/sfu-recordings`, { method: 'GET', headers: { Authorization: `Bearer ${jwt}` } });
+        if (!res.ok)
+            throw new Error(`listSfuRecordings 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

@@ -190,6 +190,30 @@ export interface SfuToken {
     /** Token expiry, Unix epoch millis. */
     expiresAt: number;
 }
+/**
+ * A server-side recording of an SFU-mode room (Phase 3.7.5). The platform
+ * never holds the recorded bytes - LiveKit Egress uploads the finalized file
+ * directly to the destination configured in the panel under `destinationId`.
+ */
+export interface SfuRecording {
+    /** Opaque ID; pass to stopSfuRecording. */
+    recordingId: string;
+    roomId: string;
+    /** ID of the panel-registered RecordingDestination this recording targets. */
+    destinationId: string;
+    /** Lifecycle state. */
+    status: 'STARTING' | 'ACTIVE' | 'STOPPING' | 'COMPLETED' | 'FAILED';
+    /** Unix epoch millis when the recording was kicked off. */
+    startedAt: number | null;
+    /** Populated once Egress finalizes the file (COMPLETED or FAILED). */
+    finishedAt: number | null;
+    durationSeconds: number | null;
+    fileSizeBytes: number | null;
+    /** Customer-side URI of the finalized file (e.g. s3://bucket/path.mp4). */
+    locationUri: string | null;
+    /** Populated when status is FAILED. */
+    errorMessage: string | null;
+}
 export interface Room {
     roomId: string;
     name: string;
@@ -522,6 +546,19 @@ export interface DropOnAirClient {
      * and need no token. Hand the returned url + token to your SFU client.
      */
     getSfuToken(roomId: string): Promise<SfuToken>;
+    /**
+     * Start a server-side recording of an SFU-mode room. The destination is a
+     * RecordingDestination pre-registered in the panel; the platform never
+     * holds the recorded bytes, LiveKit Egress uploads directly. Only valid
+     * when the room's policy sets mediaEncryption 'SFU' (E2EE rooms cannot
+     * be server-recorded). Completion is observable via the
+     * sfu-recording.completed webhook or by polling listSfuRecordings.
+     */
+    startSfuRecording(roomId: string, destinationId: string): Promise<SfuRecording>;
+    /** Stop a running SFU recording. Idempotent on terminal status. */
+    stopSfuRecording(roomId: string, recordingId: string): Promise<SfuRecording>;
+    /** List SFU recordings for a room, most-recent first. */
+    listSfuRecordings(roomId: string): Promise<SfuRecording[]>;
     /** 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, SfuToken, 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, SfuRecording, 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.17.0";
+export declare const SDK_VERSION = "0.18.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.17.0';
+exports.SDK_VERSION = '0.18.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.17.0",
+  "version": "0.18.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",