@npaw/forge-react-native 9.6.1

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

@@ -0,0 +1,431 @@
+/**
+ * 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: Apple video option builder and ordered override transport JSON writer.
+ */
+
+import Foundation
+
+public struct VideoOptions: Equatable {
+    public enum JoinTimeCalculationMode: String {
+        case `default` = "DEFAULT"
+        case legacy = "LEGACY"
+    }
+
+    public var metadata: [String: String]
+    public var joinTimeCalculationMode: JoinTimeCalculationMode?
+    public var adJoinFromAdBreakStart: Bool?
+    public var adConnectedRequiresAdJoin: Bool?
+    public var contentIsLiveNoSeek: Bool?
+    public var ignorePauseSmallEvents: Bool?
+    public var forceInit: Bool?
+    public var waitForMetadata: Bool?
+    public var waitForMetadataTimeout: Int64?
+    public var pendingMetadata: [String]?
+    public var overridesJson: String
+
+    public var hasContentDurationOverride: Bool {
+        metadata["mediaDuration"] != nil
+    }
+
+    public init(
+        metadata: [String: String] = [:],
+        joinTimeCalculationMode: JoinTimeCalculationMode? = nil,
+        adJoinFromAdBreakStart: Bool? = nil,
+        adConnectedRequiresAdJoin: Bool? = nil,
+        contentIsLiveNoSeek: Bool? = nil,
+        ignorePauseSmallEvents: Bool? = nil,
+        forceInit: Bool? = nil,
+        waitForMetadata: Bool? = nil,
+        waitForMetadataTimeout: Int64? = nil,
+        pendingMetadata: [String]? = nil,
+        overridesJson: String? = nil
+    ) {
+        // Mirror the Android VideoOptions(metadata) constructor: local option keys
+        // are extracted into typed controls before normalization filters them out
+        // of the wire metadata.
+        self.metadata = Self.normalize(metadata)
+        self.joinTimeCalculationMode = joinTimeCalculationMode
+            ?? metadata["joinTimeCalculationMode"].flatMap { JoinTimeCalculationMode(rawValue: $0.uppercased()) }
+        self.adJoinFromAdBreakStart = adJoinFromAdBreakStart ?? Self.boolOption(metadata["adJoinFromAdBreakStart"])
+        self.adConnectedRequiresAdJoin = adConnectedRequiresAdJoin ?? Self.boolOption(metadata["adConnectedRequiresAdJoin"])
+        self.contentIsLiveNoSeek = contentIsLiveNoSeek ?? Self.boolOption(metadata["contentIsLiveNoSeek"])
+        self.ignorePauseSmallEvents = ignorePauseSmallEvents ?? Self.boolOption(metadata["ignorePauseSmallEvents"])
+        let resolvedForceInit = forceInit ?? Self.boolOption(metadata["forceInit"])
+        let resolvedWaitForMetadata = waitForMetadata ?? Self.boolOption(metadata["waitForMetadata"])
+        let resolvedWaitForMetadataTimeout = waitForMetadataTimeout ?? metadata["waitForMetadataTimeout"].flatMap(Int64.init)
+        let resolvedPendingMetadata = pendingMetadata ?? metadata["pendingMetadata"].map {
+            $0.split(separator: ",")
+                .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+        }
+        self.forceInit = resolvedForceInit
+        self.waitForMetadata = resolvedWaitForMetadata
+        self.waitForMetadataTimeout = resolvedWaitForMetadataTimeout
+        self.pendingMetadata = resolvedPendingMetadata
+        self.overridesJson = overridesJson ?? OverrideBundleTransport(metadata: self.metadata)
+            .withControl("forceInit", resolvedForceInit)
+            .withControl("waitForMetadata", resolvedWaitForMetadata)
+            .withControl("waitForMetadataTimeoutMs", resolvedWaitForMetadataTimeout)
+            .withControl("pendingMetadata", resolvedPendingMetadata)
+            .toJson()
+    }
+
+    private static func boolOption(_ value: String?) -> Bool? {
+        switch value?.lowercased() {
+        case "true": return true
+        case "false": return false
+        default: return nil
+        }
+    }
+
+    /// Mirrors the Android `withAdapterWaitForMetadataDefault`: applies the
+    /// adapter-level `waitForMetadata` default without overriding an explicit
+    /// integrator choice. Returns `self` unchanged when `waitForMetadata` was
+    /// set explicitly (true or false) or when the transport JSON already
+    /// carries the control key.
+    func withAdapterWaitForMetadataDefault() -> VideoOptions {
+        if waitForMetadata != nil { return self }
+        guard let patchedJson = Self.patchControlWaitForMetadata(overridesJson) else { return self }
+        var patched = self
+        patched.waitForMetadata = true
+        patched.overridesJson = patchedJson
+        return patched
+    }
+
+    /// Adds `control.waitForMetadata = true` to an existing override transport
+    /// JSON document. Returns `nil` when the JSON already carries the control
+    /// key or cannot be parsed, so callers keep the original options.
+    private static func patchControlWaitForMetadata(_ json: String) -> String? {
+        guard let data = json.data(using: .utf8),
+              let root = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
+            return nil
+        }
+        let existingControl = root["control"] as? [String: Any]
+        if existingControl?["waitForMetadata"] != nil { return nil }
+        var control = existingControl ?? [:]
+        control["waitForMetadata"] = true
+        var patched = root
+        patched["control"] = control
+        guard JSONSerialization.isValidJSONObject(patched),
+              let patchedData = try? JSONSerialization.data(withJSONObject: patched, options: [.sortedKeys]),
+              let patchedJson = String(data: patchedData, encoding: .utf8),
+              !patchedJson.isEmpty else {
+            return nil
+        }
+        return patchedJson
+    }
+
+    public static func builder() -> Builder {
+        Builder()
+    }
+
+    public final class Builder {
+        private var metadata: [String: String] = [:]
+        private var controls: [String: Any] = [:]
+        private var joinTimeCalculationMode: JoinTimeCalculationMode?
+        private var adJoinFromAdBreakStart: Bool?
+        private var adConnectedRequiresAdJoin: Bool?
+        private var contentIsLiveNoSeek: Bool?
+        private var ignorePauseSmallEvents: Bool?
+        private var forceInit: Bool?
+        private var waitForMetadata: Bool?
+        private var waitForMetadataTimeout: Int64?
+        private var pendingMetadata: [String]?
+
+        public init() {}
+
+        @discardableResult public func metadata(_ value: [String: String]?) -> Builder {
+            value.map(Self.normalize)?.forEach { metadata[$0.key] = $0.value }
+            return self
+        }
+
+        @discardableResult public func contentTitle(_ value: String?) -> Builder { api("title", value) }
+        @discardableResult public func contentId(_ value: String?) -> Builder { api("contentId", value) }
+        @discardableResult public func contentResource(_ value: String?) -> Builder { api("resource", value) }
+        @discardableResult public func contentDuration(_ value: Double?) -> Builder { api("mediaDuration", value) }
+        @discardableResult public func contentType(_ value: String?) -> Builder { api("contentType", value) }
+        @discardableResult public func live(_ value: Bool?) -> Builder { api("live", value) }
+        @discardableResult public func contentBitrate(_ value: Int64?) -> Builder { api("bitrate", value) }
+        @discardableResult public func contentRendition(_ value: String?) -> Builder { api("rendition", value) }
+        @discardableResult public func contentCustomDimensions(_ value: [String: Any]?) -> Builder { api("dimensions", value) }
+        @discardableResult public func contentCustomDimension1(_ value: String?) -> Builder { api("param1", value) }
+        @discardableResult public func adTitle(_ value: String?) -> Builder { api("adTitle", value) }
+        @discardableResult public func adResource(_ value: String?) -> Builder { api("adResource", value) }
+        @discardableResult public func adCampaign(_ value: String?) -> Builder { api("adCampaign", value) }
+        @discardableResult public func adCreativeId(_ value: String?) -> Builder { api("adCreativeId", value) }
+        @discardableResult public func adProvider(_ value: String?) -> Builder { api("adProvider", value) }
+        @discardableResult public func transportFormat(_ value: String?) -> Builder { api("transportFormat", value) }
+        @discardableResult public func urlToParse(_ value: String?) -> Builder { api("parsedResource", value) }
+
+        @discardableResult public func joinTimeCalculationMode(_ mode: JoinTimeCalculationMode?) -> Builder {
+            joinTimeCalculationMode = mode
+            return self
+        }
+
+        @discardableResult public func adJoinFromAdBreakStart(_ enabled: Bool?) -> Builder {
+            adJoinFromAdBreakStart = enabled
+            return self
+        }
+
+        @discardableResult public func adConnectedRequiresAdJoin(_ enabled: Bool?) -> Builder {
+            adConnectedRequiresAdJoin = enabled
+            return self
+        }
+
+        @discardableResult public func contentIsLiveNoSeek(_ enabled: Bool?) -> Builder {
+            contentIsLiveNoSeek = enabled
+            return self
+        }
+
+        @discardableResult public func ignorePauseSmallEvents(_ enabled: Bool?) -> Builder {
+            ignorePauseSmallEvents = enabled
+            return self
+        }
+
+        @discardableResult public func isForceInit(_ enabled: Bool?) -> Builder {
+            forceInit = enabled
+            controls["forceInit"] = enabled
+            return self
+        }
+
+        @discardableResult public func waitForMetadata(_ enabled: Bool?) -> Builder {
+            waitForMetadata = enabled
+            controls["waitForMetadata"] = enabled
+            return self
+        }
+
+        @discardableResult public func waitForMetadataTimeout(_ timeoutMs: Int64?) -> Builder {
+            waitForMetadataTimeout = timeoutMs
+            controls["waitForMetadataTimeoutMs"] = timeoutMs
+            return self
+        }
+
+        @discardableResult public func pendingMetadata(_ keys: [String]?) -> Builder {
+            pendingMetadata = keys
+            controls["pendingMetadata"] = keys
+            return self
+        }
+
+        public func build() -> VideoOptions {
+            var transport = OverrideBundleTransport(metadata: metadata)
+            controls.forEach { transport = transport.withControl($0.key, $0.value) }
+            return VideoOptions(
+                metadata: metadata,
+                joinTimeCalculationMode: joinTimeCalculationMode,
+                adJoinFromAdBreakStart: adJoinFromAdBreakStart,
+                adConnectedRequiresAdJoin: adConnectedRequiresAdJoin,
+                contentIsLiveNoSeek: contentIsLiveNoSeek,
+                ignorePauseSmallEvents: ignorePauseSmallEvents,
+                forceInit: forceInit,
+                waitForMetadata: waitForMetadata,
+                waitForMetadataTimeout: waitForMetadataTimeout,
+                pendingMetadata: pendingMetadata,
+                overridesJson: transport.toJson()
+            )
+        }
+
+        @discardableResult private func api(_ key: String, _ value: Any?) -> Builder {
+            guard let value, !Self.nonGoKeys.contains(key) else { return self }
+            metadata[key] = Self.encode(value)
+            return self
+        }
+
+        private static func normalize(_ value: [String: String]) -> [String: String] {
+            VideoOptions.normalize(value)
+        }
+
+        private static func encode(_ value: Any) -> String {
+            if let value = value as? String { return value }
+            if let value = value as? Bool { return String(value) }
+            if let value = value as? NSNumber { return value.stringValue }
+            if JSONSerialization.isValidJSONObject(value),
+               let data = try? JSONSerialization.data(withJSONObject: value),
+               let json = String(data: data, encoding: .utf8) {
+                return json
+            }
+            return String(describing: value)
+        }
+
+        private static let nonGoKeys: Set<String> = [
+            "sendTotalBytes",
+            "pluginLogs",
+            "triggeredEvents",
+            "experiments",
+            "preloadDuration",
+            "profile",
+            "bucket",
+        ]
+    }
+
+    private static func normalize(_ value: [String: String]) -> [String: String] {
+        var output: [String: String] = [:]
+        for (key, value) in value {
+            guard let normalized = normalizedKey(key) else { continue }
+            output[normalized] = normalizedTimeValue(key: key, value: value)
+        }
+        return output
+    }
+
+    /// Mirrors the Android `normalizedApiKey` rules (VideoOptions.kt): local-only
+    /// and internal adapter keys are filtered, legacy snake_case and dotted aliases
+    /// map to camelCase wire keys, custom-dimension prefixes map to param/extraparam
+    /// keys, and unknown keys containing '_' or '.' never leak onto the wire.
+    private static func normalizedKey(_ rawKey: String) -> String? {
+        let key = rawKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        if localOptionKeys.contains(key) || internalOptionKeys.contains(key) || nonGoApiKeys.contains(key) {
+            return nil
+        }
+        switch key {
+        case "player_name": return "player"
+        case "player_version": return "playerVersion"
+        case "resource_url", "content.resource", "contentResource": return "resource"
+        case "content_type", "content.type", "contentType": return "contentType"
+        case "playhead_ms": return "playhead"
+        case "duration_ms": return "mediaDuration"
+        case "bitrate_kbps": return "bitrate"
+        case "dropped_frames": return "droppedFrames"
+        case "error_code": return "errorCode"
+        case "error_message": return "errorMsg"
+        case "creative_id": return "adCreativeId"
+        case "ad_duration_ms": return "adDuration"
+        case "ad_playhead_ms": return "adPlayhead"
+        case "insertion_type": return "adInsertionType"
+        case "content.id", "content_id": return "contentId"
+        case "content.title", "contentTitle": return "title"
+        case "content.isLive", "contentIsLive": return "live"
+        case "content.duration", "contentDuration": return "mediaDuration"
+        case "content.bitrate", "contentBitrate": return "bitrate"
+        case "content.rendition", "contentRendition": return "rendition"
+        case "content.language", "contentLanguage": return "contentLanguage"
+        case "content.metadata", "contentMetadata": return "properties"
+        case "content.metrics", "contentMetrics": return "metrics"
+        case "ad.resource", "adResource": return "adResource"
+        case "ad.title", "adTitle": return "adTitle"
+        case "ad.creativeId", "adCreativeId": return "adCreativeId"
+        case "ad.adapterVersion", "adAdapterVersion": return "adAdapterVersion"
+        case "ad.provider", "adProvider": return "adProvider"
+        case "ad.metadata", "adMetadata": return "adProperties"
+        default:
+            if key.hasPrefix("content.customDimension.") {
+                return Int(key.dropFirst("content.customDimension.".count)).map { "param\($0)" }
+            }
+            if key.hasPrefix("ad.customDimension.") {
+                return Int(key.dropFirst("ad.customDimension.".count)).map { "extraparam\($0)" }
+            }
+            return key.contains("_") || key.contains(".") ? nil : key
+        }
+    }
+
+    /// Option keys consumed by the binding itself (matching Android's
+    /// `localOptionKeys`); they configure behavior and never reach the wire.
+    private static let localOptionKeys: Set<String> = [
+        "joinTimeCalculationMode",
+        "adJoinFromAdBreakStart",
+        "adConnectedRequiresAdJoin",
+        "contentIsLiveNoSeek",
+        "ignorePauseSmallEvents",
+        "waitForMetadata",
+        "waitForMetadataTimeout",
+        "adPostRollTimeout",
+        "delegateToAdAdapter",
+        "autoRestartOnMaxTimeExpiration",
+        "parseManifest",
+        "parseCdnNode",
+        "parseCdnNodeDisableFallback",
+        "parseCdnNodeAllowedGetMethodOnRetry",
+        "parseManifestAuth",
+        "parseCdnNodeList",
+        "parseCdnNameHeaderList",
+        "parseCdnNodeHeaderList",
+        "parseCdnNodeRequestDelayed",
+        "errorsToIgnore",
+        "legacyErrorNames",
+        "fatalErrors",
+        "nonFatalErrors",
+        "forceInit",
+        "pendingMetadata",
+    ]
+
+    /// Adapter-internal descriptor keys (matching Android's `internalOptionKeys`);
+    /// they describe the integration, not the content, and never reach the wire.
+    private static let internalOptionKeys: Set<String> = [
+        "adapter_id",
+        "adapterId",
+        "video_adapter_id",
+        "videoAdapterId",
+        "ad_adapter_id",
+        "adAdapterId",
+        "player_family",
+        "playerFamily",
+        "category",
+        "version",
+        "adapterVersion",
+    ]
+
+    /// Non-Go API keys dropped on every platform (matching Android's `nonGoApiKeys`).
+    private static let nonGoApiKeys: Set<String> = [
+        "profile",
+        "bucket",
+        "experiments",
+        "preloadDuration",
+        "triggeredEvents",
+        "sendTotalBytes",
+        "pluginLogs",
+    ]
+
+    private static func normalizedTimeValue(key: String, value: String) -> String {
+        switch key {
+        case "playhead_ms", "duration_ms", "ad_duration_ms", "ad_playhead_ms":
+            guard let millis = Double(value) else { return value }
+            return String(millis / 1000.0)
+        default:
+            return value
+        }
+    }
+}
+
+struct OverrideBundleTransport: Equatable {
+    private var scalars: [String: String]
+    private var controls: [String: Any]
+
+    init(metadata: [String: String]) {
+        self.scalars = metadata
+        self.controls = [:]
+    }
+
+    func withControl(_ key: String, _ value: Any?) -> OverrideBundleTransport {
+        guard let value else { return self }
+        var copy = self
+        copy.controls[key] = value
+        return copy
+    }
+
+    func toJson() -> String {
+        var object: [String: Any] = [:]
+        if !scalars.isEmpty {
+            object["scalars"] = scalars
+        }
+        if !controls.isEmpty {
+            object["control"] = controls
+        }
+        guard JSONSerialization.isValidJSONObject(object),
+              let data = try? JSONSerialization.data(withJSONObject: object, options: [.sortedKeys]),
+              let json = String(data: data, encoding: .utf8) else {
+            return "{}"
+        }
+        return json
+    }
+
+    static func == (lhs: OverrideBundleTransport, rhs: OverrideBundleTransport) -> Bool {
+        lhs.toJson() == rhs.toJson()
+    }
+}

