Add RoomEvent.RoomSidChanged

.changeset/room-sid-changed-event.md

@@ -0,0 +1,5 @@
+---
+'livekit-client': patch
+---
+
+Add `RoomEvent.RoomSidChanged`, emitted when the room's session ID changes while connected, such as when the server starts a new session for a room that is still live.

src/room/Room.test.ts

@@ -2,6 +2,7 @@ import {
   ClientInfo_Capability,
   JoinResponse,
   StreamState as ProtoStreamState,
+  Room as RoomModel,
   StreamStateUpdate,
   SubscriptionError,
   SubscriptionResponse,
@@ -463,3 +464,30 @@ describe('audio context ownership', () => {
     expect(created[0].closed).toBe(true);
   });
 });
+
+describe('room updates', () => {
+  function pushRoomUpdate(room: Room, update: { name?: string; sid?: string }) {
+    (room as unknown as { handleRoomUpdate: (room: RoomModel) => void }).handleRoomUpdate(
+      new RoomModel(update),
+    );
+  }
+
+  it('emits RoomSidChanged when the session ID changes', async () => {
+    const room = new Room();
+    room.state = ConnectionState.Connected;
+    const sidChanged = vi.fn();
+    room.on(RoomEvent.RoomSidChanged, sidChanged);
+
+    pushRoomUpdate(room, { name: 'room', sid: 'RM_first' });
+    expect(sidChanged).not.toHaveBeenCalled();
+
+    pushRoomUpdate(room, { name: 'room', sid: 'RM_first' });
+    pushRoomUpdate(room, { name: 'room', sid: '' });
+    expect(sidChanged).not.toHaveBeenCalled();
+
+    pushRoomUpdate(room, { name: 'room', sid: 'RM_second' });
+    expect(sidChanged).toHaveBeenCalledOnce();
+    expect(sidChanged).toHaveBeenCalledWith('RM_second');
+    await expect(room.getSid()).resolves.toBe('RM_second');
+  });
+});

src/room/Room.ts

@@ -211,6 +211,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private roomInfo?: RoomModel;
 
+  /** last non-empty session ID, updates can carry an empty one */
+  private knownSid?: string;
+
   private sidToIdentity: Map<string, string>;
 
   /** connect options of room */
@@ -2455,6 +2458,13 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     if (oldRoom && oldRoom.metadata !== room.metadata) {
       this.emitWhenConnected(RoomEvent.RoomMetadataChanged, room.metadata);
     }
+    if (room.sid && room.sid !== this.knownSid) {
+      const hadSid = !!this.knownSid;
+      this.knownSid = room.sid;
+      if (hadSid) {
+        this.emitWhenConnected(RoomEvent.RoomSidChanged, room.sid);
+      }
+    }
     if (oldRoom?.activeRecording !== room.activeRecording) {
       this.emitWhenConnected(RoomEvent.RecordingStatusChanged, room.activeRecording);
     }
@@ -3285,6 +3295,7 @@ export type RoomEventCallbacks = {
   ) => void;
   activeSpeakersChanged: (speakers: Array<Participant>) => void;
   roomMetadataChanged: (metadata: string) => void;
+  roomSidChanged: (sid: string) => void;
   dataReceived: (
     payload: NonSharedUint8Array,
     participant?: RemoteParticipant,

src/room/events.ts

@@ -220,6 +220,15 @@ export enum RoomEvent {
    */
   RoomMetadataChanged = 'roomMetadataChanged',
 
+  /**
+   * The room's session ID changed while connected, for example when the server
+   * starts a new session for a room that is still live, or the local participant
+   * was moved to another room. Room.getSid() returns the new ID.
+   *
+   * args: (sid: string)
+   */
+  RoomSidChanged = 'roomSidChanged',
+
   /**
    * Data received from another participant.
    * Data packets provides the ability to use LiveKit to send/receive arbitrary payloads.