feat: expose single event stream in Call combining sfu and coordinator events (#625)

* single call event stream exposed combining sfu and coordinator events

* tweaks

* tweaks to call event

* roadmap update

* rename to StreamCallEvent

* docs

* vale fix

* typo

* Update docusaurus/docs/Flutter/03-core-concepts/09-call-events.mdx

* Update packages/stream_video/CHANGELOG.md

* removed cid requirement

---------

Co-authored-by: Deven Joshi <[email protected]>

Author: Brazol

development.md

@@ -23,14 +23,13 @@
 - [x] Android foreground service
 
 ### 0.3.0 milestone
-- [ ] Publish apps to Android/iOS [Deven]
-- - [ ] Check the stores' descriptions
-- - [ ] Publish Dogfooding app
-- [ ] Participant sort bug [Efthymis]
+- [x] Publish apps to Android/iOS [Deven]
+- - [x] Check the stores' descriptions
+- - [x] Publish Dogfooding app
+- [x] Participant sort bug [Efthymis]
 - [x] Android/iOS ringing flow
 - [x] Live streaming component(s) [Deven]
 - [x] Deeplinking
-- [ ] Tap to focus (flutter_webrtc) [Kanat]
 - [x] Push notifications [Maciej]
 - - [x] Customization of the incoming/outgoing call screens
 - - [x] Customizing CallKit ringing calls
@@ -48,29 +47,32 @@
 - [x] Fix analysis issues [Maciej]
 
 ### 0.4.0 milestone
-- [ ] Implement Chat overlay for Dogfooding app
+- [x] Implement Chat overlay for Dogfooding app
 - [x] Support SFU migration
+- [x] Send raw stats to backend
+- [x] Bluetooth fixes (check support of BT media devices in flutter)
+- [x] Switch the earpiece/microphone button *(depends on "Bluetooth fixes")*
+- [x] Align custom event support to other SDKs
+- [ ] Tap to focus (flutter_webrtc)
 - [ ] Video filters / audio filters
-- [ ] Bluetooth fixes (check support of BT media devices in flutter)
-- [ ] Switch the earpiece/microphone button *(depends on "Bluetooth fixes")*
 - [ ] Local audio levels (maybe from webrtc)
 - [ ] Test coverage 
 - - [ ] stream_video (75%)
 - - [ ] stream_video_flutter (75%)
 - - [ ] stream_video_push_notification
 - - [ ] Coverage check for PRs
-- [ ] Align custom event support to other SDKs
-- [ ] Send raw stats to backend
 - [ ] Documentation parity
 - - [ ] UI components
 - - [ ] Cookbook
 - - [ ] Advanced guides
 
 ### 0.5.0 milestone
-- [ ] Dynascale 2.0
 - [ ] Picture-in-picture
+- - [x] Android
+- - [ ] iOS
+- [ ] Dynascale 2.0
 - [ ] SFU switching
 - [ ] Buttons to simulate ICE restarts / SFU switching
 - [ ] Proximity button support
-- [ ] Call stats component
+- [x] Call stats component
 - [ ] Transcription

docusaurus/docs/Flutter/03-core-concepts/09-call-events.mdx

@@ -0,0 +1,70 @@
+---
+title: Call Events
+slug: /call-events
+description: How to listen and leverage call events
+---
+
+There are multiple events that you can listen to during a call. You can use them to update the UI, show notifications, or log the call events. You can listen to them via `callEvents` stream in the `Call` object.
+
+Here are some of the events you can listen to:
+
+
+| Call Event                                    | Description                                           |
+| --------------------------------------------- | ----------------------------------------------------- |
+| **General Call Events**                       |                                                       |
+| `StreamCallCreatedEvent`                      | Triggered when a call is created.                     |
+| `StreamCallJoinedEvent`                       | Triggered when a user joins a call.                   |
+| `StreamCallEndedEvent`                        | Triggered when the call ends.                         |
+| `StreamCallUpdatedEvent`                      | Triggered when the call metadata are updated.         |
+| **Participant Events**                        |                                                       |
+| `StreamCallParticipantJoinedEvent`            | Triggered when a participant joins the call.          |
+| `StreamCallParticipantLeftEvent`              | Triggered when a participant leaves the call.         |
+| `StreamCallDominantSpeakerChangedEvent`       | Triggered when the dominant speaker changes.          |
+| **Quality and Control Events**                |                                                       |
+| `StreamCallConnectionQualityChangedEvent`     | Triggered when connection quality changes for participants. |
+| `StreamCallAudioLevelChangedEvent`            | Triggered when audio levels change for participants.  |
+| `StreamCallPermissionRequestEvent`            | Triggered when there is a permission request for a call. |
+| `StreamCallPermissionsUpdatedEvent`           | Triggered when permissions for a call are updated.    |
+| **Call Ringing Events**                       |                                                       |
+| `StreamCallRingingEvent`                      | Triggered when the call is ringing.                   |
+| `StreamCallAcceptedEvent`                     | Triggered when the call is accepted.                  |
+| `StreamCallRejectedEvent`                     | Triggered when the call is rejected.                  |
+| **Media Events**                              |                                                       |
+| `StreamCallRecordingStartedEvent`             | Triggered when recording starts for a call.           |
+| `StreamCallRecordingStoppedEvent`             | Triggered when recording stops for a call.            |
+| `StreamCallBroadcastingStartedEvent`          | Triggered when broadcasting starts for a call.        |
+| `StreamCallBroadcastingStoppedEvent`          | Triggered when broadcasting stops for a call.         |
+| **Session Events**                            |                                                       |
+| `StreamCallSessionStartedEvent`               | Triggered when a new session starts for a call.       |
+| `StreamCallSessionEndedEvent`                 | Triggered when a session ends for a call.             |
+| `StreamCallSessionParticipantJoinedEvent`     | Triggered when a participant joins the call session.  |
+| `StreamCallSessionParticipantLeftEvent`       | Triggered when a participant leaves the call session. |
+| **Other Events**                              |                                                       |
+| `StreamCallUserBlockedEvent`                  | Triggered when a user is blocked in a call.           |
+| `StreamCallUserUnblockedEvent`                | Triggered when a user is unblocked in a call.         |
+| `StreamCallReactionEvent`                     | Triggered when someone sends a reaction during a call.|
+
+## Custom event
+
+Stream Video also supports custom events. This is a real-time layer that you can broadcast your own events to.
+
+### Sending custom events
+
+You can use the `sendCustomEvent` method of the `Call` instance to send custom events:
+
+```dart
+call.sendCustomEvent(
+    eventType: 'my-custom-event',
+    custom: {
+      'key': 'value',
+    },
+);
+```
+
+### Receiving custom events
+​
+You can listen to custom events by listening to the `StreamCallCustomEvent` event via the same `callEvents` stream:
+
+```dart
+call.callEvents.on<StreamCallCustomEvent>((event) { });
+```

packages/stream_video/CHANGELOG.md

@@ -1,3 +1,12 @@
+## Unrelease
+✅ Added
+
+* Added `callEvents` stream to `Call` that replaces `events` and `coordinatorEvents` streams (both are now deprecated)
+
+🚧 Breaking changes
+
+* Removed the `callCid` parameter requirement from `sendCustomEvent` method in `Call` class
+
 ## 0.3.5
 ✅ Added
 

packages/stream_video/lib/src/call/call.dart

@@ -242,13 +242,18 @@ class Call {
   SharedEmitter<CallStats> get stats => _stats;
   late final _stats = MutableSharedEmitterImpl<CallStats>();
 
+  @Deprecated('Use `callEvents` instead')
   SharedEmitter<SfuEvent> get events => _events;
   final _events = MutableSharedEmitterImpl<SfuEvent>();
 
+  @Deprecated('Use `callEvents` instead')
   SharedEmitter<CoordinatorCallEvent> get coordinatorEvents =>
       _coordinatorEvents;
   final _coordinatorEvents = MutableSharedEmitterImpl<CoordinatorCallEvent>();
 
+  SharedEmitter<StreamCallEvent> get callEvents => _callEvents;
+  final _callEvents = MutableSharedEmitterImpl<StreamCallEvent>();
+
   OnCallPermissionRequest? onPermissionRequest;
 
   final _status = MutableStateEmitterImpl<_ConnectionStatus>(
@@ -294,6 +299,7 @@ class Call {
       _idCoordEvents,
       _coordinatorClient.events.on<CoordinatorCallEvent>((event) async {
         _coordinatorEvents.emit(event);
+        event.mapToCallEvent(state.value).emitIfNotNull(_callEvents);
         await _onCoordinatorEvent(event);
       }),
     );
@@ -593,6 +599,7 @@ class Call {
           () => '[listenSfuEvent] event.type: ${event.runtimeType}',
         );
         _events.emit(event);
+        event.mapToCallEvent(state.value).emitIfNotNull(_callEvents);
         _onSfuEvent(event);
       }),
     );
@@ -1760,7 +1767,6 @@ class Call {
   }
 
   Future<Result<None>> sendCustomEvent({
-    required StreamCallCid callCid,
     required String eventType,
     Map<String, Object> custom = const {},
   }) {