@npaw/forge-react-native 9.6.1

package/ios/ForgeModuleImpl.swift

@@ -0,0 +1,1131 @@
+/**
+ * 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: Swift implementation behind the core Forge TurboModule - full facade surface over the Swift NPAWForge facade (sessions, identity, raw/business, network, diagnostics, video fire*, ad reporters, kernel event feed).
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#elseif canImport(NPAWForgeApple)
+import NPAWForgeApple
+#endif
+#if canImport(NPAWForgeNetworkCapture)
+import NPAWForgeNetworkCapture
+#endif
+
+/// Bridge-friendly resolve/reject shapes so this file never imports React.
+public typealias ForgeResolveBlock = (Any?) -> Void
+public typealias ForgeRejectBlock = (String, String) -> Void
+
+@objc(ForgeModuleImpl)
+public final class ForgeModuleImpl: NSObject {
+
+    @objc public static let shared = ForgeModuleImpl()
+
+    /// Set by the TurboModule shell; receives the channel body for every kernel event.
+    @objc public var eventSink: (([String: Any]) -> Void)?
+
+    private let lock = NSLock()
+    private var instances: [String: NPAWForge] = [:]
+    private var subscriptions: [String: ForgeEventSubscription] = [:]
+    private var adReporters: [Int: ManualAdReporter] = [:]
+    private var nextInstanceId = 1
+    private var nextReporterId = 1
+    private var listenerCount = 0
+
+    private static let errUnknownInstance = "E_FORGE_UNKNOWN_INSTANCE"
+    private static let errUnknownReporter = "E_FORGE_UNKNOWN_REPORTER"
+    private static let errBadArgument = "E_FORGE_BAD_ARGUMENT"
+
+    private override init() {
+        super.init()
+    }
+
+    // MARK: - Registry seam for the video package
+
+    public func resolveInstance(_ instanceId: String) -> NPAWForge? {
+        lock.lock()
+        defer { lock.unlock() }
+        return instances[instanceId]
+    }
+
+    // MARK: - Lifecycle
+
+    @objc public func create(
+        _ accountCode: String,
+        config: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        guard !accountCode.trimmingCharacters(in: .whitespaces).isEmpty else {
+            reject(Self.errBadArgument, "accountCode must not be blank")
+            return
+        }
+        let builder = NPAWForge.Builder(accountCode: accountCode)
+        applyConfig(builder, config: config)
+        let forge = builder.build()
+
+        lock.lock()
+        let instanceId = "forge-\(nextInstanceId)"
+        nextInstanceId += 1
+        instances[instanceId] = forge
+        let shouldSubscribe = listenerCount > 0
+        lock.unlock()
+
+        if shouldSubscribe {
+            subscribeInstanceEvents(instanceId, forge: forge)
+        }
+        resolve(instanceId)
+    }
+
+    @objc public func destroy(
+        _ instanceId: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let forge = instances.removeValue(forKey: instanceId)
+        let subscription = subscriptions.removeValue(forKey: instanceId)
+        lock.unlock()
+
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        subscription?.cancel()
+        resolve(Self.outcomeToDictionary(forge.destroy()))
+    }
+
+    @objc public func setLogLevel(
+        _ instanceId: String,
+        level: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) { $0.setLogLevel(level) }
+    }
+
+    // MARK: - App session
+
+    @objc public func startSession(
+        _ instanceId: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) { $0.startSession(metadata ?? [:]) }
+    }
+
+    @objc public func endSession(
+        _ instanceId: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) { $0.endSession(metadata ?? [:]) }
+    }
+
+    @objc public func trackSessionNavigation(
+        _ instanceId: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackSessionNavigation(metadata ?? [:])
+        }
+    }
+
+    @objc public func trackSessionEvent(
+        _ instanceId: String,
+        name: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackSessionEvent(name: name, metadata: metadata ?? [:])
+        }
+    }
+
+    @objc public func trackSessionEventStop(
+        _ instanceId: String,
+        name: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackSessionEventStop(name: name, metadata: metadata ?? [:])
+        }
+    }
+
+    @objc public func trackSessionError(
+        _ instanceId: String,
+        errorCode: String,
+        errorMessage: String,
+        metadata: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackSessionError(errorCode: errorCode, errorMessage: errorMessage, metadata: metadata ?? [:])
+        }
+    }
+
+    // MARK: - Identity
+
+    @objc public func loginSuccess(
+        _ instanceId: String,
+        userId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.loginSuccess(userId: userId, options: Self.stringMap(options))
+        }
+    }
+
+    @objc public func loginFailed(
+        _ instanceId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.loginFailed(options: Self.stringMap(options))
+        }
+    }
+
+    @objc public func logout(
+        _ instanceId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.logout(options: Self.stringMap(options))
+        }
+    }
+
+    @objc public func profileCreated(
+        _ instanceId: String,
+        profileId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.profileCreated(profileId: profileId, options: Self.stringMap(options))
+        }
+    }
+
+    @objc public func profileSelected(
+        _ instanceId: String,
+        profileId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.profileSelected(profileId: profileId, options: Self.stringMap(options))
+        }
+    }
+
+    @objc public func profileDeleted(
+        _ instanceId: String,
+        profileId: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.profileDeleted(profileId: profileId)
+        }
+    }
+
+    // MARK: - Raw / business
+
+    @objc public func trackRawEvent(
+        _ instanceId: String,
+        name: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackRawEvent(name: name, params: params ?? [:])
+        }
+    }
+
+    @objc public func trackSearch(
+        _ instanceId: String,
+        query: String,
+        resultCount: Double,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackSearch(query: query, resultCount: resultCount < 0 ? nil : Int(resultCount))
+        }
+    }
+
+    @objc public func trackSearchResultClick(
+        _ instanceId: String,
+        query: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        let map = Self.stringMap(options)
+        let typed = ForgeSearchResultClickOptions(
+            contentId: map["contentId"],
+            position: map["position"].flatMap { Int($0) }
+        )
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackSearchResultClick(query: query, options: typed)
+        }
+    }
+
+    @objc public func trackBusinessEvent(
+        _ instanceId: String,
+        name: String,
+        attributes: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackBusinessEvent(name: name, attributes: attributes ?? [:])
+        }
+    }
+
+    @objc public func trackAttribution(
+        _ instanceId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        let map = Self.stringMap(options)
+        let typed = ForgeAttributionOptions(
+            utmSource: map["utmSource"],
+            utmMedium: map["utmMedium"],
+            utmCampaign: map["utmCampaign"],
+            utmTerm: map["utmTerm"],
+            utmContent: map["utmContent"],
+            utmUrl: map["utmUrl"]
+        )
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackAttribution(options: typed)
+        }
+    }
+
+    // MARK: - Network
+
+    @objc public func trackNetworkRequest(
+        _ instanceId: String,
+        record: [String: Any],
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withInstance(instanceId, resolve: resolve, reject: reject) {
+            $0.trackNetworkRequest(Self.networkRecord(from: record))
+        }
+    }
+
+    @objc public func installNetworkCapture(
+        _ instanceId: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        // URLSession swizzling captures React Native's networking directly.
+        // FORGE_RN_HYDRATED marks the staged self-contained pod, where the
+        // NetworkCapture sources compile into this module (no import needed).
+        #if canImport(NPAWForgeNetworkCapture) || FORGE_RN_HYDRATED
+        let outcome = ForgeNetworkCapture.install(forge: forge)
+        resolve(Self.outcomeToDictionary(outcome))
+        #else
+        _ = forge
+        resolve(
+            Self.outcomeToDictionary(
+                ForgeOutcome(
+                    code: .unsupportedCapability,
+                    reason: "NPAWForgeNetworkCapture module not present in this build"
+                )
+            )
+        )
+        #endif
+    }
+
+    // MARK: - Diagnostics
+
+    @objc public func snapshotEvents(
+        _ instanceId: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        let items = forge.snapshotEvents().map {
+            Self.recordedEventToDictionary(instanceId: instanceId, event: $0)
+        }
+        resolve(["items": items])
+    }
+
+    // MARK: - Video
+
+    @objc public func createVideo(
+        _ instanceId: String,
+        identifier: String,
+        options: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        let videoOptions = VideoOptions.Builder().metadata(Self.stringMap(options)).build()
+        _ = forge.videoBuilder().setIdentifier(identifier).setOptions(videoOptions).build()
+        resolve(Self.outcomeToDictionary(ForgeOutcome.accepted))
+    }
+
+    @objc public func videoDestroy(
+        _ instanceId: String,
+        identifier: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) { $0.destroy() }
+    }
+
+    @objc public func videoFireInit(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireInit(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireStart(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        forceInit: Bool,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireStart(forceInit: forceInit, params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireJoin(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireJoin(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFirePause(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.firePause(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireResume(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireResume(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireSeekBegin(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        convertFromBuffer: Bool,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireSeekBegin(convertFromBuffer: convertFromBuffer, params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireSeekEnd(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireSeekEnd(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireBufferBegin(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        convertFromSeek: Bool,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireBufferBegin(convertFromSeek: convertFromSeek, params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireBufferEnd(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireBufferEnd(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireStop(
+        _ instanceId: String,
+        identifier: String,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireStop(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func videoFireError(
+        _ instanceId: String,
+        identifier: String,
+        errorCode: String,
+        errorMessage: String,
+        errorMetadata: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireError(
+                errorCode: Self.emptyToNil(errorCode),
+                errorMessage: Self.emptyToNil(errorMessage),
+                errorMetadata: Self.emptyToNil(errorMetadata)
+            )
+        }
+    }
+
+    @objc public func videoFireFatalError(
+        _ instanceId: String,
+        identifier: String,
+        errorCode: String,
+        errorMessage: String,
+        errorMetadata: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireFatalError(
+                errorCode: Self.emptyToNil(errorCode),
+                errorMessage: Self.emptyToNil(errorMessage),
+                errorMetadata: Self.emptyToNil(errorMetadata)
+            )
+        }
+    }
+
+    @objc public func videoFireDestroy(
+        _ instanceId: String,
+        identifier: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireDestroy()
+        }
+    }
+
+    @objc public func videoFireEvent(
+        _ instanceId: String,
+        identifier: String,
+        eventName: String,
+        dimensions: [String: Any]?,
+        values: [String: Any]?,
+        topLevelDimensions: [String: Any]?,
+        hasEndDatetime: Bool,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireEvent(
+                eventName: eventName,
+                dimensions: Self.stringMap(dimensions),
+                values: Self.doubleMap(values),
+                topLevelDimensions: Self.stringMap(topLevelDimensions),
+                hasEndDatetime: hasEndDatetime
+            )
+        }
+    }
+
+    @objc public func videoFireEventEnd(
+        _ instanceId: String,
+        identifier: String,
+        eventName: String,
+        dimensions: [String: Any]?,
+        values: [String: Any]?,
+        topLevelDimensions: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireEventEnd(
+                eventName: eventName,
+                dimensions: Self.stringMap(dimensions),
+                values: Self.doubleMap(values),
+                topLevelDimensions: Self.stringMap(topLevelDimensions)
+            )
+        }
+    }
+
+    @objc public func videoFireMetadataUpdate(
+        _ instanceId: String,
+        identifier: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withVideo(instanceId, identifier: identifier, resolve: resolve, reject: reject) {
+            $0.fireMetadataUpdate()
+        }
+    }
+
+    // MARK: - Ads
+
+    @objc public func createAdReporter(
+        _ instanceId: String,
+        identifier: String,
+        adapterVersion: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        guard let video = forge.getVideoAdapter(identifier: identifier) else {
+            reject(Self.errBadArgument, "No video '\(identifier)' on instance '\(instanceId)'")
+            return
+        }
+        let reporter = video.createAdReporter(adapterVersion: Self.emptyToNil(adapterVersion))
+        lock.lock()
+        let reporterId = nextReporterId
+        nextReporterId += 1
+        adReporters[reporterId] = reporter
+        lock.unlock()
+        resolve(reporterId)
+    }
+
+    @objc public func releaseAdReporter(
+        _ reporterId: Double,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        lock.lock()
+        let removed = adReporters.removeValue(forKey: Int(reporterId))
+        lock.unlock()
+        guard removed != nil else {
+            reject(Self.errUnknownReporter, "No ad reporter \(Int(reporterId))")
+            return
+        }
+        resolve(Self.outcomeToDictionary(ForgeOutcome.accepted))
+    }
+
+    @objc public func adFireManifest(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireManifest(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireBreakStart(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireBreakStart(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireAdInit(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireAdInit(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireStart(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireStart(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireJoin(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireJoin(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFirePause(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.firePause(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireResume(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireResume(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireBufferBegin(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireBufferBegin(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireBufferEnd(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireBufferEnd(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireQuartile(
+        _ reporterId: Double,
+        quartile: Double,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireQuartile(quartile < 0 ? nil : Int(quartile))
+        }
+    }
+
+    @objc public func adFireClick(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireClick(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireSkip(
+        _ reporterId: Double,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) { $0.fireSkip() }
+    }
+
+    @objc public func adFireStop(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireStop(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireError(
+        _ reporterId: Double,
+        errorCode: String,
+        errorMessage: String,
+        errorMetadata: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireError(
+                errorCode: Self.emptyToNil(errorCode),
+                errorMessage: Self.emptyToNil(errorMessage),
+                errorMetadata: Self.emptyToNil(errorMetadata)
+            )
+        }
+    }
+
+    @objc public func adFireFatalError(
+        _ reporterId: Double,
+        errorCode: String,
+        errorMessage: String,
+        errorMetadata: String,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireFatalError(
+                errorCode: Self.emptyToNil(errorCode),
+                errorMessage: Self.emptyToNil(errorMessage),
+                errorMetadata: Self.emptyToNil(errorMetadata)
+            )
+        }
+    }
+
+    @objc public func adFireBreakStop(
+        _ reporterId: Double,
+        params: [String: Any]?,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) {
+            $0.fireBreakStop(params: Self.stringMap(params))
+        }
+    }
+
+    @objc public func adFireDestroy(
+        _ reporterId: Double,
+        resolve: @escaping ForgeResolveBlock,
+        reject: @escaping ForgeRejectBlock
+    ) {
+        withReporter(reporterId, resolve: resolve, reject: reject) { $0.fireDestroy() }
+    }
+
+    // MARK: - Event feed
+
+    @objc public func addListener() {
+        lock.lock()
+        listenerCount += 1
+        let shouldSubscribe = listenerCount == 1
+        let live = shouldSubscribe ? instances : [:]
+        lock.unlock()
+
+        if shouldSubscribe {
+            live.forEach { subscribeInstanceEvents($0.key, forge: $0.value) }
+        }
+    }
+
+    @objc public func removeListeners(_ count: Int) {
+        lock.lock()
+        listenerCount = max(0, listenerCount - count)
+        let shouldCancel = listenerCount == 0
+        let cancelled = shouldCancel ? Array(subscriptions.values) : []
+        if shouldCancel { subscriptions.removeAll() }
+        lock.unlock()
+
+        cancelled.forEach { $0.cancel() }
+    }
+
+    @objc public func invalidate() {
+        lock.lock()
+        let cancelled = Array(subscriptions.values)
+        let live = Array(instances.values)
+        subscriptions.removeAll()
+        instances.removeAll()
+        adReporters.removeAll()
+        listenerCount = 0
+        lock.unlock()
+
+        cancelled.forEach { $0.cancel() }
+        live.forEach { _ = $0.destroy() }
+    }
+
+    // MARK: - Internals
+
+    private func withInstance(
+        _ instanceId: String,
+        resolve: ForgeResolveBlock,
+        reject: ForgeRejectBlock,
+        block: (NPAWForge) -> ForgeOutcome
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        resolve(Self.outcomeToDictionary(block(forge)))
+    }
+
+    private func withVideo(
+        _ instanceId: String,
+        identifier: String,
+        resolve: ForgeResolveBlock,
+        reject: ForgeRejectBlock,
+        block: (VideoAdapter) -> ForgeOutcome
+    ) {
+        lock.lock()
+        let forge = instances[instanceId]
+        lock.unlock()
+        guard let forge else {
+            reject(Self.errUnknownInstance, "No NPAWForge instance '\(instanceId)'")
+            return
+        }
+        guard let video = forge.getVideoAdapter(identifier: identifier) else {
+            // The video may have been legitimately destroyed; report facade
+            // state semantics instead of a programmer error.
+            resolve(Self.outcomeToDictionary(ForgeOutcome.ignoredInvalidState))
+            return
+        }
+        resolve(Self.outcomeToDictionary(block(video)))
+    }
+
+    private func withReporter(
+        _ reporterId: Double,
+        resolve: ForgeResolveBlock,
+        reject: ForgeRejectBlock,
+        block: (ManualAdReporter) -> ForgeOutcome
+    ) {
+        lock.lock()
+        let reporter = adReporters[Int(reporterId)]
+        lock.unlock()
+        guard let reporter else {
+            reject(Self.errUnknownReporter, "No ad reporter \(Int(reporterId))")
+            return
+        }
+        resolve(Self.outcomeToDictionary(block(reporter)))
+    }
+
+    private func subscribeInstanceEvents(_ instanceId: String, forge: NPAWForge) {
+        lock.lock()
+        if subscriptions[instanceId] != nil {
+            lock.unlock()
+            return
+        }
+        lock.unlock()
+
+        let subscription = forge.subscribeEvents { [weak self] event, _ in
+            guard let self, let sink = self.eventSink else { return }
+            sink(Self.recordedEventToDictionary(instanceId: instanceId, event: event))
+        }
+        lock.lock()
+        subscriptions[instanceId] = subscription
+        lock.unlock()
+    }
+
+    private func applyConfig(_ builder: NPAWForge.Builder, config: [String: Any]?) {
+        guard let config else { return }
+        for (key, value) in config {
+            switch key {
+            case "appName":
+                builder.setAppName(value as? String)
+            case "appReleaseVersion":
+                builder.setAppReleaseVersion(value as? String)
+            case "buildVariant":
+                builder.setBuildVariant(value as? String)
+            case "lmaEndpoint":
+                builder.setLmaEndpoint(value as? String)
+            case "analyticsUserAgent":
+                builder.setAnalyticsUserAgent(value as? String)
+            case "logLevel":
+                builder.setLogLevel(value)
+            case "startSessionOnInitialize":
+                builder.setStartSessionOnInitialize(value as? Bool ?? false)
+            case "processEventsBeforeSessionStart":
+                builder.setProcessEventsBeforeSessionStart(value as? Bool ?? false)
+            case "preSessionEventQueueLimitEvents":
+                builder.setPreSessionEventQueueLimitEvents((value as? NSNumber)?.intValue ?? 100)
+            case "preSessionEventQueueMaxAgeMs":
+                builder.setPreSessionEventQueueMaxAgeMs((value as? NSNumber)?.int64Value ?? 0)
+            case "allowLocalHttpForTesting":
+                builder.setLocalPlaintextTransportForTesting(value as? Bool ?? false)
+            case "deviceUuid", "autoDeviceIdentityEnabled":
+                // Android-only today: the Swift Builder lacks these setters.
+                NSLog("[NPAWForgeRN] ForgeConfig key '%@' is Android-only; ignored on iOS", key)
+            default:
+                NSLog("[NPAWForgeRN] Unknown ForgeConfig key '%@' ignored (forward compatibility)", key)
+            }
+        }
+    }
+
+    private static func networkRecord(from map: [String: Any]) -> NetworkRequestRecord {
+        var record = NetworkRequestRecord(
+            targetUrl: map["targetUrl"] as? String ?? "",
+            method: map["method"] as? String ?? "GET",
+            responseStatusCode: (map["responseStatusCode"] as? NSNumber)?.intValue ?? 0,
+            durationMs: int64(map["durationMs"]) ?? 0,
+            outcome: NetworkRequestOutcome(rawValue: map["outcome"] as? String ?? "unknown") ?? .unknown
+        )
+        record.responseStatusText = map["responseStatusText"] as? String
+        record.errorMessage = map["errorMessage"] as? String
+        record.traceparent = map["traceparent"] as? String
+        record.dnsDurationMs = int64(map["dnsDurationMs"])
+        record.connectDurationMs = int64(map["connectDurationMs"])
+        record.sslDurationMs = int64(map["sslDurationMs"])
+        record.requestDurationMs = int64(map["requestDurationMs"])
+        record.timeToFirstByteMs = int64(map["timeToFirstByteMs"])
+        record.responseDownloadDurationMs = int64(map["responseDownloadDurationMs"])
+        record.redirectDurationMs = int64(map["redirectDurationMs"])
+        record.redirectCount = int64(map["redirectCount"])
+        record.networkProtocol = map["protocol"] as? String
+        record.requestBytes = int64(map["requestBytes"])
+        record.responseBytes = int64(map["responseBytes"])
+        return record
+    }
+
+    private static func int64(_ value: Any?) -> Int64? {
+        (value as? NSNumber)?.int64Value
+    }
+
+    private static func emptyToNil(_ value: String) -> String? {
+        value.isEmpty ? nil : value
+    }
+
+    private static func stringMap(_ map: [String: Any]?) -> [String: String] {
+        guard let map else { return [:] }
+        var result: [String: String] = [:]
+        for (key, value) in map {
+            switch value {
+            case let string as String:
+                result[key] = string
+            case let number as NSNumber:
+                if number === kCFBooleanTrue || number === kCFBooleanFalse {
+                    result[key] = number.boolValue ? "true" : "false"
+                } else if number.doubleValue == number.doubleValue.rounded()
+                    && abs(number.doubleValue) < 9_007_199_254_740_992 {
+                    result[key] = String(number.int64Value)
+                } else {
+                    result[key] = number.stringValue
+                }
+            default:
+                result[key] = String(describing: value)
+            }
+        }
+        return result
+    }
+
+    private static func doubleMap(_ map: [String: Any]?) -> [String: Double] {
+        guard let map else { return [:] }
+        var result: [String: Double] = [:]
+        for (key, value) in map {
+            if let number = value as? NSNumber {
+                result[key] = number.doubleValue
+            }
+        }
+        return result
+    }
+
+    static func outcomeToDictionary(_ outcome: ForgeOutcome) -> [String: Any] {
+        var result: [String: Any] = [
+            "code": outcome.code.wireName,
+            "isAccepted": outcome.isAccepted,
+        ]
+        if let reason = outcome.reason {
+            result["reason"] = reason
+        }
+        if !outcome.details.isEmpty {
+            result["details"] = outcome.details
+        }
+        return result
+    }
+
+    static func recordedEventToDictionary(
+        instanceId: String,
+        event: ForgeRecordedEvent
+    ) -> [String: Any] {
+        var result: [String: Any] = [
+            "instanceId": instanceId,
+            "eventName": event.eventName,
+            "timestampMs": Double(event.timestampMs),
+            "payload": event.payload,
+            "urgent": event.urgent,
+        ]
+        if let viewKey = event.viewKey {
+            result["viewKey"] = viewKey
+        }
+        return result
+    }
+}