package/ios/ForgeApple/Sources/NPAWForgeNetworkCapture/ForgeNetworkCapture.swift

@@ -0,0 +1,116 @@
+/**
+ * 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 network capture installer and payload adapter for Apple URLSession swizzling.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+#if canImport(NPAWForgeNetworkCaptureObjC)
+import NPAWForgeNetworkCaptureObjC
+#endif
+
+public struct NetworkCaptureConfiguration: Equatable {
+    public var enabled: Bool
+    public var privacy: NetworkPrivacyConfiguration
+    public var blockedHosts: Set<String>
+
+    public init(
+        enabled: Bool = false,
+        privacy: NetworkPrivacyConfiguration = NetworkPrivacyConfiguration(),
+        blockedHosts: Set<String> = ["lma.npaw.com"]
+    ) {
+        self.enabled = enabled
+        self.privacy = privacy
+        self.blockedHosts = blockedHosts.map { $0.lowercased() }.asSet
+    }
+}
+
+public enum ForgeNetworkCapture {
+    private static let lock = NSLock()
+    private static var activeForge: NPAWForge?
+    private static var activeConfiguration = NetworkCaptureConfiguration()
+
+    @discardableResult
+    public static func install(
+        forge: NPAWForge,
+        configuration: NetworkCaptureConfiguration = NetworkCaptureConfiguration(enabled: true)
+    ) -> ForgeOutcome {
+        lock.lock()
+        activeForge = forge
+        activeConfiguration = configuration
+        lock.unlock()
+        guard configuration.enabled else { return .ignoredInvalidState }
+        let installed = NPAWForgeNetworkSwizzler.install(
+            callback: { payload in
+                handle(payload: payload)
+            },
+            blockedHosts: configuration.blockedHosts
+        )
+        return installed ? .accepted : .failedWithDiagnostic("network_swizzler_install_failed")
+    }
+
+    /// Stops automatic capture and clears the active forge/configuration so
+    /// swizzled traffic and manual tracking no-op until the next install. The
+    /// underlying method swizzles stay installed for the process lifetime;
+    /// `install(forge:configuration:)` resumes capture by re-arming the callback.
+    @discardableResult
+    public static func uninstall() -> ForgeOutcome {
+        lock.lock()
+        activeForge = nil
+        activeConfiguration = NetworkCaptureConfiguration()
+        lock.unlock()
+        NPAWForgeNetworkSwizzler.uninstall()
+        return .accepted
+    }
+
+    public static func track(_ record: NetworkRequestRecord) -> ForgeOutcome {
+        lock.lock()
+        let forge = activeForge
+        let configuration = activeConfiguration
+        lock.unlock()
+        guard configuration.enabled else { return .ignoredInvalidState }
+        return forge?.trackNetworkRequest(record.sanitized(configuration: configuration.privacy)) ?? .ignoredInvalidState
+    }
+
+    private static func handle(payload: [String: String]) {
+        lock.lock()
+        let forge = activeForge
+        let configuration = activeConfiguration
+        lock.unlock()
+        guard configuration.enabled, let forge else { return }
+        var record = NetworkRequestRecord(
+            targetUrl: payload["targetUrl"] ?? "unknown",
+            method: payload["method"] ?? "GET",
+            responseStatusCode: Int(payload["responseStatusCode"] ?? "0") ?? 0,
+            durationMs: Int64(payload["durationMs"] ?? "0") ?? 0,
+            outcome: NetworkRequestOutcome(rawValue: payload["outcome"] ?? "unknown") ?? .unknown,
+            eventId: payload["eventId"] ?? UUID().uuidString,
+            source: NetworkRequestSource(rawValue: payload["source"] ?? "automatic_urlsession") ?? .automaticURLSession,
+            timestampMs: Int64(payload["timestampMs"] ?? "0") ?? 0
+        )
+        record.errorMessage = payload["errorMessage"]
+        record.requestBytes = payload["requestBytes"].flatMap(Int64.init)
+        record.responseBytes = payload["responseBytes"].flatMap(Int64.init)
+        record.responseHeaders = payload
+            .filter { $0.key.hasPrefix("responseHeader.") }
+            .reduce(into: [String: String]()) { output, element in
+                output[String(element.key.dropFirst("responseHeader.".count))] = element.value
+            }
+        _ = forge.trackNetworkRequest(record.sanitized(configuration: configuration.privacy))
+    }
+}
+
+private extension Array where Element == String {
+    var asSet: Set<String> { Set(self) }
+}