@droponair/sdk-js 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.15.0], 2026-05-21
+
+### Added
+
+- **Live stage roles & audience controls.** A room created with `policy.stageMode` runs its live call as a stage: hosts join as speakers, everyone else joins as receive-only audience. New `raiseHand` / `lowerHand` (any participant), `promoteToSpeaker` / `demoteToAudience` (host / co-host), and `submitStageQuestion` - all act on the callId from `joinRoom`. Role changes surface via `GROUP_CALL_ROLE_CHANGED` events (role `SPEAKER` / `AUDIENCE`); the room-call participant list now carries each participant's role.
+- New `GROUP_CALL_STAGE_*` event types.
+
+### Notes
+
+- Stage mode is a roles + signaling layer, the media topology is still the WebRTC mesh, suited to panels and small/medium stages. Large-audience streaming needs an SFU and is out of scope. Pure control-plane signaling; no proto change.
+
+---
+
 ## [0.14.0], 2026-05-21
 
 ### Added

package/README.md

@@ -333,6 +333,35 @@ client.sendGroupCallSignal('GROUP_CALL_SDP_OFFER', callId, '', peerUserId, sdp);
 
 `joinRoom` rejects with `HOST_REQUIRED`, `ROOM_CLOSED`, or `WAITING_ROOM_PENDING` (listen for `GROUP_CALL_WAITING_ROOM_ADMITTED`, then call `joinRoom` again).
 
