@npaw/forge-react-native 9.6.1

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

@@ -0,0 +1,596 @@
+/**
+ * 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: Internal Apple facade that owns binding-local runtime wiring and event sanitization.
+ */
+
+import Foundation
+
+public struct ForgeAppleConfig: Equatable {
+    public var accountCode: String
+    public var pluginVersion: String
+    public var appName: String
+    public var buildVariant: String
+    public var appReleaseVersion: String?
+    public var lmaEndpoint: String
+    public var analyticsUserAgent: String?
+    public var allowLocalHttp: Bool
+    public var startSessionOnInitialize: Bool
+    public var processEventsBeforeSessionStart: Bool
+    public var preSessionEventQueueLimitEvents: Int
+    public var preSessionEventQueueMaxAgeMs: Int64
+    public var logLevel: ForgeLogLevel
+
+    public init(
+        accountCode: String,
+        pluginVersion: String,
+        appName: String,
+        buildVariant: String,
+        appReleaseVersion: String? = nil,
+        lmaEndpoint: String = "https://lma.npaw.com",
+        analyticsUserAgent: String? = nil,
+        allowLocalHttp: Bool = false,
+        startSessionOnInitialize: Bool = false,
+        processEventsBeforeSessionStart: Bool = false,
+        preSessionEventQueueLimitEvents: Int = 100,
+        preSessionEventQueueMaxAgeMs: Int64 = 30_000,
+        logLevel: ForgeLogLevel = .warning
+    ) {
+        self.accountCode = accountCode
+        self.pluginVersion = pluginVersion
+        self.appName = appName
+        self.buildVariant = buildVariant
+        self.appReleaseVersion = appReleaseVersion
+        self.lmaEndpoint = lmaEndpoint
+        self.analyticsUserAgent = analyticsUserAgent
+        self.allowLocalHttp = allowLocalHttp
+        self.startSessionOnInitialize = startSessionOnInitialize
+        self.processEventsBeforeSessionStart = processEventsBeforeSessionStart
+        self.preSessionEventQueueLimitEvents = preSessionEventQueueLimitEvents
+        self.preSessionEventQueueMaxAgeMs = preSessionEventQueueMaxAgeMs
+        self.logLevel = logLevel
+    }
+}
+
+public struct ForgeAppleServices {
+    public var runtimeFactory: ForgeRuntimeFactory
+    public var storage: ForgeStorage
+    public var logSink: ForgeLogSink?
+
+    public init(
+        runtimeFactory: ForgeRuntimeFactory = NativeForgeRuntimeFactory(),
+        storage: ForgeStorage = MemoryStorage(),
+        logSink: ForgeLogSink? = OSLogForgeLogSink()
+    ) {
+        self.runtimeFactory = runtimeFactory
+        self.storage = storage
+        self.logSink = logSink
+    }
+}
+
+/// Typed options for `trackSearchResultClick`, mirroring the web binding's
+/// `ForgeSearchResultClickOptions` shape.
+public struct ForgeSearchResultClickOptions: Equatable {
+    /// Identifier of the content the user selected from the results.
+    public var contentId: String?
+    /// One-based position of the selected result within the list.
+    public var position: Int?
+
+    public init(contentId: String? = nil, position: Int? = nil) {
+        self.contentId = contentId
+        self.position = position
+    }
+}
+
+/// Typed campaign parameters for the explicit `trackAttribution` variant,
+/// mirroring the web binding's `ForgeAttributionParams` shape.
+public struct ForgeAttributionOptions: Equatable {
+    public var utmSource: String?
+    public var utmMedium: String?
+    public var utmCampaign: String?
+    public var utmTerm: String?
+    public var utmContent: String?
+    public var utmUrl: String?
+
+    public init(
+        utmSource: String? = nil,
+        utmMedium: String? = nil,
+        utmCampaign: String? = nil,
+        utmTerm: String? = nil,
+        utmContent: String? = nil,
+        utmUrl: String? = nil
+    ) {
+        self.utmSource = utmSource
+        self.utmMedium = utmMedium
+        self.utmCampaign = utmCampaign
+        self.utmTerm = utmTerm
+        self.utmContent = utmContent
+        self.utmUrl = utmUrl
+    }
+}
+
+public final class ForgeApple {
+    /// Upper bound for the Swift-side recorded-event mirror. Matches the Rust-side
+    /// `EVENT_SNAPSHOT_LIMIT` bounded snapshot semantics (oldest entries dropped).
+    static let eventSnapshotLimit = 512
+
+    public let config: ForgeAppleConfig
+    public let services: ForgeAppleServices
+    private let runtime: ForgeRuntime
+    private let logger: ForgeLogger
+    private var destroyed = false
+    private var appSessionActive = false
+    private let lock = NSRecursiveLock()
+    private var recordedEvents: [ForgeRecordedEvent] = []
+    private var eventObservers: [UUID: (ForgeRecordedEvent, ForgeOutcome) -> Void] = [:]
+    private var onSendRequestListeners: [UUID: (String, inout [String: String]) -> Void] = [:]
+    private var capturePlanObservers: [UUID: (ForgeCapturePlan) -> Void] = [:]
+    private var latestCapturePlan: ForgeCapturePlan?
+
+    public init(config: ForgeAppleConfig, services: ForgeAppleServices) {
+        let safeConfig = config.withPluginVersion(NPAWForge.defaultPluginVersion)
+        self.config = safeConfig
+        self.services = services
+        self.logger = ForgeLogger(level: safeConfig.logLevel, sink: services.logSink)
+        self.runtime = services.runtimeFactory.create(config: safeConfig, services: services)
+        _ = runtime.setCapturePlanListener { [weak self] plan in
+            self?.dispatchCapturePlan(plan)
+        }
+        _ = runtime.start()
+        if safeConfig.startSessionOnInitialize {
+            _ = startSession()
+        }
+    }
+
+    public func recordEvent(
+        eventName: String,
+        payload: [String: String] = [:],
+        timestampMs: Int64 = 0,
+        urgent: Bool = false,
+        viewKey: String? = nil
+    ) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        if eventName == "sessionstart" {
+            return startSession(metadata: payload, timestampMs: timestampMs)
+        }
+        if eventName == "sessionstop" {
+            return endSession(metadata: payload, timestampMs: timestampMs)
+        }
+        let event = ForgeRecordedEvent(
+            eventName: eventName,
+            timestampMs: timestampMs,
+            payload: PrivacySanitizer.sanitize(appSessionPayload(eventName: eventName, payload: payload), maxValueLength: maxPayloadValueLength(eventName)),
+            urgent: urgent,
+            viewKey: viewKey
+        )
+        let outcome = runtime.recordEvent(event)
+        recordRuntimeEvent(event, outcome: outcome)
+        return outcome
+    }
+
+    public func startSession(metadata: [String: String] = [:], timestampMs: Int64 = 0) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        guard !appSessionActive else { return .ignoredDuplicate }
+        appSessionActive = true
+        let event = ForgeRecordedEvent(
+            eventName: "sessionstart",
+            timestampMs: timestampMs,
+            payload: PrivacySanitizer.sanitize(appSessionPayload(eventName: "sessionstart", payload: metadata)),
+            urgent: true
+        )
+        let outcome = runtime.recordEvent(event)
+        if outcome.code == .failedWithDiagnostic || outcome.code == .unsupportedCapability {
+            appSessionActive = false
+        }
+        recordRuntimeEvent(event, outcome: outcome)
+        return outcome
+    }
+
+    public func endSession(metadata: [String: String] = [:], timestampMs: Int64 = 0) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        guard appSessionActive else { return .ignoredInvalidState }
+        appSessionActive = false
+        let event = ForgeRecordedEvent(
+            eventName: "sessionstop",
+            timestampMs: timestampMs,
+            payload: PrivacySanitizer.sanitize(appSessionPayload(eventName: "sessionstop", payload: metadata)),
+            urgent: true
+        )
+        let outcome = runtime.recordEvent(event)
+        recordRuntimeEvent(event, outcome: outcome)
+        return outcome
+    }
+
+    public func trackSessionNavigation(_ metadata: [String: String]) -> ForgeOutcome {
+        recordEvent(eventName: "sessionnav", payload: metadata)
+    }
+
+    public func trackSessionEvent(name: String, metadata: [String: String] = [:]) -> ForgeOutcome {
+        recordEvent(eventName: "sessionevent", payload: metadata.merging(["name": name]) { _, new in new })
+    }
+
+    public func trackSessionEventStop(name: String, metadata: [String: String] = [:]) -> ForgeOutcome {
+        recordEvent(eventName: "sessioneventstop", payload: metadata.merging(["name": name]) { _, new in new })
+    }
+
+    public func trackSessionError(errorCode: String, errorMessage: String, metadata: [String: String] = [:]) -> ForgeOutcome {
+        recordEvent(
+            eventName: "sessionerror",
+            payload: metadata.merging(["errorCode": errorCode, "errorMsg": errorMessage]) { _, new in new },
+            urgent: true
+        )
+    }
+
+    /// Emits a raw event: the name gains the `raw_` prefix when missing and
+    /// travels on the session-event path (`sessionevent` with the normalized
+    /// name), matching the web binding's `trackRawEvent` wire shape.
+    public func trackRawEvent(name: String, params: [String: String] = [:]) -> ForgeOutcome {
+        let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalized = trimmed.hasPrefix("raw_") ? trimmed : "raw_\(trimmed)"
+        return trackSessionEvent(name: normalized, metadata: params)
+    }
+
+    /// Emits a `raw_search` event. The query text is subject to the kernel-side
+    /// remote visible-text privacy policy, which can strip it before any
+    /// payload leaves the device.
+    public func trackSearch(query: String, resultCount: Int? = nil) -> ForgeOutcome {
+        var params = ["searchQuery": query]
+        if let resultCount {
+            params["resultCount"] = String(resultCount)
+        }
+        return trackRawEvent(name: "raw_search", params: params)
+    }
+
+    /// Emits a `raw_search_result_click` event for a result chosen from the
+    /// search results produced by the query last reported via `trackSearch`.
+    public func trackSearchResultClick(query: String, options: ForgeSearchResultClickOptions = ForgeSearchResultClickOptions()) -> ForgeOutcome {
+        var params = ["searchQuery": query]
+        if let contentId = options.contentId {
+            params["contentId"] = contentId
+        }
+        if let position = options.position {
+            params["position"] = String(position)
+        }
+        return trackRawEvent(name: "raw_search_result_click", params: params)
+    }
+
+    /// Emits a typed business raw event: the name gains the `raw_` prefix when
+    /// missing and every attribute travels under the `target.attr.*`
+    /// convention, so the kernel target-attribute allowlist and PPE
+    /// `target.attr.*` facts apply unchanged.
+    public func trackBusinessEvent(name: String, attributes: [String: String] = [:]) -> ForgeOutcome {
+        var params: [String: String] = [:]
+        params.reserveCapacity(attributes.count)
+        for (key, value) in attributes {
+            params["target.attr.\(key)"] = value
+        }
+        return trackRawEvent(name: name, params: params)
+    }
+
+    /// Emits a `raw_attribution` event for apps that resolve their own
+    /// campaign parameters (the explicit variant; automatic UTM capture is a
+    /// separate capture family).
+    public func trackAttribution(options: ForgeAttributionOptions = ForgeAttributionOptions()) -> ForgeOutcome {
+        var params: [String: String] = [:]
+        if let utmSource = options.utmSource { params["utmSource"] = utmSource }
+        if let utmMedium = options.utmMedium { params["utmMedium"] = utmMedium }
+        if let utmCampaign = options.utmCampaign { params["utmCampaign"] = utmCampaign }
+        if let utmTerm = options.utmTerm { params["utmTerm"] = utmTerm }
+        if let utmContent = options.utmContent { params["utmContent"] = utmContent }
+        if let utmUrl = options.utmUrl { params["utmUrl"] = utmUrl }
+        return trackRawEvent(name: "raw_attribution", params: params)
+    }
+
+    /// Reports a successful login. The kernel stamps the session-level
+    /// identity on subsequent session traffic, emits `login
+    /// {authStatus:"success"}` on the CURRENT session, and atomically restarts
+    /// the app session when the effective identity changed.
+    public func loginSuccess(userId: String, options: [String: String] = [:]) -> ForgeOutcome {
+        recordIdentityEvent(kind: "loginSuccess", fields: options.merging(["userId": userId]) { _, new in new })
+    }
+
+    /// Reports a failed login attempt: `login {authStatus:"failure"}`.
+    public func loginFailed(options: [String: String] = [:]) -> ForgeOutcome {
+        recordIdentityEvent(kind: "loginFailed", fields: options)
+    }
+
+    /// Reports a logout. The `logout` event still carries the outgoing user;
+    /// the kernel then clears the identity to Anonymous and atomically
+    /// restarts the app session.
+    public func logout(options: [String: String] = [:]) -> ForgeOutcome {
+        recordIdentityEvent(kind: "logout", fields: options)
+    }
+
+    /// Reports a profile creation: `profile_created {profileId, profileType?}`.
+    public func profileCreated(profileId: String, options: [String: String] = [:]) -> ForgeOutcome {
+        recordIdentityEvent(kind: "profileCreated", fields: options.merging(["profileId": profileId]) { _, new in new })
+    }
+
+    /// Reports a profile selection. Stamps `profileId` on the session identity
+    /// and atomically restarts the app session when the profile changed.
+    public func profileSelected(profileId: String, options: [String: String] = [:]) -> ForgeOutcome {
+        recordIdentityEvent(kind: "profileSelected", fields: options.merging(["profileId": profileId]) { _, new in new })
+    }
+
+    /// Reports a profile deletion: `profile_deleted {profileId}`.
+    public func profileDeleted(profileId: String) -> ForgeOutcome {
+        recordIdentityEvent(kind: "profileDeleted", fields: ["profileId": profileId])
+    }
+
+    /// 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
+    /// session-event params. Validation failures (e.g. a missing `userId`)
+    /// surface as `failedWithDiagnostic` outcomes from the kernel.
+    public func recordIdentityEvent(kind: String, fields: [String: String] = [:], timestampMs: Int64 = 0) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        return runtime.recordIdentityEvent(
+            kind: kind,
+            timemarkMs: timestampMs,
+            fields: PrivacySanitizer.sanitize(fields)
+        )
+    }
+
+    public func trackNetworkRequest(_ record: NetworkRequestRecord) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        return runtime.recordNetworkEvent(record)
+    }
+
+    public func recordApplicationForeground(_ foreground: Bool, timestampMs: Int64 = 0) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        return runtime.recordApplicationForeground(foreground, timestampMs: timestampMs)
+    }
+
+    public func setLogLevel(_ level: ForgeLogLevel) -> ForgeOutcome {
+        logger.setLevel(level)
+        return runtime.setLogLevel(level)
+    }
+
+    public func effectiveLogLevel() -> ForgeLogLevel {
+        logger.effectiveLevel()
+    }
+
+    public func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView {
+        runtime.createVideoView(timestampMs: timestampMs, options: options)
+    }
+
+    public func recordPlayerEvent(
+        view: RuntimeVideoView,
+        event: PlayerEvent,
+        timestampMs: Int64,
+        metadata: PlayerMetadataSnapshot,
+        options: VideoOptions
+    ) -> ForgeOutcome {
+        runtime.recordPlayerEvent(
+            view: view,
+            event: event,
+            timemarkMs: timestampMs,
+            elapsedRealtimeMs: elapsedRealtimeFor(timestampMs),
+            options: options,
+            metadata: metadata
+        )
+    }
+
+    public func recordAdEvent(
+        view: RuntimeVideoView,
+        event: AdEvent,
+        timestampMs: Int64,
+        metadata: AdMetadataSnapshot,
+        options: VideoOptions,
+        adapterVersion: String?
+    ) -> ForgeOutcome {
+        runtime.recordAdEvent(
+            view: view,
+            event: event,
+            timemarkMs: timestampMs,
+            elapsedRealtimeMs: elapsedRealtimeFor(timestampMs),
+            options: options,
+            metadata: metadata,
+            adapterVersion: adapterVersion
+        )
+    }
+
+    public func registerContentMetadataProvider(view: RuntimeVideoView, provider: RuntimeContentMetadataProvider?) -> ForgeOutcome {
+        runtime.registerContentMetadataProvider(view: view, provider: provider)
+    }
+
+    public func registerVideoPreSendHook(view: RuntimeVideoView, hook: RuntimeVideoPreSendHook?) -> ForgeOutcome {
+        runtime.registerVideoPreSendHook(view: view, hook: hook)
+    }
+
+    public func registerSessionPreSendHook(_ hook: RuntimeSessionPreSendHook?) -> ForgeOutcome {
+        runtime.registerSessionPreSendHook(hook)
+    }
+
+    public func addOnSendRequestListener(_ listener: @escaping (String, inout [String: String]) -> Void) -> ForgeEventSubscription {
+        let id = UUID()
+        lock.lock()
+        onSendRequestListeners[id] = listener
+        lock.unlock()
+        refreshSessionPreSendHook()
+        return ForgeEventSubscription { [weak self] in
+            self?.lock.lock()
+            self?.onSendRequestListeners.removeValue(forKey: id)
+            self?.lock.unlock()
+            self?.refreshSessionPreSendHook()
+        }
+    }
+
+    public func subscribeEvents(_ observer: @escaping (ForgeRecordedEvent, ForgeOutcome) -> Void) -> ForgeEventSubscription {
+        let id = UUID()
+        lock.lock()
+        eventObservers[id] = observer
+        lock.unlock()
+        return ForgeEventSubscription { [weak self] in
+            self?.lock.lock()
+            self?.eventObservers.removeValue(forKey: id)
+            self?.lock.unlock()
+        }
+    }
+
+    /// Observes kernel-derived capture plans. The latest plan (if any) is
+    /// replayed synchronously so listeners registered after the first
+    /// emission still reconcile their observers immediately.
+    public func addCapturePlanListener(_ listener: @escaping (ForgeCapturePlan) -> Void) -> ForgeEventSubscription {
+        let id = UUID()
+        lock.lock()
+        capturePlanObservers[id] = listener
+        let replay = latestCapturePlan
+        lock.unlock()
+        if let replay {
+            listener(replay)
+        }
+        return ForgeEventSubscription { [weak self] in
+            self?.lock.lock()
+            self?.capturePlanObservers.removeValue(forKey: id)
+            self?.lock.unlock()
+        }
+    }
+
+    /// Latest kernel-emitted capture plan, or `nil` before the first
+    /// emission. Adapters read `capturePlan()?.behavior` at view start for
+    /// the remote behavior hints.
+    public func capturePlan() -> ForgeCapturePlan? {
+        lock.lock()
+        let latest = latestCapturePlan
+        lock.unlock()
+        return latest ?? runtime.capturePlan()
+    }
+
+    private func dispatchCapturePlan(_ plan: ForgeCapturePlan) {
+        lock.lock()
+        guard !destroyed else {
+            lock.unlock()
+            return
+        }
+        latestCapturePlan = plan
+        let observers = Array(capturePlanObservers.values)
+        lock.unlock()
+        observers.forEach { $0(plan) }
+    }
+
+    public func destroyVideoView(_ view: RuntimeVideoView) -> ForgeOutcome {
+        runtime.destroyVideoView(view)
+    }
+
+    public func snapshotEvents() -> [ForgeRecordedEvent] {
+        let snapshot = runtime.snapshotEvents()
+        if !snapshot.isEmpty { return snapshot }
+        lock.lock()
+        defer { lock.unlock() }
+        return recordedEvents
+    }
+
+    public func destroy() -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredDuplicate }
+        destroyed = true
+        eventObservers.removeAll()
+        onSendRequestListeners.removeAll()
+        capturePlanObservers.removeAll()
+        recordedEvents.removeAll()
+        _ = runtime.registerSessionPreSendHook(nil)
+        _ = runtime.setCapturePlanListener(nil)
+        return runtime.destroy()
+    }
+
+    private func appSessionPayload(eventName: String, payload: [String: String]) -> [String: String] {
+        if eventName.hasPrefix("raw_") { return payload }
+        return ["appName": config.appName]
+            .merging(config.appReleaseVersion.map { ["appReleaseVersion": $0] } ?? [:]) { _, new in new }
+            .merging(payload) { _, new in new }
+    }
+
+    private func maxPayloadValueLength(_ eventName: String) -> Int {
+        eventName == "app_crash" ? 16_384 : 512
+    }
+
+    private func elapsedRealtimeFor(_ timestampMs: Int64) -> Int64 {
+        timestampMs <= 0 ? 0 : ForgeClock.elapsedRealtimeMs(anchorTimestampMs: timestampMs)
+    }
+
+    private func recordRuntimeEvent(_ event: ForgeRecordedEvent, outcome: ForgeOutcome) {
+        if recordedEvents.contains(event) { return }
+        recordedEvents.append(event)
+        if recordedEvents.count > Self.eventSnapshotLimit {
+            recordedEvents.removeFirst(recordedEvents.count - Self.eventSnapshotLimit)
+        }
+        eventObservers.values.forEach { observer in
+            observer(event, outcome)
+        }
+    }
+
+    private func refreshSessionPreSendHook() {
+        if onSendRequestListeners.isEmpty {
+            _ = runtime.registerSessionPreSendHook(nil)
+            return
+        }
+        let hook = SessionPreSendHook { [weak self] serviceName, params in
+            guard let self else { return }
+            self.lock.lock()
+            let listeners = Array(self.onSendRequestListeners.values)
+            self.lock.unlock()
+            listeners.forEach { $0(serviceName, &params) }
+        }
+        _ = runtime.registerSessionPreSendHook(hook)
+    }
+}
+
+private extension ForgeAppleConfig {
+    func withPluginVersion(_ pluginVersion: String) -> ForgeAppleConfig {
+        var copy = self
+        copy.pluginVersion = pluginVersion
+        return copy
+    }
+}
+
+public final class ForgeEventSubscription {
+    private let cancelBlock: () -> Void
+    private var cancelled = false
+    private let lock = NSLock()
+
+    public init(_ cancelBlock: @escaping () -> Void) {
+        self.cancelBlock = cancelBlock
+    }
+
+    public func cancel() {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !cancelled else { return }
+        cancelled = true
+        cancelBlock()
+    }
+}
+
+private final class SessionPreSendHook: RuntimeSessionPreSendHook {
+    private let callback: (String, inout [String: String]) -> Void
+
+    init(callback: @escaping (String, inout [String: String]) -> Void) {
+        self.callback = callback
+    }
+
+    func willSendRequest(serviceName: String, params: inout [String: String]) {
+        callback(serviceName, &params)
+    }
+}