@npaw/forge-react-native 9.7.5 → 10.0.0

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

@@ -27,6 +27,12 @@ public struct ForgeAppleConfig: Equatable {
     public var processEventsBeforeSessionStart: Bool
     public var preSessionEventQueueLimitEvents: Int
     public var preSessionEventQueueMaxAgeMs: Int64
+    /// Logout guard window in milliseconds (session-update mode only): after
+    /// `logout()` closes the session, the kernel holds the replacement
+    /// session back for this long so a follow-up `loginSuccess` attaches its
+    /// own session directly; events raised inside the window are buffered
+    /// with their original timestamps. `0` disables the guard.
+    public var logoutSessionGuardMs: Int64
     public var logLevel: ForgeLogLevel
     public var deviceUuid: String?
     public var deviceInfo: ForgeDeviceInfo?
@@ -48,6 +54,7 @@ public struct ForgeAppleConfig: Equatable {
         processEventsBeforeSessionStart: Bool = false,
         preSessionEventQueueLimitEvents: Int = 100,
         preSessionEventQueueMaxAgeMs: Int64 = 30_000,
+        logoutSessionGuardMs: Int64 = 30_000,
         logLevel: ForgeLogLevel = .warning,
         deviceUuid: String? = nil,
         deviceInfo: ForgeDeviceInfo? = nil,
@@ -65,6 +72,7 @@ public struct ForgeAppleConfig: Equatable {
         self.processEventsBeforeSessionStart = processEventsBeforeSessionStart
         self.preSessionEventQueueLimitEvents = preSessionEventQueueLimitEvents
         self.preSessionEventQueueMaxAgeMs = preSessionEventQueueMaxAgeMs
+        self.logoutSessionGuardMs = logoutSessionGuardMs
         self.logLevel = logLevel
         self.deviceUuid = deviceUuid
         self.deviceInfo = deviceInfo
@@ -143,7 +151,10 @@ public final class ForgeApple {
     private let lock = NSRecursiveLock()
     private var recordedEvents: [ForgeRecordedEvent] = []
     private var eventObservers: [UUID: (ForgeRecordedEvent, ForgeOutcome) -> Void] = [:]
-    private var onSendRequestListeners: [UUID: (String, inout [String: String]) -> Void] = [:]
+    /// Registration-ordered, matching Android's CopyOnWriteArrayList: when two
+    /// listeners edit the same param, the later registration wins
+    /// deterministically on both platforms.
+    private var onSendRequestListeners: [(id: UUID, listener: (String, inout [String: WireValue]) -> Void)] = []
     private var capturePlanObservers: [UUID: (ForgeCapturePlan) -> Void] = [:]
     private var latestCapturePlan: ForgeCapturePlan?
     private var logObservers: [UUID: (ForgeRenderedLog) -> Void] = [:]
@@ -359,6 +370,35 @@ public final class ForgeApple {
         recordIdentityEvent(kind: "profileDeleted", fields: ["profileId": profileId])
     }
 
+    /// Hot-updates session-level dimensions without a session boundary:
+    /// `param1`..`param20` extraparams, `screenName`, or any dimension the
+    /// NQS parameter registry marks updatable - new backend dimensions work
+    /// without an SDK release. Identity keys are rejected by the kernel (use
+    /// the typed identity API); blank values are dropped because NQS never
+    /// erases a session value. Requires the account's remote config to
+    /// enable session updates.
+    public func updateSession(_ metadata: [String: String], timestampMs: Int64 = 0) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        return runtime.recordSessionUpdate(
+            timemarkMs: timestampMs,
+            params: PrivacySanitizer.sanitize(metadata),
+            metrics: [:]
+        )
+    }
+
+    /// Reports numeric session metrics (account-registered custom metrics).
+    /// Values aggregate server-side per the account's registered operation
+    /// and settle on the session close row; re-sending an unchanged value is
+    /// a no-op. Same remote-config gating as `updateSession`.
+    public func updateSessionMetrics(_ metrics: [String: Double], timestampMs: Int64 = 0) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        return runtime.recordSessionUpdate(timemarkMs: timestampMs, params: [:], metrics: metrics)
+    }
+
     /// Forwards a typed identity transition to the runtime. Recognized fields
     /// (`userId`, `profileId`, `profileType`, `method`, `errorCode`, `reason`,
     /// `userType`) are consumed by the kernel; remaining entries ride as extra
@@ -492,15 +532,15 @@ public final class ForgeApple {
         runtime.registerSessionPreSendHook(hook)
     }
 
-    public func addOnSendRequestListener(_ listener: @escaping (String, inout [String: String]) -> Void) -> ForgeEventSubscription {
+    public func addOnSendRequestListener(_ listener: @escaping (String, inout [String: WireValue]) -> Void) -> ForgeEventSubscription {
         let id = UUID()
         lock.lock()
-        onSendRequestListeners[id] = listener
+        onSendRequestListeners.append((id: id, listener: listener))
         lock.unlock()
         refreshSessionPreSendHook()
         return ForgeEventSubscription { [weak self] in
             self?.lock.lock()
-            self?.onSendRequestListeners.removeValue(forKey: id)
+            self?.onSendRequestListeners.removeAll { $0.id == id }
             self?.lock.unlock()
             self?.refreshSessionPreSendHook()
         }
@@ -672,7 +712,7 @@ public final class ForgeApple {
         let hook = SessionPreSendHook { [weak self] serviceName, params in
             guard let self else { return }
             self.lock.lock()
-            let listeners = Array(self.onSendRequestListeners.values)
+            let listeners = self.onSendRequestListeners.map(\.listener)
             self.lock.unlock()
             listeners.forEach { $0(serviceName, &params) }
         }
@@ -707,13 +747,13 @@ public final class ForgeEventSubscription {
 }
 
 private final class SessionPreSendHook: RuntimeSessionPreSendHook {
-    private let callback: (String, inout [String: String]) -> Void
+    private let callback: (String, inout [String: WireValue]) -> Void
 
-    init(callback: @escaping (String, inout [String: String]) -> Void) {
+    init(callback: @escaping (String, inout [String: WireValue]) -> Void) {
         self.callback = callback
     }
 
-    func willSendRequest(serviceName: String, params: inout [String: String]) {
+    func willSendRequest(serviceName: String, params: inout [String: WireValue]) {
         callback(serviceName, &params)
     }
 }

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

@@ -48,17 +48,23 @@ public protocol RuntimeContentMetadataProvider: AnyObject {
     func metadataSnapshot(timemarkMs: Int64, elapsedRealtimeMs: Int64) -> MetadataSnapshot?
 }
 
+/// Per-view pre-send hook. `params` is the request payload as the typed
+/// values the wire will carry — see ``WireValue`` for the encoding and the
+/// two deliberate escape hatches (string re-typing, byte-identical
+/// untouched values).
 public protocol RuntimeVideoPreSendHook: AnyObject {
     func willSendRequest(
         eventName: String,
         view: RuntimeVideoView,
         serviceName: String,
-        params: inout [String: String]
+        params: inout [String: WireValue]
     )
 }
 
+/// Session-scope counterpart of ``RuntimeVideoPreSendHook``; same typed
+/// payload contract.
 public protocol RuntimeSessionPreSendHook: AnyObject {
-    func willSendRequest(serviceName: String, params: inout [String: String])
+    func willSendRequest(serviceName: String, params: inout [String: WireValue])
 }
 
 public protocol ForgeRuntime: AnyObject {
@@ -91,6 +97,10 @@ public protocol ForgeRuntime: AnyObject {
     /// `profileType`, `method`, `errorCode`, `reason`, `userType`), forwards
     /// the rest as extra session-event params, and emits the taxonomy event.
     func recordIdentityEvent(kind: String, timemarkMs: Int64, fields: [String: String]) -> ForgeOutcome
+    /// Hot session update (session-update mode): flat dimension params plus
+    /// numeric session metrics staged by the kernel and carried on the next
+    /// session event or an update beat.
+    func recordSessionUpdate(timemarkMs: Int64, params: [String: String], metrics: [String: Double]) -> ForgeOutcome
     func recordApplicationForeground(_ foreground: Bool, timestampMs: Int64) -> ForgeOutcome
     func recordNetworkEvent(_ record: NetworkRequestRecord) -> ForgeOutcome
     func recordPlayerEvent(
@@ -138,6 +148,9 @@ public extension ForgeRuntime {
     /// Additive default: runtimes without kernel identity support report the
     /// capability gap instead of silently accepting the transition.
     func recordIdentityEvent(kind: String, timemarkMs: Int64, fields: [String: String]) -> ForgeOutcome { .unsupportedCapability }
+    /// Additive default: runtimes without kernel session-update support report
+    /// the capability gap instead of silently accepting the update.
+    func recordSessionUpdate(timemarkMs: Int64, params: [String: String], metrics: [String: Double]) -> ForgeOutcome { .unsupportedCapability }
     /// Additive default: a runtime with no kernel behind it has nowhere to keep
     /// the observed connection class, so it accepts and forgets.
     func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome { .accepted }
@@ -171,6 +184,7 @@ public final class UnavailableForgeRuntime: ForgeRuntime {
     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() }
+    public func recordSessionUpdate(timemarkMs: Int64, params: [String: String], metrics: [String: Double]) -> ForgeOutcome { failed() }
     public func recordApplicationForeground(_ foreground: Bool, timestampMs: Int64) -> ForgeOutcome { failed() }
     public func recordNetworkEvent(_ record: NetworkRequestRecord) -> ForgeOutcome { failed() }
     public func recordPlayerEvent(
@@ -217,6 +231,7 @@ public final class NativeForgeRuntimeFactory: ForgeRuntimeFactory {
 public final class RecordingForgeRuntime: ForgeRuntime {
     public private(set) var events: [ForgeRecordedEvent] = []
     public private(set) var identityEvents: [(kind: String, timemarkMs: Int64, fields: [String: String])] = []
+    public private(set) var sessionUpdates: [(timemarkMs: Int64, params: [String: String], metrics: [String: Double])] = []
     public private(set) var playerEvents: [(RuntimeVideoView, PlayerEvent, PlayerMetadataSnapshot)] = []
     public private(set) var playerEventTimestamps: [(timemarkMs: Int64, elapsedRealtimeMs: Int64)] = []
     public private(set) var playerEventOptions: [VideoOptions] = []
@@ -290,6 +305,11 @@ public final class RecordingForgeRuntime: ForgeRuntime {
         identityEvents.append((kind, timemarkMs, fields))
         return .accepted
     }
+
+    public func recordSessionUpdate(timemarkMs: Int64, params: [String: String], metrics: [String: Double]) -> ForgeOutcome {
+        sessionUpdates.append((timemarkMs, params, metrics))
+        return .accepted
+    }
     public func recordApplicationForeground(_ foreground: Bool, timestampMs: Int64) -> ForgeOutcome {
         events.append(
             ForgeRecordedEvent(

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.5"
+    public static let defaultPluginVersion = "10.0.0"
     public static let defaultAppName = "apple"
     public static let defaultBuildVariant = "release"
     public static let defaultLmaEndpoint = "https://lma.npaw.com"
@@ -135,7 +135,7 @@ public final class NPAWForge: NSObject {
         kernel.capturePlan()
     }
 
-    public func addOnSendRequestListener(_ listener: @escaping (String, inout [String: String]) -> Void) -> ForgeEventSubscription {
+    public func addOnSendRequestListener(_ listener: @escaping (String, inout [String: WireValue]) -> Void) -> ForgeEventSubscription {
         kernel.addOnSendRequestListener(listener)
     }
 
@@ -200,6 +200,25 @@ public final class NPAWForge: NSObject {
         kernel.trackAttribution(options: options)
     }
 
+    /// Hot-updates session-level dimensions without a session boundary:
+    /// `param1`..`param20` extraparams, `screenName`, or any dimension the
+    /// NQS parameter registry marks updatable - new backend dimensions work
+    /// without an SDK release. The change reaches NQS on the next session
+    /// event within one second, or on an immediate beat after that window.
+    /// Identity keys are rejected - use the typed identity API. Requires the
+    /// account's remote config to enable session updates.
+    @objc public func updateSession(_ metadata: [String: Any]) -> ForgeOutcome {
+        kernel.updateSession(metadata.toStringMap())
+    }
+
+    /// Reports numeric session metrics (account-registered custom metrics).
+    /// Values aggregate server-side per the account's registered operation
+    /// and settle on the session close row; re-sending an unchanged value is
+    /// a no-op. Same remote-config gating as `updateSession(_:)`.
+    @objc public func updateSessionMetrics(_ metrics: [String: Double]) -> ForgeOutcome {
+        kernel.updateSessionMetrics(metrics)
+    }
+
     /// Reports a successful login; the kernel emits `login
     /// {authStatus:"success"}` and atomically restarts the app session when
     /// the effective identity changed.
@@ -392,6 +411,7 @@ public final class NPAWForge: NSObject {
         private var processEventsBeforeSessionStart = false
         private var preSessionEventQueueLimitEvents = 100
         private var preSessionEventQueueMaxAgeMs: Int64 = 30_000
+        private var logoutSessionGuardMs: Int64 = 30_000
         private var logLevel: ForgeLogLevel = .warning
         private var autoDeviceIdentityEnabled = true
         private var autoConnectionTypeEnabled = true
@@ -464,6 +484,17 @@ public final class NPAWForge: NSObject {
             return self
         }
 
+        /// Logout guard window in milliseconds (session-update mode only):
+        /// after `logout()` closes the session, the kernel holds the
+        /// replacement session back for this long so a follow-up
+        /// `loginSuccess` attaches its own session directly; events raised
+        /// inside the window are buffered with their original timestamps.
+        /// `0` disables the guard. Default 30 000.
+        @discardableResult public func setLogoutSessionGuardMs(_ guardMs: Int64) -> Builder {
+            logoutSessionGuardMs = max(0, guardMs)
+            return self
+        }
+
         @discardableResult public func setLogLevel(_ value: Any?) -> Builder {
             logLevel = ForgeLogLevel.from(value)
             return self
@@ -562,6 +593,7 @@ public final class NPAWForge: NSObject {
                 processEventsBeforeSessionStart: processEventsBeforeSessionStart,
                 preSessionEventQueueLimitEvents: preSessionEventQueueLimitEvents,
                 preSessionEventQueueMaxAgeMs: preSessionEventQueueMaxAgeMs,
+                logoutSessionGuardMs: logoutSessionGuardMs,
                 logLevel: logLevel,
                 deviceUuid: resolvedDeviceUuid,
                 deviceInfo: resolvedDeviceInfo?.isEmpty == true ? nil : resolvedDeviceInfo,

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

@@ -47,7 +47,8 @@ final class UniFFIForgeRuntime: ForgeRuntime {
                 processEventsBeforeSessionStart: config.processEventsBeforeSessionStart,
                 queueLimitEvents: UInt64(max(0, config.preSessionEventQueueLimitEvents)),
                 maxAgeMs: u64(config.preSessionEventQueueMaxAgeMs)
-            )
+            ),
+            logoutSessionGuardMs: u64(config.logoutSessionGuardMs)
         ))
     }
 
@@ -132,6 +133,14 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         ))
     }
 
+    func recordSessionUpdate(timemarkMs: Int64, params: [String: String], metrics: [String: Double]) -> ForgeOutcome {
+        outcome(bridge.recordSessionUpdate(
+            timemarkMs: u64(timemarkMs),
+            params: params,
+            metrics: metrics
+        ))
+    }
+
     func recordApplicationForeground(_ foreground: Bool, timestampMs: Int64) -> ForgeOutcome {
         outcome(bridge.recordApplicationForeground(foreground: foreground, timemarkMs: u64(timestampMs)))
     }
@@ -653,6 +662,32 @@ private final class UniFFIContentMetadataProvider: AppleContentMetadataProvider,
     }
 }
 
+// MARK: - WireValue boundary conversions
+
+extension WireValue {
+    init(bridged: AppleWireValue) {
+        switch bridged {
+        case let .str(value): self = .string(value)
+        case let .int(value): self = .int(value)
+        case let .num(value): self = .number(value)
+        case let .bool(value): self = .bool(value)
+        case let .object(value): self = .object(value.mapValues(WireValue.init(bridged:)))
+        case let .array(value): self = .array(value.map(WireValue.init(bridged:)))
+        }
+    }
+
+    var bridged: AppleWireValue {
+        switch self {
+        case let .string(value): return .str(value: value)
+        case let .int(value): return .int(value: value)
+        case let .number(value): return .num(value: value)
+        case let .bool(value): return .bool(value: value)
+        case let .object(value): return .object(value: value.mapValues(\.bridged))
+        case let .array(value): return .array(value: value.map(\.bridged))
+        }
+    }
+}
+
 private final class UniFFIVideoPreSendHook: AppleVideoPreSendHook, @unchecked Sendable {
     private let view: RuntimeVideoView
     private let hook: RuntimeVideoPreSendHook
@@ -662,15 +697,15 @@ private final class UniFFIVideoPreSendHook: AppleVideoPreSendHook, @unchecked Se
         self.hook = hook
     }
 
-    func willSend(eventName: String, viewId: UInt64, serviceName: String, params: [String: String]) -> [String: String] {
-        var mutableParams = params
+    func willSend(eventName: String, viewId: UInt64, serviceName: String, params: [String: AppleWireValue]) -> [String: AppleWireValue] {
+        var mutableParams = params.mapValues(WireValue.init(bridged:))
         hook.willSendRequest(
             eventName: eventName,
             view: view.id == i64(viewId) ? view : RuntimeVideoView(id: i64(viewId)),
             serviceName: serviceName,
             params: &mutableParams
         )
-        return mutableParams
+        return mutableParams.mapValues(\.bridged)
     }
 }
 
@@ -681,10 +716,10 @@ private final class UniFFISessionPreSendHook: AppleSessionPreSendHook, @unchecke
         self.hook = hook
     }
 
-    func willSend(serviceName: String, params: [String: String]) -> [String: String] {
-        var mutableParams = params
+    func willSend(serviceName: String, params: [String: AppleWireValue]) -> [String: AppleWireValue] {
+        var mutableParams = params.mapValues(WireValue.init(bridged:))
         hook.willSendRequest(serviceName: serviceName, params: &mutableParams)
-        return mutableParams
+        return mutableParams.mapValues(\.bridged)
     }
 }
 

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

@@ -134,6 +134,20 @@ public final class NPAWForgeObjC: NSObject {
         ))
     }
 
+    @objc(updateSessionWithMetadata:)
+    public func updateSession(metadata: NSDictionary?) -> ForgeOutcome {
+        swiftForge.updateSession(metadata as? [String: Any] ?? [:])
+    }
+
+    @objc(updateSessionMetricsWithMetrics:)
+    public func updateSessionMetrics(metrics: NSDictionary?) -> ForgeOutcome {
+        var converted: [String: Double] = [:]
+        for case let (key as String, value as NSNumber) in metrics ?? [:] {
+            converted[key] = value.doubleValue
+        }
+        return swiftForge.updateSessionMetrics(converted)
+    }
+
     @objc(loginSuccessWithUserId:options:)
     public func loginSuccess(userId: String, options: NSDictionary?) -> ForgeOutcome {
         swiftForge.loginSuccess(userId: userId, options: options.toStringStringMap())

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

@@ -70,7 +70,7 @@ public final class VideoAdapter: RuntimeContentMetadataProvider {
     private var effectiveOptions: VideoOptions
     private let runtimeView: RuntimeVideoView
     private var destroyed = false
-    private var willSendRequestListener: ((String, String, VideoAdapter, inout [String: String]) -> Void)?
+    private var willSendRequestListener: ((String, String, VideoAdapter, inout [String: WireValue]) -> Void)?
 
     public private(set) var playerAdapter: PlayerAdapter?
     public private(set) var adAdapter: AdAdapter?
@@ -113,7 +113,7 @@ public final class VideoAdapter: RuntimeContentMetadataProvider {
     /// addressed to `error` and `stop`, both carrying the same `eventName` — so
     /// without the service name that correct pair is indistinguishable from a
     /// duplicate.
-    public func setWillSendRequestListener(_ listener: ((String, String, VideoAdapter, inout [String: String]) -> Void)?) -> ForgeOutcome {
+    public func setWillSendRequestListener(_ listener: ((String, String, VideoAdapter, inout [String: WireValue]) -> Void)?) -> ForgeOutcome {
         guard !destroyed else { return .ignoredInvalidState }
         willSendRequestListener = listener
         let hook = listener.map { callback in
@@ -475,13 +475,13 @@ private extension AdInsertionType {
 }
 
 private final class VideoPreSendHook: RuntimeVideoPreSendHook {
-    private let callback: (String, RuntimeVideoView, String, inout [String: String]) -> Void
+    private let callback: (String, RuntimeVideoView, String, inout [String: WireValue]) -> Void
 
-    init(callback: @escaping (String, RuntimeVideoView, String, inout [String: String]) -> Void) {
+    init(callback: @escaping (String, RuntimeVideoView, String, inout [String: WireValue]) -> Void) {
         self.callback = callback
     }
 
-    func willSendRequest(eventName: String, view: RuntimeVideoView, serviceName: String, params: inout [String: String]) {
+    func willSendRequest(eventName: String, view: RuntimeVideoView, serviceName: String, params: inout [String: WireValue]) {
         callback(eventName, view, serviceName, &params)
     }
 }

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

@@ -0,0 +1,207 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Typed wire value the pre-send request hooks see and edit.
+ */
+
+import Foundation
+
+/// One request-body param as the wire carries it.
+///
+/// The NQS POST body is typed JSON: quantities are numbers, flags are
+/// booleans, and nested documents (`entities`, `metrics`, `dimensions`,
+/// `deviceInfo`, …) are nested objects. Pre-send hooks see and edit exactly
+/// that encoding — what you read is what the wire says, and what you write is
+/// what the wire will say.
+///
+/// Literal conformances keep hook code natural:
+///
+/// ```swift
+/// params["contentId"] = "movie-42"   // .string
+/// params["bitrate"] = 4_316_400      // .int
+/// params["playhead"] = 645.75        // .number
+/// params["live"] = true              // .bool
+/// params["dimensions"] = ["genre": "sports"]
+/// ```
+///
+/// Two escape hatches are deliberate:
+/// - A string written where a numeric or boolean param is declared (for
+///   example `params["bitrate"] = "4316400"`, the all-strings habit) is
+///   re-typed by the kernel before sending, so ported hook code keeps
+///   producing the same wire.
+/// - A param the hook leaves content-equal is sent byte-identical to its
+///   pre-hook form — key order of untouched nested documents included — so
+///   registering a hook never changes traffic the hook did not edit.
+public enum WireValue: Equatable, Hashable {
+    case string(String)
+    /// An integral number. Serializes without a decimal point (`28899`).
+    case int(Int64)
+    /// A floating-point number. Keeps its spelling (`1.0` stays `1.0`).
+    case number(Double)
+    case bool(Bool)
+    case object([String: WireValue])
+    case array([WireValue])
+}
+
+extension WireValue: ExpressibleByStringLiteral {
+    public init(stringLiteral value: String) { self = .string(value) }
+}
+
+extension WireValue: ExpressibleByIntegerLiteral {
+    public init(integerLiteral value: Int64) { self = .int(value) }
+}
+
+extension WireValue: ExpressibleByFloatLiteral {
+    public init(floatLiteral value: Double) { self = .number(value) }
+}
+
+extension WireValue: ExpressibleByBooleanLiteral {
+    public init(booleanLiteral value: Bool) { self = .bool(value) }
+}
+
+extension WireValue: ExpressibleByDictionaryLiteral {
+    public init(dictionaryLiteral elements: (String, WireValue)...) {
+        self = .object(Dictionary(uniqueKeysWithValues: elements))
+    }
+}
+
+extension WireValue: ExpressibleByArrayLiteral {
+    public init(arrayLiteral elements: WireValue...) { self = .array(elements) }
+}
+
+public extension WireValue {
+    /// The string payload, when this value is a string.
+    var stringValue: String? {
+        if case let .string(value) = self { return value }
+        return nil
+    }
+
+    /// The integral payload. An integral `.number` (`4.0`) converts; a
+    /// fractional one does not.
+    var intValue: Int64? {
+        switch self {
+        case let .int(value): return value
+        case let .number(value)
+            where value.truncatingRemainder(dividingBy: 1) == 0
+                && value >= -9_007_199_254_740_992 && value <= 9_007_199_254_740_992:
+            return Int64(value)
+        default: return nil
+        }
+    }
+
+    /// The numeric payload, integral or floating.
+    var doubleValue: Double? {
+        switch self {
+        case let .int(value): return Double(value)
+        case let .number(value): return value
+        default: return nil
+        }
+    }
+
+    /// The boolean payload, when this value is a boolean.
+    var boolValue: Bool? {
+        if case let .bool(value) = self { return value }
+        return nil
+    }
+
+    /// The nested object payload, when this value is an object.
+    var objectValue: [String: WireValue]? {
+        if case let .object(value) = self { return value }
+        return nil
+    }
+
+    /// The nested array payload, when this value is an array.
+    var arrayValue: [WireValue]? {
+        if case let .array(value) = self { return value }
+        return nil
+    }
+
+    /// The text this value renders to where a string is needed: the payload
+    /// itself for a string, the canonical JSON text for everything else.
+    ///
+    /// Scalars render exactly as the wire does. One divergence is inherent to
+    /// Swift: `.object` renders with its keys **sorted**, because a Swift
+    /// dictionary has no insertion order to preserve — the wire itself keeps
+    /// authored order (untouched values byte-repaired by the kernel), so use
+    /// this for reading and logging, not as a byte-level mirror of a nested
+    /// document on the wire.
+    var textValue: String {
+        switch self {
+        case let .string(value): return value
+        case let .int(value): return String(value)
+        case let .number(value): return jsonNumberText(value)
+        case let .bool(value): return value ? "true" : "false"
+        case .object, .array:
+            return jsonText
+        }
+    }
+}
+
+extension WireValue: CustomStringConvertible {
+    public var description: String { textValue }
+}
+
+public extension WireValue {
+    /// Canonical JSON text of this value. Object keys render sorted — see
+    /// ``textValue`` for why.
+    var jsonText: String {
+        switch self {
+        case let .string(value):
+            return escapedJSONString(value)
+        case let .int(value):
+            return String(value)
+        case let .number(value):
+            return jsonNumberText(value)
+        case let .bool(value):
+            return value ? "true" : "false"
+        case let .object(value):
+            let fields = value
+                .sorted { $0.key < $1.key }
+                .map { "\(escapedJSONString($0.key)):\($0.value.jsonText)" }
+            return "{\(fields.joined(separator: ","))}"
+        case let .array(value):
+            return "[\(value.map(\.jsonText).joined(separator: ","))]"
+        }
+    }
+}
+
+/// Renders a double the way the wire does: integral values keep one decimal
+/// (`1.0`), fractional values keep their precision.
+private func jsonNumberText(_ value: Double) -> String {
+    guard value.isFinite else { return String(describing: value) }
+    if value.truncatingRemainder(dividingBy: 1) == 0, abs(value) < 1e15 {
+        return String(format: "%.1f", value)
+    }
+    var text = String(value)
+    // Swift renders some doubles in exponent form ("1e+16"); JSON accepts it.
+    if text.hasSuffix(".0") { text.removeLast(2); text += ".0" }
+    return text
+}
+
+private func escapedJSONString(_ value: String) -> String {
+    var escaped = "\""
+    for scalar in value.unicodeScalars {
+        switch scalar {
+        case "\"": escaped += "\\\""
+        case "\\": escaped += "\\\\"
+        case "\n": escaped += "\\n"
+        case "\r": escaped += "\\r"
+        case "\t": escaped += "\\t"
+        default:
+            if scalar.value < 0x20 {
+                escaped += String(format: "\\u%04x", scalar.value)
+            } else {
+                escaped.unicodeScalars.append(scalar)
+            }
+        }
+    }
+    return escaped + "\""
+}

package/ios/ForgeModuleImpl.swift

@@ -194,6 +194,37 @@ public final class ForgeModuleImpl: NSObject {
         }
     }
 
+    // MARK: - Session updates
+
+    @objc public func updateSession(
+        _ instanceId: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.updateSession(metadata ?? [:])
+        }
+    }
+
+    @objc public func updateSessionMetrics(
+        _ instanceId: String,
+        metrics: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        var converted: [String: Double] = [:]
+        for (key, value) in metrics ?? [:] {
+            if let number = value as? NSNumber {
+                converted[key] = number.doubleValue
+            }
+        }
+        let numeric = converted
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.updateSessionMetrics(numeric)
+        }
+    }
+
     // MARK: - Identity
 
     @objc public func loginSuccess(
@@ -1045,6 +1076,8 @@ public final class ForgeModuleImpl: NSObject {
                 builder.setPreSessionEventQueueLimitEvents((value as? NSNumber)?.intValue ?? 100)
             case "preSessionEventQueueMaxAgeMs":
                 builder.setPreSessionEventQueueMaxAgeMs((value as? NSNumber)?.int64Value ?? 0)
+            case "logoutSessionGuardMs":
+                builder.setLogoutSessionGuardMs((value as? NSNumber)?.int64Value ?? 30_000)
             case "allowLocalHttpForTesting":
                 builder.setLocalPlaintextTransportForTesting(value as? Bool ?? false)
             case "deviceUuid":