+### Live Stage
+
+Available since SDK `0.15.0`. Create a room with `policy.stageMode` and its live call runs as a stage: hosts join as **speakers**, everyone else joins as receive-only **audience**. Audience can raise a hand; a host promotes them to speaker. The media topology is still the WebRTC mesh, so a stage is suited to panels and small/medium audiences - large-audience streaming needs an SFU and is out of scope.
+
+| Method | Description |
+|--------|-------------|
+| `raiseHand(callId)` | Request promotion to speaker (any participant) |
+| `lowerHand(callId)` | Lower your raised hand |
+| `promoteToSpeaker(callId, userId)` | Promote an audience member (host / co-host) |
+| `demoteToAudience(callId, userId)` | Demote a speaker (host / co-host) |
+| `submitStageQuestion(callId, text)` | Submit a text question to the stage's speakers |
+
+```typescript
+const room = await client.createRoom({ name: 'AMA', policy: { stageMode: true, requireHost: true } });
+const callId = await client.joinRoom(room.roomId);
+
+// Audience side
+client.raiseHand(callId);
+client.submitStageQuestion(callId, 'How does E2EE key rotation work?');
+
+// Host side - role changes arrive as GROUP_CALL_ROLE_CHANGED events
+client.onGroupCallEvent((e) => {
+  if (e.type === 'GROUP_CALL_STAGE_HAND_RAISED') client.promoteToSpeaker(callId, e.payload!);
+  if (e.type === 'GROUP_CALL_ROLE_CHANGED') updateStageUi(e.payload);   // {"userId","role":"SPEAKER"|"AUDIENCE"}
+});
+```
+
+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.
+
 ### Screen Sharing
 
 Available since SDK `0.6.0`. The SDK only signals start/stop - capture (via the browser's `getDisplayMedia()`) and adding the resulting `MediaStreamTrack` to the existing peer connection are the app's responsibility.

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

@@ -289,6 +289,11 @@ export declare class MessagingClient implements DropOnAirClient {
     requestWaitingRoomEntry(callId: string, groupId: string): void;
     admitFromWaitingRoom(callId: string, groupId: string, userId: string): void;
     rejectFromWaitingRoom(callId: string, groupId: string, userId: string): void;
+    raiseHand(callId: string): void;
+    lowerHand(callId: string): void;
+    promoteToSpeaker(callId: string, userId: string): void;
+    demoteToAudience(callId: string, userId: string): void;
+    submitStageQuestion(callId: string, text: string): void;
     private sendGroupCallFrame;
     /**
      * Initiate an outgoing call.

package/dist/core/messaging-client.js

@@ -1307,6 +1307,35 @@ class MessagingClient {
             payload: JSON.stringify({ userId }),
         });
     }
+    // Live stage controls (Feature 3.2). These act on a room call running in
+    // stage mode; pass the callId from joinRoom(). raiseHand / lowerHand and
+    // submitStageQuestion are open to any participant; promote / demote are
+    // host / co-host authority. Roles surface via GROUP_CALL_ROLE_CHANGED.
+    raiseHand(callId) {
+        this.sendGroupCallFrame({ type: 'GROUP_CALL_STAGE_HAND_RAISED', callId, groupId: '' });
+    }
+    lowerHand(callId) {
+        this.sendGroupCallFrame({ type: 'GROUP_CALL_STAGE_HAND_LOWERED', callId, groupId: '' });
+    }
+    promoteToSpeaker(callId, userId) {
+        this.sendGroupCallFrame({
+            type: 'GROUP_CALL_STAGE_PROMOTE',
+            callId,
+            groupId: '',
+            payload: JSON.stringify({ userId }),
+        });
+    }
+    demoteToAudience(callId, userId) {
+        this.sendGroupCallFrame({
+            type: 'GROUP_CALL_STAGE_DEMOTE',
+            callId,
+            groupId: '',
+            payload: JSON.stringify({ userId }),
+        });
+    }
+    submitStageQuestion(callId, text) {
+        this.sendGroupCallFrame({ type: 'GROUP_CALL_STAGE_QUESTION', callId, groupId: '', payload: text });
+    }
     sendGroupCallFrame(frame) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             throw new Error('DropOnAir websocket is not connected');

package/dist/core/types.d.ts

@@ -135,7 +135,7 @@ export interface DecryptedGroupMessage {
     plaintext: string;
 }
 export type GroupMessageCallback = (message: DecryptedGroupMessage) => void;
-export type GroupCallEventType = 'GROUP_CALL_INVITE' | 'GROUP_CALL_RINGING' | 'GROUP_CALL_JOIN' | 'GROUP_CALL_LEAVE' | 'GROUP_CALL_END' | 'GROUP_CALL_ENDED' | 'GROUP_CALL_PARTICIPANT_JOINED' | 'GROUP_CALL_PARTICIPANT_LEFT' | 'GROUP_CALL_PARTICIPANT_REMOVED' | 'GROUP_CALL_ALREADY_ACTIVE' | 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE' | 'GROUP_CALL_SCREEN_SHARE_STARTED' | 'GROUP_CALL_SCREEN_SHARE_STOPPED' | 'GROUP_CALL_HOST_TRANSFER' | 'GROUP_CALL_COHOST_APPOINT' | 'GROUP_CALL_COHOST_REVOKE' | 'GROUP_CALL_ROLE_CHANGED' | 'GROUP_CALL_MUTE_PARTICIPANT' | 'GROUP_CALL_REMOVE_PARTICIPANT' | 'GROUP_CALL_WAITING_ROOM_REQUEST' | 'GROUP_CALL_WAITING_ROOM_JOINED' | 'GROUP_CALL_WAITING_ROOM_ADMIT' | 'GROUP_CALL_WAITING_ROOM_ADMITTED' | 'GROUP_CALL_WAITING_ROOM_REJECT' | 'GROUP_CALL_WAITING_ROOM_REJECTED' | 'GROUP_CALL_JOINED' | 'GROUP_CALL_WAITING_ROOM_PENDING' | 'GROUP_CALL_HOST_REQUIRED' | 'GROUP_CALL_ROOM_CLOSED';
+export type GroupCallEventType = 'GROUP_CALL_INVITE' | 'GROUP_CALL_RINGING' | 'GROUP_CALL_JOIN' | 'GROUP_CALL_LEAVE' | 'GROUP_CALL_END' | 'GROUP_CALL_ENDED' | 'GROUP_CALL_PARTICIPANT_JOINED' | 'GROUP_CALL_PARTICIPANT_LEFT' | 'GROUP_CALL_PARTICIPANT_REMOVED' | 'GROUP_CALL_ALREADY_ACTIVE' | 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE' | 'GROUP_CALL_SCREEN_SHARE_STARTED' | 'GROUP_CALL_SCREEN_SHARE_STOPPED' | 'GROUP_CALL_HOST_TRANSFER' | 'GROUP_CALL_COHOST_APPOINT' | 'GROUP_CALL_COHOST_REVOKE' | 'GROUP_CALL_ROLE_CHANGED' | 'GROUP_CALL_MUTE_PARTICIPANT' | 'GROUP_CALL_REMOVE_PARTICIPANT' | 'GROUP_CALL_WAITING_ROOM_REQUEST' | 'GROUP_CALL_WAITING_ROOM_JOINED' | 'GROUP_CALL_WAITING_ROOM_ADMIT' | 'GROUP_CALL_WAITING_ROOM_ADMITTED' | 'GROUP_CALL_WAITING_ROOM_REJECT' | 'GROUP_CALL_WAITING_ROOM_REJECTED' | 'GROUP_CALL_JOINED' | 'GROUP_CALL_WAITING_ROOM_PENDING' | 'GROUP_CALL_HOST_REQUIRED' | 'GROUP_CALL_ROOM_CLOSED' | 'GROUP_CALL_STAGE_HAND_RAISED' | 'GROUP_CALL_STAGE_HAND_LOWERED' | 'GROUP_CALL_STAGE_PROMOTE' | 'GROUP_CALL_STAGE_DEMOTE' | 'GROUP_CALL_STAGE_QUESTION';
 export interface GroupCallEvent {
     type: GroupCallEventType | string;
     callId: string;
@@ -159,6 +159,12 @@ export interface RoomPolicy {
     maxParticipants?: number;
     /** When true, the room flips to CLOSED once the last participant leaves the call. */
     autoCloseWhenEmpty?: boolean;
+    /**
+     * When true, the room's live call runs in stage mode (Feature 3.2): hosts
+     * join as speakers, everyone else as receive-only audience who can raise a
+     * hand to be promoted. Mesh-scale - suited to panels and small stages.
+     */
+    stageMode?: boolean;
 }
 export interface Room {
     roomId: string;
@@ -486,4 +492,14 @@ export interface DropOnAirClient {
     joinRoom(roomId: string): Promise<string>;
     /** Leave the live call in a room. */
     leaveRoom(callId: string): Promise<void>;
+    /** Raise your hand to request promotion to speaker (any participant). */
+    raiseHand(callId: string): void;
+    /** Lower your previously raised hand. */
+    lowerHand(callId: string): void;
+    /** Promote an audience member to speaker (host / co-host). */
+    promoteToSpeaker(callId: string, userId: string): void;
+    /** Demote a speaker back to audience (host / co-host). */
+    demoteToAudience(callId: string, userId: string): void;
+    /** Submit a text question; relayed to the stage's speakers. */
+    submitStageQuestion(callId: string, text: string): void;
 }

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.14.0";
+export declare const SDK_VERSION = "0.15.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.14.0';
+exports.SDK_VERSION = '0.15.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.14.0",
+  "version": "0.15.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",