@npaw/forge-react-native 9.6.1

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

@@ -0,0 +1,453 @@
+/**
+ * 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: Public Swift-first Forge Apple facade.
+ */
+
+import Foundation
+
+// The generated kernel bridge is only present when the Rust runtime is linked;
+// guarded exactly as in NativeUniFFIRuntime.swift.
+#if FORGE_HAS_UNIFFI
+#if canImport(ForgeKernelUniFFI)
+import ForgeKernelUniFFI
+#endif
+#endif
+
+@objc(NPAWForge)
+public final class NPAWForge: NSObject {
+    public static let defaultVideoAdapterIdentifier = "default"
+    /// Marker meaning "this build does not know its own version".
+    ///
+    /// The authoritative Forge version is resolved by
+    /// `scripts/version/resolve-version.sh` and compiled into the Rust
+    /// runtime, which substitutes it whenever the Swift layer sends this
+    /// marker — so the wire never carries the marker when a Forge runtime is
+    /// linked. Only builds with no runtime linked see it.
+    ///
+    /// Deliberately NOT release-shaped: it used to be `9.0.0-local`, which
+    /// reached the wire as a plausible-looking version and made internal
+    /// builds indistinguishable from a real 9.0.0 release.
+    ///
+    /// `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.6.1"
+    public static let defaultAppName = "apple"
+    public static let defaultBuildVariant = "release"
+    public static let defaultLmaEndpoint = "https://lma.npaw.com"
+
+    /// The Forge plugin version this build actually reports, matching Android's
+    /// `NPAWForge.pluginVersion`.
+    ///
+    /// Precedence deliberately mirrors the runtime's own
+    /// `effective_plugin_version`, so this property and the wire always agree:
+    ///
+    /// 1. A patched `defaultPluginVersion` wins. That only happens in a staged
+    ///    shipped package, where `publish-local-shipped.sh` has written the
+    ///    release version in, and the release version must stay authoritative.
+    /// 2. Otherwise the version compiled into the linked Rust runtime.
+    /// 3. Otherwise the marker, for builds with no runtime linked.
+    public static var pluginVersion: String {
+        if defaultPluginVersion != unresolvedPluginVersionMarker {
+            return defaultPluginVersion
+        }
+        return runtimePluginVersion ?? defaultPluginVersion
+    }
+
+    /// Kept separate from `defaultPluginVersion` so the release patch can
+    /// rewrite that literal without also rewriting the comparison value.
+    private static let unresolvedPluginVersionMarker = "0.0.0-unresolved"
+
+    /// The version embedded in the linked Rust runtime, when one is linked.
+    ///
+    /// `forgePluginVersion()` is the UniFFI-generated Swift name for the UDL
+    /// declaration `string forge_plugin_version();` — the generator camelCases
+    /// it.
+    private static var runtimePluginVersion: String? {
+        #if FORGE_HAS_UNIFFI
+        #if canImport(ForgeKernelUniFFI)
+        let version = forgePluginVersion()
+        return version.isEmpty ? nil : version
+        #else
+        return nil
+        #endif
+        #else
+        return nil
+        #endif
+    }
+
+    public let kernel: ForgeApple
+    private var destroyed = false
+    private let lock = NSRecursiveLock()
+    private var videoAdapters: [VideoAdapter] = []
+
+    public init(kernel: ForgeApple) {
+        self.kernel = kernel
+    }
+
+    public func videoBuilder() -> VideoBuilder {
+        VideoBuilder(forge: self)
+    }
+
+    public func subscribeEvents(_ observer: @escaping (ForgeRecordedEvent, ForgeOutcome) -> Void) -> ForgeEventSubscription {
+        kernel.subscribeEvents(observer)
+    }
+
+    /// Observes kernel-derived capture plans (bitmask + focus/limit knobs +
+    /// behavior hints). The latest plan is replayed to listeners added after
+    /// the first emission. The kernel intake gates remain the semantic
+    /// authority; the plan only tells observers what is worth installing.
+    public func addCapturePlanListener(_ listener: @escaping (ForgeCapturePlan) -> Void) -> ForgeEventSubscription {
+        kernel.addCapturePlanListener(listener)
+    }
+
+    /// Latest kernel-emitted capture plan, or `nil` before the first
+    /// emission (pre-first-plan behavior is local options only).
+    public func capturePlan() -> ForgeCapturePlan? {
+        kernel.capturePlan()
+    }
+
+    public func addOnSendRequestListener(_ listener: @escaping (String, inout [String: String]) -> Void) -> ForgeEventSubscription {
+        kernel.addOnSendRequestListener(listener)
+    }
+
+    public func snapshotEvents() -> [ForgeRecordedEvent] {
+        kernel.snapshotEvents()
+    }
+
+    @objc public func setLogLevel(_ value: Any?) -> ForgeOutcome {
+        kernel.setLogLevel(ForgeLogLevel.from(value, default: kernel.effectiveLogLevel()))
+    }
+
+    @objc public func startSession(_ metadata: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.startSession(metadata: metadata.toStringMap())
+    }
+
+    @objc public func endSession(_ metadata: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.endSession(metadata: metadata.toStringMap())
+    }
+
+    public func trackSessionNavigation(_ metadata: [String: Any]) -> ForgeOutcome {
+        kernel.trackSessionNavigation(metadata.toStringMap())
+    }
+
+    public func trackSessionEvent(name: String, metadata: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.trackSessionEvent(name: name, metadata: metadata.toStringMap())
+    }
+
+    public func trackSessionEventStop(name: String, metadata: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.trackSessionEventStop(name: name, metadata: metadata.toStringMap())
+    }
+
+    public func trackSessionError(errorCode: String, errorMessage: String, metadata: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.trackSessionError(errorCode: errorCode, errorMessage: errorMessage, metadata: metadata.toStringMap())
+    }
+
+    /// Emits a raw event: the name gains the `raw_` prefix when missing and
+    /// travels on the session-event path, matching the web binding shape.
+    public func trackRawEvent(name: String, params: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.trackRawEvent(name: name, params: params.toStringMap())
+    }
+
+    /// Emits a `raw_search` event with the query and optional result count.
+    public func trackSearch(query: String, resultCount: Int? = nil) -> ForgeOutcome {
+        kernel.trackSearch(query: query, resultCount: resultCount)
+    }
+
+    /// Emits a `raw_search_result_click` event for a result chosen from the
+    /// results produced by the query last reported via `trackSearch`.
+    public func trackSearchResultClick(query: String, options: ForgeSearchResultClickOptions = ForgeSearchResultClickOptions()) -> ForgeOutcome {
+        kernel.trackSearchResultClick(query: query, options: options)
+    }
+
+    /// Emits a typed business raw event whose attributes travel under the
+    /// `target.attr.*` convention.
+    public func trackBusinessEvent(name: String, attributes: [String: Any] = [:]) -> ForgeOutcome {
+        kernel.trackBusinessEvent(name: name, attributes: attributes.toStringMap())
+    }
+
+    /// Emits a `raw_attribution` event for apps that resolve their own
+    /// campaign parameters.
+    public func trackAttribution(options: ForgeAttributionOptions = ForgeAttributionOptions()) -> ForgeOutcome {
+        kernel.trackAttribution(options: options)
+    }
+
+    /// Reports a successful login; the kernel emits `login
+    /// {authStatus:"success"}` and atomically restarts the app session when
+    /// the effective identity changed.
+    public func loginSuccess(userId: String, options: [String: String] = [:]) -> ForgeOutcome {
+        kernel.loginSuccess(userId: userId, options: options)
+    }
+
+    /// Reports a failed login attempt: `login {authStatus:"failure"}`.
+    public func loginFailed(options: [String: String] = [:]) -> ForgeOutcome {
+        kernel.loginFailed(options: options)
+    }
+
+    /// Reports a logout; the kernel clears the identity to Anonymous and
+    /// atomically restarts the app session.
+    public func logout(options: [String: String] = [:]) -> ForgeOutcome {
+        kernel.logout(options: options)
+    }
+
+    /// Reports a profile creation: `profile_created {profileId, profileType?}`.
+    public func profileCreated(profileId: String, options: [String: String] = [:]) -> ForgeOutcome {
+        kernel.profileCreated(profileId: profileId, options: options)
+    }
+
+    /// Reports a profile selection; the kernel stamps `profileId` on the
+    /// session identity and restarts the app session when it changed.
+    public func profileSelected(profileId: String, options: [String: String] = [:]) -> ForgeOutcome {
+        kernel.profileSelected(profileId: profileId, options: options)
+    }
+
+    /// Reports a profile deletion: `profile_deleted {profileId}`.
+    public func profileDeleted(profileId: String) -> ForgeOutcome {
+        kernel.profileDeleted(profileId: profileId)
+    }
+
+    public func trackNetworkRequest(_ record: NetworkRequestRecord) -> ForgeOutcome {
+        guard !destroyed else { return .ignoredInvalidState }
+        return kernel.trackNetworkRequest(record)
+    }
+
+    public func getVideoAdapter(identifier: String? = nil) -> VideoAdapter? {
+        let id = identifier?.nilIfBlank ?? Self.defaultVideoAdapterIdentifier
+        lock.lock()
+        defer { lock.unlock() }
+        return videoAdapters.first { $0.identifier == id && !$0.isDestroyed }
+    }
+
+    public func destroy() -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredDuplicate }
+        destroyed = true
+        let adapters = videoAdapters
+        videoAdapters.removeAll()
+        adapters.forEach { _ = $0.destroy() }
+        return kernel.destroy()
+    }
+
+    func buildVideoAdapter(
+        identifier: String,
+        options: VideoOptions,
+        playerAdapter: PlayerAdapter?,
+        adAdapter: AdAdapter?
+    ) -> VideoAdapter {
+        lock.lock()
+        defer { lock.unlock() }
+        destroyAdapters(identifier: identifier)
+        destroyAdapters(using: playerAdapter, owner: nil)
+        destroyAdapters(using: adAdapter, owner: nil)
+        let adapter = VideoAdapter(forge: self, identifier: identifier, options: options)
+        videoAdapters.append(adapter)
+        _ = adapter.replacePlayerAdapter(playerAdapter, checkDuplicates: false)
+        _ = adapter.replaceAdAdapter(adAdapter, checkDuplicates: false)
+        return adapter
+    }
+
+    func onPlayerAdapterRegistered(owner: VideoAdapter, playerAdapter: PlayerAdapter?) {
+        lock.lock()
+        defer { lock.unlock() }
+        destroyAdapters(using: playerAdapter, owner: owner)
+    }
+
+    func onAdAdapterRegistered(owner: VideoAdapter, adAdapter: AdAdapter?) {
+        lock.lock()
+        defer { lock.unlock() }
+        destroyAdapters(using: adAdapter, owner: owner)
+    }
+
+    func onVideoAdapterDestroyed(_ adapter: VideoAdapter) {
+        lock.lock()
+        defer { lock.unlock() }
+        videoAdapters.removeAll { $0 === adapter }
+    }
+
+    private func destroyAdapters(identifier: String) {
+        videoAdapters.filter { $0.identifier == identifier && !$0.isDestroyed }.forEach { _ = $0.destroy() }
+    }
+
+    private func destroyAdapters(using candidate: AnyObject?, owner: VideoAdapter?) {
+        guard let candidate else { return }
+        videoAdapters
+            .filter { $0 !== owner && !$0.isDestroyed && $0.usesAdapterOrPlayer(candidate) }
+            .forEach { _ = $0.destroy() }
+    }
+
+    public final class Builder {
+        private var accountCode: String
+        private var appName = Bundle.main.displayName ?? NPAWForge.defaultAppName
+        private var appReleaseVersion = Bundle.main.releaseVersion
+        private var buildVariant = NPAWForge.defaultBuildVariant
+        private var lmaEndpoint = NPAWForge.defaultLmaEndpoint
+        private var analyticsUserAgent: String?
+        private var allowLocalHttp = false
+        private var startSessionOnInitialize = false
+        private var processEventsBeforeSessionStart = false
+        private var preSessionEventQueueLimitEvents = 100
+        private var preSessionEventQueueMaxAgeMs: Int64 = 30_000
+        private var logLevel: ForgeLogLevel = .warning
+        private var services: ForgeAppleServices?
+
+        public init(accountCode: String) {
+            self.accountCode = accountCode
+        }
+
+        @available(*, deprecated, message: "pluginVersion is owned by the Forge SDK build and this setter is ignored.")
+        @discardableResult public func setPluginVersion(_ value: String?) -> Builder {
+            _ = value
+            return self
+        }
+
+        @discardableResult public func setAppName(_ value: String?) -> Builder {
+            appName = value?.nilIfBlank ?? appName
+            return self
+        }
+
+        @discardableResult public func setApplicationName(_ value: String?) -> Builder { setAppName(value) }
+
+        @discardableResult public func setAppReleaseVersion(_ value: String?) -> Builder {
+            appReleaseVersion = value?.nilIfBlank
+            return self
+        }
+
+        @discardableResult public func setAppVersion(_ value: String?) -> Builder { setAppReleaseVersion(value) }
+        @discardableResult public func setApplicationVersion(_ value: String?) -> Builder { setAppReleaseVersion(value) }
+
+        @discardableResult public func setLmaEndpoint(_ value: String?) -> Builder {
+            lmaEndpoint = value?.nilIfBlank ?? lmaEndpoint
+            return self
+        }
+
+        @discardableResult public func setAnalyticsHost(_ value: String?) -> Builder { setLmaEndpoint(value) }
+        @discardableResult public func setHost(_ value: String?) -> Builder { setLmaEndpoint(value) }
+
+        @discardableResult public func setAnalyticsUserAgent(_ value: String?) -> Builder {
+            analyticsUserAgent = value?.nilIfBlank
+            return self
+        }
+
+        @discardableResult public func setLocalPlaintextTransportForTesting(_ enabled: Bool) -> Builder {
+            allowLocalHttp = enabled
+            return self
+        }
+
+        @discardableResult public func setStartSessionOnInitialize(_ enabled: Bool) -> Builder {
+            startSessionOnInitialize = enabled
+            return self
+        }
+
+        @discardableResult public func setProcessEventsBeforeSessionStart(_ enabled: Bool) -> Builder {
+            processEventsBeforeSessionStart = enabled
+            return self
+        }
+
+        @discardableResult public func setPreSessionEventQueueLimitEvents(_ limit: Int) -> Builder {
+            preSessionEventQueueLimitEvents = max(0, limit)
+            return self
+        }
+
+        @discardableResult public func setPreSessionEventQueueMaxAgeMs(_ maxAgeMs: Int64) -> Builder {
+            preSessionEventQueueMaxAgeMs = max(0, maxAgeMs)
+            return self
+        }
+
+        @discardableResult public func setLogLevel(_ value: Any?) -> Builder {
+            logLevel = ForgeLogLevel.from(value)
+            return self
+        }
+
+        @discardableResult public func setBuildVariant(_ value: String?) -> Builder {
+            buildVariant = value?.nilIfBlank ?? buildVariant
+            return self
+        }
+
+        @discardableResult public func setServices(_ value: ForgeAppleServices?) -> Builder {
+            services = value
+            return self
+        }
+
+        public func build() -> NPAWForge {
+            let config = ForgeAppleConfig(
+                accountCode: accountCode,
+                pluginVersion: NPAWForge.defaultPluginVersion,
+                appName: appName,
+                buildVariant: buildVariant,
+                appReleaseVersion: appReleaseVersion,
+                lmaEndpoint: lmaEndpoint,
+                analyticsUserAgent: analyticsUserAgent,
+                allowLocalHttp: allowLocalHttp,
+                startSessionOnInitialize: startSessionOnInitialize,
+                processEventsBeforeSessionStart: processEventsBeforeSessionStart,
+                preSessionEventQueueLimitEvents: preSessionEventQueueLimitEvents,
+                preSessionEventQueueMaxAgeMs: preSessionEventQueueMaxAgeMs,
+                logLevel: logLevel
+            )
+            let resolvedServices = services ?? ForgeAppleServices(storage: UserDefaultsStorage())
+            let forge = NPAWForge(kernel: ForgeApple(config: config, services: resolvedServices))
+            ForgeAutomaticCaptureRegistry.installIfAvailable(forge)
+            return forge
+        }
+    }
+}
+
+public enum ForgeAutomaticCaptureRegistry {
+    private static let lock = NSLock()
+    private static var installers: [(NPAWForge) -> Void] = []
+
+    public static func register(_ installer: @escaping (NPAWForge) -> Void) {
+        lock.lock()
+        defer { lock.unlock() }
+        installers.append(installer)
+    }
+
+    static func installIfAvailable(_ forge: NPAWForge) {
+        lock.lock()
+        let snapshot = installers
+        lock.unlock()
+        snapshot.forEach { $0(forge) }
+    }
+}
+
+private extension Dictionary where Key == String, Value == Any {
+    func toStringMap() -> [String: String] {
+        reduce(into: [String: String]()) { output, element in
+            let key = element.key.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !key.isEmpty else { return }
+            let value = String(describing: element.value)
+            guard !value.isEmpty else { return }
+            output[key] = value
+        }
+    }
+}
+
+private extension String {
+    var nilIfBlank: String? {
+        let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}
+
+private extension Bundle {
+    var displayName: String? {
+        object(forInfoDictionaryKey: "CFBundleDisplayName") as? String
+            ?? object(forInfoDictionaryKey: "CFBundleName") as? String
+            ?? bundleIdentifier
+    }
+
+    var releaseVersion: String? {
+        object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
+            ?? object(forInfoDictionaryKey: "CFBundleVersion") as? String
+    }
+}