[Enhancement]Battery traces (#978)

Author: ipavlidakis

Sources/StreamVideo/StreamVideo.swift

@@ -17,6 +17,7 @@ public class StreamVideo: ObservableObject, @unchecked Sendable {
     @Injected(\.callCache) private var callCache
     @Injected(\.screenProperties) private var screenProperties
     @Injected(\.audioStore) private var audioStore
+    @Injected(\.battery) private var battery
 
     private enum DisposableKey: String { case ringEventReceived }
 
@@ -203,6 +204,7 @@ public class StreamVideo: ObservableObject, @unchecked Sendable {
         // Warm up
         _ = eventNotificationCenter
         _ = idleTimerAdapter
+        _ = battery
 
         if user.type != .anonymous {
             let userAuth = UserAuth { [weak self] in

Sources/StreamVideo/Utils/Battery/BatteryStore.swift

@@ -0,0 +1,123 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Combine
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// Monitors the device battery state and exposes the latest readings through
+/// the shared store pipeline.
+final class BatteryStore: CustomStringConvertible, @unchecked Sendable {
+
+    var state: Namespace.State { store.state }
+
+    var description: String {
+        var result = "Battery {"
+        result += " isMonitoring:\(store.state.isMonitoringEnabled)"
+        result += " state:\(store.state.state)"
+        result += " level:\(store.state.level)"
+        result += " }"
+        return result
+    }
+
+    private let store: Store<Namespace>
+    private let disposableBag = DisposableBag()
+
+    init(
+        store: Store<Namespace> = Namespace.store(
+            initialState: .init(
+                isMonitoringEnabled: false,
+                state: .unknown,
+                level: 0
+            )
+        )
+    ) {
+        self.store = store
+
+        self.store.dispatch(.setMonitoringEnabled(true))
+
+        #if canImport(UIKit)
+        self.store
+            .publisher(\.isMonitoringEnabled)
+            .filter { $0 }
+            .removeDuplicates()
+            .receive(on: DispatchQueue.main)
+            .map { _ in
+                MainActor.assumeIsolated {
+                    (
+                        UIDevice.current.batteryState,
+                        UIDevice.current.batteryLevel
+                    )
+                }
+            }
+            .sink { [weak self] stateAndLevel in
+                let (state, level) = stateAndLevel
+                self?.store.dispatch([
+                    .setState(.init(state)),
+                    .setLevel(level)
+                ])
+            }
+            .store(in: disposableBag)
+        #endif
+    }
+
+    func publisher<V: Equatable>(
+        _ keyPath: KeyPath<Namespace.State, V>
+    ) -> AnyPublisher<V, Never> {
+        store.publisher(keyPath)
+    }
+
+    func dispatch(
+        _ actions: [Namespace.Action],
+        file: StaticString = #file,
+        function: StaticString = #function,
+        line: UInt = #line
+    ) -> StoreTask<Namespace> {
+        store.dispatch(
+            actions,
+            file: file,
+            function: function,
+            line: line
+        )
+    }
+}
+
+extension BatteryStore: Encodable {
+    private enum CodingKeys: String, CodingKey {
+        case isMonitoringEnabled
+        case state
+        case level
+    }
+
+    /// Encodes a snapshot of the store's observable state.
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        let state = store.state
+        try container.encode(
+            state.isMonitoringEnabled,
+            forKey: .isMonitoringEnabled
+        )
+        try container.encode(state.state, forKey: .state)
+        try container.encode(state.level, forKey: .level)
+    }
+}
+
+extension BatteryStore: InjectionKey {
+    /// The default recorder instance used when no custom recorder is
+    /// provided.
+    nonisolated(unsafe) static var currentValue: BatteryStore = .init()
+}
+
+extension InjectedValues {
+    var battery: BatteryStore {
+        get {
+            Self[BatteryStore.self]
+        }
+        set {
+            Self[BatteryStore.self] = newValue
+        }
+    }
+}

Sources/StreamVideo/Utils/Battery/Namespace/BatteryStore+Action.swift

@@ -0,0 +1,17 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+
+extension BatteryStore.Namespace {
+    /// Actions that drive battery monitoring state transitions.
+    ///
+    /// These actions mirror updates from `UIDevice` and user controlled
+    /// monitoring preferences.
+    enum StoreAction: Sendable, Equatable, StoreActionBoxProtocol {
+        case setMonitoringEnabled(Bool)
+        case setLevel(Float)
+        case setState(StoreState.BatteryState)
+    }
+}

Sources/StreamVideo/Utils/Battery/Namespace/BatteryStore+Namespace.swift

@@ -0,0 +1,35 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+
+extension BatteryStore {
+
+    /// Namespace configuration for the battery monitoring store.
+    enum Namespace: StoreNamespace {
+
+        /// The state type for this store namespace.
+        typealias State = StoreState
+
+        /// The action type for this store namespace.
+        typealias Action = StoreAction
+
+        /// Unique identifier for this store instance.
+        ///
+        /// Used for logging and debugging purposes.
+        static let identifier: String = "battery.store"
+
+        static func reducers() -> [Reducer<Namespace>] {
+            [
+                DefaultReducer()
+            ]
+        }
+
+        static func middleware() -> [Middleware<BatteryStore.Namespace>] {
+            [
+                ObservationMiddleware()
+            ]
+        }
+    }
+}

Sources/StreamVideo/Utils/Battery/Namespace/BatteryStore+State.swift

@@ -0,0 +1,78 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+extension BatteryStore.Namespace {
+
+    /// Snapshot of the battery monitoring configuration and readings.
+    struct StoreState: Equatable {
+        var isMonitoringEnabled: Bool
+        var state: BatteryState
+        var level: Int
+    }
+}
+
+extension BatteryStore.Namespace.StoreState {
+
+    /// Represents the high-level battery state emitted by `UIDevice`.
+    enum BatteryState: CustomStringConvertible {
+        case unknown
+        case unplugged
+        case charging
+        case full
+
+        var description: String {
+            switch self {
+            case .unknown:
+                return ".unknown"
+            case .unplugged:
+                return ".unplugged"
+            case .charging:
+                return ".charging"
+            case .full:
+                return ".full"
+            }
+        }
+
+        #if canImport(UIKit)
+        /// Creates a battery state from the UIKit battery representation.
+        init(_ rawValue: UIDevice.BatteryState) {
+            switch rawValue {
+            case .unknown:
+                self = .unknown
+            case .unplugged:
+                self = .unplugged
+            case .charging:
+                self = .charging
+            case .full:
+                self = .full
+            @unknown default:
+                self = .unknown
+            }
+        }
+        #endif
+    }
+}
+
+extension BatteryStore.Namespace.StoreState: Encodable {}
+
+extension BatteryStore.Namespace.StoreState.BatteryState: Encodable {
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        switch self {
+        case .unknown:
+            try container.encode("unknown")
+        case .unplugged:
+            try container.encode("unplugged")
+        case .charging:
+            try container.encode("charging")
+        case .full:
+            try container.encode("full")
+        }
+    }
+}

Sources/StreamVideo/Utils/Battery/Namespace/Middleware/BatteryStore+ObservationMiddleware.swift

@@ -0,0 +1,41 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Combine
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+extension BatteryStore.Namespace {
+
+    /// Observes UIKit battery notifications and forwards updates to the store.
+    final class ObservationMiddleware: Middleware<BatteryStore.Namespace>, @unchecked Sendable {
+
+        private let disposableBag = DisposableBag()
+
+        /// Initializes the middleware and sets up interruption monitoring.
+        override init() {
+            super.init()
+
+            #if canImport(UIKit)
+            NotificationCenter
+                .default
+                .publisher(for: UIDevice.batteryStateDidChangeNotification)
+                .receive(on: DispatchQueue.main)
+                .map { _ in MainActor.assumeIsolated { UIDevice.current.batteryState } }
+                .sink { [weak self] in self?.dispatcher?.dispatch(.setState(.init($0))) }
+                .store(in: disposableBag)
+
+            NotificationCenter
+                .default
+                .publisher(for: UIDevice.batteryLevelDidChangeNotification)
+                .receive(on: DispatchQueue.main)
+                .map { _ in MainActor.assumeIsolated { UIDevice.current.batteryLevel } }
+                .sink { [weak self] in self?.dispatcher?.dispatch(.setLevel($0)) }
+                .store(in: disposableBag)
+            #endif
+        }
+    }
+}

Sources/StreamVideo/Utils/Battery/Namespace/Reducers/BatteryStore+DefaultReducer.swift

@@ -0,0 +1,63 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+extension BatteryStore.Namespace {
+
+    final class DefaultReducer: Reducer<BatteryStore.Namespace>, @unchecked Sendable {
+        /// Processes an action to produce a new state.
+        ///
+        /// This method creates a copy of the current state, applies the
+        /// action's changes, and returns the updated state.
+        ///
+        /// - Parameters:
+        ///   - state: The current state before the action.
+        ///   - action: The action to process.
+        ///   - file: Source file where the action was dispatched.
+        ///   - function: Function name where the action was dispatched.
+        ///   - line: Line number where the action was dispatched.
+        ///
+        /// - Returns: A new state reflecting the action's changes.
+        ///
+        /// - Throws: This implementation doesn't throw, but the protocol
+        ///   allows for error handling in complex reducers.
+        override func reduce(
+            state: State,
+            action: Action,
+            file: StaticString,
+            function: StaticString,
+            line: UInt
+        ) async throws -> State {
+            var updatedState = state
+
+            switch action {
+            case let .setMonitoringEnabled(value):
+                #if canImport(UIKit)
+                await MainActor.run { UIDevice.current.isBatteryMonitoringEnabled = value }
+                updatedState.isMonitoringEnabled = value
+                #else
+                break
+                #endif
+
+            case let .setLevel(value):
+                if value >= 0 {
+                    let percentage = Double(value) * 100
+                    let rounded = percentage.rounded()
+                    updatedState.level = Int(max(0, min(rounded, 100)))
+                } else {
+                    updatedState.level = 0
+                }
+
+            case let .setState(value):
+                updatedState.state = value
+            }
+
+            return updatedState
+        }
+    }
+}

Sources/StreamVideo/WebRTC/v2/Stats/Models/WebRTCTrace.swift

@@ -217,3 +217,15 @@ extension WebRTCTrace {
         )
     }
 }
+
+extension WebRTCTrace {
+    init(
+        _ battery: BatteryStore
+    ) {
+        self.init(
+            id: nil,
+            tag: "device.battery.\(battery.state.state)",
+            data: .init(battery)
+        )
+    }
+}