@droponair/sdk-js 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0], 2026-05-18
+
+### Added
+- **Screen sharing signaling.** New client APIs and event types so apps can
+  coordinate the start/stop of a screen-share track on top of the existing
+  WebRTC call. The SDK only signals - capture (`getDisplayMedia()` on web) and
+  track management remain in the app layer.
+- **1:1 calls:**
+  - `client.startScreenShare(callId, payload?)` and `client.stopScreenShare(callId, payload?)`.
+  - New `CallEventType` values: `'CALL_SCREEN_SHARE_STARTED'`, `'CALL_SCREEN_SHARE_STOPPED'`.
+- **Group calls:**
+  - `client.startGroupScreenShare(callId, groupId, payload?)` and `client.stopGroupScreenShare(callId, groupId, payload?)`.
+  - New `GroupCallEventType` values: `'GROUP_CALL_SCREEN_SHARE_STARTED'`, `'GROUP_CALL_SCREEN_SHARE_STOPPED'`.
+  - Server enforces a single concurrent sharer per group call. If another
+    participant already holds the slot when you call `startGroupScreenShare`,
+    you'll receive a `GROUP_CALL_SCREEN_SHARE_STOPPED` event with the current
+    holder's userId in `payload`, so the app can roll back its optimistic UI.
+  - When a sharer leaves the call, the server broadcasts a STOPPED event to
+    remaining participants before they see `PARTICIPANT_LEFT`.
+- `GET /api/info` now advertises `"screen_sharing"` in the `features` array.
+
+### Notes
+- Wire-level additive: legacy 0.5.x clients ignore the new signal type strings
+  (string discriminators on existing `CallFrame.type` / `GroupCallFrame.type`).
+  No proto schema change, no `PROTOCOL_VERSION` bump.
+- Screen content is opaque WebRTC media; the server never sees it. Use
+  `getDisplayMedia()` (web) / `MediaProjection` (Android) / `ReplayKit` (iOS)
+  in the app, add the track to the existing peer connection, then call
+  `startScreenShare(...)` to notify the peer.
+- Plan gate: `screen_sharing` is enabled on PRO/GROWTH/PAYG/ENTERPRISE and
+  disabled on FREE. Check `subscription.featuresEnabled.screen_sharing` (server
+  side, on the customer's backend).
+
+---
+
 ## [0.5.0], 2026-05-18
 
 ### Added

package/README.md

@@ -209,6 +209,51 @@ client.onMessage(async (msg) => {
 | `sendGroupCallSignal(type, callId, groupId, targetUserId, payload)` | `void` | Send SDP/ICE to a peer |
 | `onGroupCallEvent(callback)` | `() => void` | Listen for group call events |
 
+### 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.
+
+```typescript
+// 1:1 call
+async function shareMyScreen(callId: string, peerConnection: RTCPeerConnection) {
+  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
+  const track  = stream.getVideoTracks()[0];
+  peerConnection.addTrack(track, stream);
+  client.startScreenShare(callId);
+  track.onended = () => client.stopScreenShare(callId);
+}
+
+// Group call
+async function shareMyScreenInGroup(callId: string, groupId: string, peerConnections: RTCPeerConnection[]) {
+  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
+  const track  = stream.getVideoTracks()[0];
+  peerConnections.forEach(pc => pc.addTrack(track, stream));
+  client.startGroupScreenShare(callId, groupId);
+  track.onended = () => client.stopGroupScreenShare(callId, groupId);
+}
+
+client.onCallEvent((evt) => {
+  if (evt.type === 'CALL_SCREEN_SHARE_STARTED')  showShareIndicator(evt.callId);
+  if (evt.type === 'CALL_SCREEN_SHARE_STOPPED')  hideShareIndicator(evt.callId);
+});
+
+client.onGroupCallEvent((evt) => {
+  if (evt.type === 'GROUP_CALL_SCREEN_SHARE_STARTED')  showShareIndicator(evt.callId, evt.payload);  // payload = sharer userId
+  if (evt.type === 'GROUP_CALL_SCREEN_SHARE_STOPPED')  hideShareIndicator(evt.callId);
+});
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `startScreenShare(callId, payload?)` | `void` | Signal start in a 1:1 call |
+| `stopScreenShare(callId, payload?)` | `void` | Signal stop in a 1:1 call |
+| `startGroupScreenShare(callId, groupId, payload?)` | `void` | Signal start in a group call |
+| `stopGroupScreenShare(callId, groupId, payload?)` | `void` | Signal stop in a group call |
+
+- The server enforces **one concurrent sharer per group call**. If another participant already holds the slot when you call `startGroupScreenShare`, the SDK delivers a `GROUP_CALL_SCREEN_SHARE_STOPPED` event with the current holder's userId in `payload`, so you can roll back the optimistic UI.
+- When a sharer leaves the call, the server broadcasts a STOPPED event to remaining participants before they see `PARTICIPANT_LEFT`.
+- Plan gate: `screen_sharing` is on `PRO`/`GROWTH`/`PAYG`/`ENTERPRISE`, off on `FREE`. Read `subscription.featuresEnabled.screen_sharing` on your backend to decide whether to expose the share button.
+
 ## Security
 
 - **X25519 ECDH** key agreement for shared secrets

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

@@ -136,6 +136,8 @@ export declare class MessagingClient implements DropOnAirClient {
     leaveGroupCall(callId: string): Promise<void>;
     endGroupCall(callId: string): Promise<void>;
     sendGroupCallSignal(type: 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE', callId: string, groupId: string, targetUserId: string, payload: string): void;
+    startGroupScreenShare(callId: string, groupId: string, payload?: string): void;
+    stopGroupScreenShare(callId: string, groupId: string, payload?: string): void;
     onGroupCallEvent(callback: GroupCallEventCallback): () => void;
     private sendGroupCallFrame;
     /**
@@ -149,6 +151,8 @@ export declare class MessagingClient implements DropOnAirClient {
     endCall(callId: string): Promise<void>;
     toggleVideo(callId: string, enabled: boolean): void;
     sendCallSignal(type: 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE', callId: string, payload: string): void;
+    startScreenShare(callId: string, payload?: string): void;
+    stopScreenShare(callId: string, payload?: string): void;
     fetchTurnCredentials(): Promise<TurnCredentials>;
     private sendCallFrame;
     private emitCallEvent;

package/dist/core/messaging-client.js

@@ -740,6 +740,24 @@ class MessagingClient {
     sendGroupCallSignal(type, callId, groupId, targetUserId, payload) {
         this.sendGroupCallFrame({ type, callId, groupId, targetUserId, payload });
     }
+    startGroupScreenShare(callId, groupId, payload) {
+        this.sendGroupCallFrame({
+            type: 'GROUP_CALL_SCREEN_SHARE_STARTED',
+            callId,
+            groupId,
+            targetUserId: '',
+            payload: payload ?? '',
+        });
+    }
+    stopGroupScreenShare(callId, groupId, payload) {
+        this.sendGroupCallFrame({
+            type: 'GROUP_CALL_SCREEN_SHARE_STOPPED',
+            callId,
+            groupId,
+            targetUserId: '',
+            payload: payload ?? '',
+        });
+    }
     onGroupCallEvent(callback) {
         this.groupCallListeners.add(callback);
         return () => this.groupCallListeners.delete(callback);
@@ -781,6 +799,12 @@ class MessagingClient {
     sendCallSignal(type, callId, payload) {
         this.sendCallFrame({ type, callId, payload });
     }
+    startScreenShare(callId, payload) {
+        this.sendCallFrame({ type: 'CALL_SCREEN_SHARE_STARTED', callId, payload: payload ?? '' });
+    }
+    stopScreenShare(callId, payload) {
+        this.sendCallFrame({ type: 'CALL_SCREEN_SHARE_STOPPED', callId, payload: payload ?? '' });
+    }
     async fetchTurnCredentials() {
         const jwt = await this.getValidDropOnAirJwt(false);
         const url = `${this.httpUrl}/api/v1/turn/credentials`;

package/dist/core/types.d.ts

@@ -57,7 +57,7 @@ export interface BroadcastMessage {
     sequenceNumber: number;
 }
 export type BroadcastCallback = (message: BroadcastMessage) => void;
-export type CallEventType = 'CALL_INVITE' | 'CALL_RINGING' | 'CALL_ACCEPTED' | 'CALL_REJECTED' | 'CALL_ENDED' | 'CALL_CANCELLED' | 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE' | 'CALL_VIDEO_TOGGLE' | 'CALL_DENIED_LIMIT_REACHED';
+export type CallEventType = 'CALL_INVITE' | 'CALL_RINGING' | 'CALL_ACCEPTED' | 'CALL_REJECTED' | 'CALL_ENDED' | 'CALL_CANCELLED' | 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE' | 'CALL_VIDEO_TOGGLE' | 'CALL_SCREEN_SHARE_STARTED' | 'CALL_SCREEN_SHARE_STOPPED' | 'CALL_DENIED_LIMIT_REACHED';
 export interface CallEvent {
     type: CallEventType | string;
     callId?: string;
@@ -92,7 +92,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_ALREADY_ACTIVE' | 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE';
+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_ALREADY_ACTIVE' | 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE' | 'GROUP_CALL_SCREEN_SHARE_STARTED' | 'GROUP_CALL_SCREEN_SHARE_STOPPED';
 export interface GroupCallEvent {
     type: GroupCallEventType | string;
     callId: string;
@@ -212,6 +212,16 @@ export interface DropOnAirClient {
      * The payload is forwarded opaquely, the server does NOT inspect or store it.
      */
     sendCallSignal(type: 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE', callId: string, payload: string): void;
+    /**
+     * Signal that this user started sharing their screen in a 1:1 call
+     * (phase1/screen-sharing, PROTOCOL_VERSION 4+). The actual screen MediaStreamTrack
+     * is added to the existing peer connection by the application; the SDK only
+     * broadcasts the start/stop notification so the remote SDK can update its UI.
+     * Optional `payload` (JSON string) can carry track-id or app-specific metadata.
+     */
+    startScreenShare(callId: string, payload?: string): void;
+    /** Signal that this user stopped sharing their screen in a 1:1 call. */
+    stopScreenShare(callId: string, payload?: string): void;
     /** Register a listener for all incoming call events. Returns an unsubscribe function. */
     onCallEvent(callback: CallEventCallback): () => void;
     /** Fetch short-lived TURN credentials for ICE negotiation. */
@@ -244,6 +254,16 @@ export interface DropOnAirClient {
     endGroupCall(callId: string): Promise<void>;
     /** Send a signaling frame to a specific peer in a group call. */
     sendGroupCallSignal(type: 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE', callId: string, groupId: string, targetUserId: string, payload: string): void;
+    /**
+     * Signal that this user started sharing their screen in a group call.
+     * The server enforces one concurrent sharer per group call; if another
+     * participant already holds the slot, the SDK will receive a
+     * `GROUP_CALL_SCREEN_SHARE_STOPPED` event echoing the current holder's
+     * userId in `payload` so the app can roll back its optimistic UI.
+     */
+    startGroupScreenShare(callId: string, groupId: string, payload?: string): void;
+    /** Signal that this user stopped sharing their screen in a group call. */
+    stopGroupScreenShare(callId: string, groupId: string, payload?: string): void;
     /** Register a listener for group call events. Returns an unsubscribe function. */
     onGroupCallEvent(callback: GroupCallEventCallback): () => 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.5.0";
+export declare const SDK_VERSION = "0.6.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.5.0';
+exports.SDK_VERSION = '0.6.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.5.0",
+  "version": "0.6.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",