@npaw/forge-react-native 9.7.3 → 9.7.4

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeRuntime.swift

@@ -71,6 +71,18 @@ public protocol ForgeRuntime: AnyObject {
     /// Forwards a location fix. Fixes only - the kernel owns every threshold,
     /// so the three platforms cannot drift into different definitions of moving.
     func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome
+    /// Forwards a device runtime health sample. Every field is optional; the
+    /// kernel validates field-wise, derives `dev_cpu` between samples and
+    /// attaches the set to the next session beat and video ping. Refused
+    /// (`ignoredInvalidState`) while device insights are off remotely.
+    func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome
+    /// Registers (or clears with `nil`) the receiver of the kernel's device
+    /// sample requests. The kernel owns the cadence: it asks for one sample per
+    /// tick with the operator's family allowlist (`cpu`, `mem`, `bat`, `thm`,
+    /// `disk`), and the host answers through ``recordDeviceSample(_:)``. A
+    /// request is not replayed to a late listener - the kernel asks again on
+    /// the next tick.
+    func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome
     func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView
     func recordEvent(_ event: ForgeRecordedEvent) -> ForgeOutcome
     /// Records a typed identity transition (`loginSuccess`, `loginFailed`,
@@ -131,6 +143,12 @@ public extension ForgeRuntime {
     func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome { .accepted }
     /// Additive default: no kernel behind it means nothing to derive motion with.
     func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome { .accepted }
+    /// Additive default: a runtime with no kernel behind it has no sampler to
+    /// feed, so it accepts and forgets.
+    func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome { .accepted }
+    /// Additive default: no kernel means no cadence, so registration succeeds
+    /// and simply never delivers a request.
+    func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome { .accepted }
 }
 
 public protocol ForgeRuntimeFactory: AnyObject {
@@ -148,6 +166,8 @@ public final class UnavailableForgeRuntime: ForgeRuntime {
     public func setLogLevel(_ level: ForgeLogLevel) -> ForgeOutcome { .accepted }
     public func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome { .accepted }
     public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome { .accepted }
+    public func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome { .accepted }
+    public func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome { .accepted }
     public func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView { RuntimeVideoView(id: -1) }
     public func recordEvent(_ event: ForgeRecordedEvent) -> ForgeOutcome { failed() }
     public func recordIdentityEvent(kind: String, timemarkMs: Int64, fields: [String: String]) -> ForgeOutcome { failed() }
@@ -215,6 +235,14 @@ public final class RecordingForgeRuntime: ForgeRuntime {
     public private(set) var publishedConnectionTypes: [String?] = []
     /// Every location fix forwarded, in order.
     public private(set) var recordedLocationFixes: [ForgeLocationFix] = []
+    /// Every device sample forwarded, in order.
+    public private(set) var recordedDeviceSamples: [ForgeDeviceSample] = []
+    /// The device sample request listener currently registered, `nil` once
+    /// cleared.
+    public private(set) var deviceSampleListener: (([String]) -> Void)?
+    /// Device samples arrive from the collector's utility queue while a test
+    /// reads them from the main thread; only those two members are guarded.
+    private let recordingLock = NSLock()
     private var nextViewId: Int64 = 1
 
     public init() {}
@@ -229,6 +257,26 @@ public final class RecordingForgeRuntime: ForgeRuntime {
         recordedLocationFixes.append(fix)
         return .accepted
     }
+    public func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome {
+        recordingLock.lock()
+        defer { recordingLock.unlock() }
+        recordedDeviceSamples.append(sample)
+        return .accepted
+    }
+    public func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome {
+        recordingLock.lock()
+        defer { recordingLock.unlock() }
+        deviceSampleListener = listener
+        return .accepted
+    }
+    /// Test hook mirroring the kernel's request push path: hands the family
+    /// allowlist to the registered listener, if any. Nothing is replayed.
+    public func emitDeviceSampleRequest(_ families: [String]) {
+        recordingLock.lock()
+        let listener = deviceSampleListener
+        recordingLock.unlock()
+        listener?(families)
+    }
     public func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView {
         createdVideoTimestamps.append(timestampMs)
         defer { nextViewId += 1 }

package/ios/ForgeApple/Sources/NPAWForgeCore/NPAWForge.swift

@@ -40,7 +40,7 @@ public final class NPAWForge: NSObject {
     /// `scripts/apple/publish-local-shipped.sh` rewrites this literal to the
     /// release version when staging the shipped package, and fails loudly if
     /// it cannot find it. Keep it a plain stored literal for that reason.
-    public static let defaultPluginVersion = "9.7.3"
+    public static let defaultPluginVersion = "9.7.4"
     public static let defaultAppName = "apple"
     public static let defaultBuildVariant = "release"
     public static let defaultLmaEndpoint = "https://lma.npaw.com"
@@ -95,6 +95,11 @@ public final class NPAWForge: NSObject {
     /// Set when the integrator allowed location observation. It reads nothing
     /// until a capture plan carries the location bit.
     private var locationObserver: ForgeLocationObserver?
+    /// Answers the kernel's device sample requests. Inert until an operator
+    /// enables device insights remotely; held so `destroy()` can stop it and
+    /// return battery monitoring to what it was.
+    private var deviceInsightsCollector: ForgeDeviceInsightsCollector?
+    private var deviceInsightsSubscriptions: [ForgeEventSubscription] = []
 
     public init(kernel: ForgeApple) {
         self.kernel = kernel
@@ -250,6 +255,10 @@ public final class NPAWForge: NSObject {
         connectionTypeObserver = nil
         locationObserver?.stop()
         locationObserver = nil
+        deviceInsightsSubscriptions.forEach { $0.cancel() }
+        deviceInsightsSubscriptions.removeAll()
+        deviceInsightsCollector?.stop()
+        deviceInsightsCollector = nil
         let adapters = videoAdapters
         videoAdapters.removeAll()
         adapters.forEach { _ = $0.destroy() }
@@ -270,6 +279,17 @@ public final class NPAWForge: NSObject {
         kernel.recordLocationFix(fix)
     }
 
+    /// Forwards a device runtime health sample to the kernel. Forge answers the
+    /// kernel's requests itself (process CPU time, memory, battery on iOS,
+    /// thermal state); use this only to supply a value Forge does not read,
+    /// such as `diskFreeBytes` from an app that declares the required-reason
+    /// API in its own privacy manifest. Every field is optional. Ignored while
+    /// device insights are off remotely.
+    @discardableResult
+    public func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome {
+        kernel.recordDeviceSample(sample)
+    }
+
     /// Starts or stops location observation to match the capture plan. Nothing
     /// reads location - not even the authorization status - until an operator
     /// enables one of the two motion switches.
@@ -295,6 +315,24 @@ public final class NPAWForge: NSObject {
         observer.start()
     }
 
+    /// Wires the collector to the kernel: capture plans pre-arm the observers a
+    /// family needs (battery monitoring for `bat`), sample requests trigger the
+    /// reads. Both subscriptions are cancelled in `destroy()`.
+    func installDeviceInsightsCollector(_ collector: ForgeDeviceInsightsCollector) {
+        lock.lock()
+        deviceInsightsCollector = collector
+        lock.unlock()
+        let planSubscription = kernel.addCapturePlanListener { [weak collector] plan in
+            collector?.applyCapturePlan(plan)
+        }
+        let requestSubscription = kernel.addDeviceSampleRequestListener { [weak collector] families in
+            collector?.handleSampleRequest(families)
+        }
+        lock.lock()
+        deviceInsightsSubscriptions.append(contentsOf: [planSubscription, requestSubscription])
+        lock.unlock()
+    }
+
     func buildVideoAdapter(
         identifier: String,
         options: VideoOptions,
@@ -554,6 +592,16 @@ public final class NPAWForge: NSObject {
                     }
                 )
             }
+            // Always installed and inert by construction: it reads nothing
+            // until the kernel asks, and the kernel asks only once an operator
+            // enabled device insights remotely (that enablement is the whole
+            // authorisation - device health is non-personal and needs no OS
+            // permission on any platform).
+            forge.installDeviceInsightsCollector(
+                ForgeDeviceInsightsCollector { [weak forge] sample in
+                    forge?.recordDeviceSample(sample)
+                }
+            )
             ForgeAutomaticCaptureRegistry.installIfAvailable(forge)
             return forge
         }

package/ios/ForgeApple/Sources/NPAWForgeCore/NativeUniFFIRuntime.swift

@@ -27,6 +27,7 @@ final class UniFFIForgeRuntime: ForgeRuntime {
     private var sessionPreSendHook: UniFFISessionPreSendHook?
     private var capturePlanListener: UniFFICapturePlanListener?
     private var logListener: UniFFILogListener?
+    private var deviceSampleListener: UniFFIDeviceSampleListener?
 
     init(config: ForgeAppleConfig) {
         bridge = ForgeRuntimeBridge(config: AppleRuntimeConfig(
@@ -71,6 +72,37 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         ))
     }
 
+    func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome {
+        outcome(bridge.recordDeviceSample(sample: appleDeviceSample(sample)))
+    }
+
+    func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome {
+        if let listener {
+            let callback = UniFFIDeviceSampleListener(callback: listener)
+            // Retained before registering, like the plan and log listeners, so
+            // a request that fires as soon as the bridge has the wrapper lands
+            // in one the runtime keeps alive.
+            callbackLock.lock()
+            deviceSampleListener = callback
+            callbackLock.unlock()
+            let result = outcome(bridge.setDeviceSampleListener(listener: callback))
+            if !result.isAccepted {
+                callbackLock.lock()
+                deviceSampleListener = nil
+                callbackLock.unlock()
+            }
+            return result
+        }
+
+        let result = outcome(bridge.clearDeviceSampleListener())
+        if result.isAccepted {
+            callbackLock.lock()
+            deviceSampleListener = nil
+            callbackLock.unlock()
+        }
+        return result
+    }
+
     func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView {
         RuntimeVideoView(id: Int64(clamping: bridge.createVideoView(
             nowMs: u64(timestampMs),
@@ -312,12 +344,14 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         let result = outcome(bridge.destroy())
         _ = bridge.clearCapturePlanListener()
         _ = bridge.clearLogListener()
+        _ = bridge.clearDeviceSampleListener()
         callbackLock.lock()
         contentMetadataProviders.removeAll()
         videoPreSendHooks.removeAll()
         sessionPreSendHook = nil
         capturePlanListener = nil
         logListener = nil
+        deviceSampleListener = nil
         callbackLock.unlock()
         return result
     }
@@ -508,6 +542,7 @@ private func forgeCapturePlan(_ plan: AppleCapturePlan) -> ForgeCapturePlan {
         attributionIncludeLandingUrl: plan.attributionIncludeLandingUrl,
         attributionDeriveFromDeepLinks: plan.attributionDeriveFromDeepLinks,
         attributionInstallReferrerEnabled: plan.attributionInstallReferrerEnabled,
+        deviceInsightFamilies: plan.deviceInsightFamilies,
         hash: plan.hash
     )
 }
@@ -548,6 +583,33 @@ private func appleAdInsertionType(_ insertionType: AdInsertionType) -> AppleAdIn
     }
 }
 
+/// Maps the typed Swift sample onto the UniFFI dictionary one-to-one. `nil`
+/// stays `nil` on every field: the kernel's "absent" is the UniFFI `None`,
+/// never `0`. A non-positive timestamp becomes `0`, which the bridge stamps.
+private func appleDeviceSample(_ sample: ForgeDeviceSample) -> AppleDeviceSample {
+    AppleDeviceSample(
+        sampledAtMs: u64(sample.sampledAtMs),
+        cpuTimeMs: sample.cpuTimeMs,
+        cpuCores: sample.cpuCores,
+        memUsedBytes: sample.memUsedBytes,
+        memAvailBytes: sample.memAvailBytes,
+        batteryLevelPct: sample.batteryLevelPct,
+        batteryCharging: sample.batteryCharging,
+        thermal: sample.thermal.map(appleThermalState),
+        diskFreeBytes: sample.diskFreeBytes
+    )
+}
+
+private func appleThermalState(_ state: ForgeThermalState) -> AppleThermalState {
+    switch state {
+    case .nominal: return .nominal
+    case .fair: return .fair
+    case .serious: return .serious
+    case .critical: return .critical
+    case .emergency: return .emergency
+    }
+}
+
 private func customEventJson(_ payload: CustomVideoEventPayload) -> String? {
     var object: [String: Any] = [
         "name": payload.name,
@@ -652,4 +714,19 @@ private final class UniFFILogListener: AppleLogListener, @unchecked Sendable {
         callback(ForgeRenderedLog(level: level, tag: log.tag, message: log.message))
     }
 }
+
+/// Receives the kernel's device sample requests on the runtime worker thread
+/// and hands the family allowlist to the Swift listener, which must not block
+/// (the collector hops to its own queue).
+private final class UniFFIDeviceSampleListener: AppleDeviceSampleListener, @unchecked Sendable {
+    private let callback: ([String]) -> Void
+
+    init(callback: @escaping ([String]) -> Void) {
+        self.callback = callback
+    }
+
+    func onSampleRequest(families: [String]) {
+        callback(families)
+    }
+}
 #endif

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npaw/forge-react-native",
-  "version": "9.7.3",
+  "version": "9.7.4",
   "description": "NPAW Forge analytics for React Native: New Architecture TurboModule facade over the native Forge Android/Apple SDKs.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Victor Soto <victor.soto@nicepeopleatwork.com>",