@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/NPAWForgeCapture/AttributionCapture.swift

@@ -0,0 +1,158 @@
+/**
+ * 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: F4/B4 deep-link attribution derivation. Pure query parser turning a
+ *               deep-link URL into `raw_attribution` wire params (camelCase utm_*
+ *               mapping, built-in click-id keys extended by the plan's
+ *               extraQueryKeys, `attributionOrigin: "deep_link"`, and the optional
+ *               redacted `utmUrl`), plus the bounded process-wide per-URL dedupe so
+ *               multi-delegate deep-link delivery emits attribution once. No UIKit:
+ *               fully unit-testable on macOS.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+
+/// Pure deep-link → `raw_attribution` parameter derivation. Matching is
+/// case-insensitive on the query-key name (marketing URLs vary casing) while
+/// values pass through verbatim; the first occurrence of a duplicated query
+/// key wins, mirroring the kernel's `copy_first` fact promotion.
+public enum AttributionDeepLinkParser {
+    /// Built-in paid-click identifier query keys; mirrors the kernel's
+    /// `BUILT_IN_CLICK_ID_KEYS`. The plan's `extraQueryKeys` EXTENDS this
+    /// list, it never replaces it.
+    public static let builtInClickIdKeys = ["gclid", "fbclid", "ttclid", "msclkid", "dclid", "twclid"]
+
+    /// Wire param carrying the derivation origin; the kernel promotes it to
+    /// the `attribution.origin` fact.
+    public static let originParamKey = "attributionOrigin"
+    /// Canonical origin token for deep-link derivation.
+    public static let deepLinkOrigin = "deep_link"
+    /// Optional wire param carrying the redacted landing URL. Deliberately
+    /// NOT an attribution hit by itself and excluded from PPE preserved keys
+    /// kernel-side, so a large URL can never crowd identity fields.
+    public static let landingUrlParamKey = "utmUrl"
+
+    /// `utm_*` query keys mapped to the camelCase wire params the kernel
+    /// promotes into `attribution.source/medium/campaign/term/content`.
+    private static let utmParamsByQueryKey: [String: String] = [
+        "utm_source": "utmSource",
+        "utm_medium": "utmMedium",
+        "utm_campaign": "utmCampaign",
+        "utm_term": "utmTerm",
+        "utm_content": "utmContent",
+    ]
+
+    /// Output params owned by the parser itself. A remote `extraQueryKeys`
+    /// entry naming one of these (any casing) is rejected so a config edge
+    /// can never let `?utmUrl=`/`?attributionOrigin=` count as attribution
+    /// hits or spoof the derived origin/landing fields.
+    private static let reservedOutputKeysLowercased: Set<String> = [
+        originParamKey.lowercased(),
+        landingUrlParamKey.lowercased(),
+    ]
+
+    /// Derives `raw_attribution` params from a deep-link URL, or `nil` when
+    /// the URL carries no utm/click-id signal. `attributionOrigin` and
+    /// `utmUrl` never count as hits on their own: only a matched utm or
+    /// click-id query key produces an event.
+    public static func parse(
+        url: URL,
+        extraQueryKeys: [String] = [],
+        includeLandingUrl: Bool = true
+    ) -> [String: String]? {
+        guard let queryItems = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems,
+              !queryItems.isEmpty else {
+            return nil
+        }
+        // Canonical output spelling per lowercased query key: utm params map
+        // to camelCase, built-ins keep their canonical lowercase form, and
+        // remote extra keys keep the configured spelling. Extras never
+        // override the utm/built-in mappings (a redundant remote "gclid"
+        // stays canonical).
+        var paramKeyByQueryKey = utmParamsByQueryKey
+        for key in builtInClickIdKeys {
+            paramKeyByQueryKey[key] = key
+        }
+        for key in extraQueryKeys {
+            let normalized = key.trimmingCharacters(in: .whitespaces)
+            guard !normalized.isEmpty else { continue }
+            let lookup = normalized.lowercased()
+            guard !reservedOutputKeysLowercased.contains(lookup) else { continue }
+            if paramKeyByQueryKey[lookup] == nil {
+                paramKeyByQueryKey[lookup] = normalized
+            }
+        }
+        var params: [String: String] = [:]
+        for item in queryItems {
+            // Valueless (`?gclid`) and empty (`?gclid=`) keys carry no
+            // signal: skip instead of emitting empty attribution facts.
+            guard let value = item.value, !value.isEmpty else { continue }
+            guard let paramKey = paramKeyByQueryKey[item.name.lowercased()] else { continue }
+            if params[paramKey] == nil {
+                params[paramKey] = value
+            }
+        }
+        guard !params.isEmpty else { return nil }
+        params[originParamKey] = deepLinkOrigin
+        if includeLandingUrl {
+            params[landingUrlParamKey] = PrivacySanitizer.redactUrl(url.absoluteString)
+        }
+        return params
+    }
+}
+
+/// Bounded process-wide dedupe: each exact deep-link URL derives attribution
+/// at most once per process, so scene- and app-delegate double delivery (or
+/// SDK rebuilds replaying the same link) cannot double-count campaigns. FIFO
+/// eviction keeps the memory bound tiny; an evicted URL may emit again, which
+/// is preferable to unbounded growth. The check and the record are split so
+/// callers consume a URL's single slot only after the emission was actually
+/// accepted (a rejected capture never burns the slot).
+enum AttributionDeepLinkDedupe {
+    static let maxTrackedUrls = 16
+
+    private static let lock = NSLock()
+    private static var seenUrls: [String] = []
+
+    /// True when the URL already derived accepted attribution this process.
+    /// Callers must check this only after every other emission gate passed,
+    /// so a plan-disabled sighting never even consults the slot.
+    static func hasSeen(url: String) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return seenUrls.contains(url)
+    }
+
+    /// Records an ACCEPTED derivation for the URL. Never call this for a
+    /// rejected/ignored capture outcome: the URL keeps its slot and a later
+    /// sighting may still derive attribution.
+    static func markSeen(url: String) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !seenUrls.contains(url) else { return }
+        seenUrls.append(url)
+        if seenUrls.count > maxTrackedUrls {
+            seenUrls.removeFirst(seenUrls.count - maxTrackedUrls)
+        }
+    }
+
+    /// Test hook: clears the process-wide seen set so regression tests can
+    /// exercise the dedupe deterministically (mirrors
+    /// `ForgeCrashExceptionHandler.resetForTesting`).
+    static func resetForTesting() {
+        lock.lock()
+        seenUrls.removeAll()
+        lock.unlock()
+    }
+}

package/ios/ForgeApple/Sources/NPAWForgeCapture/CapturePlanGate.swift

@@ -0,0 +1,189 @@
+/**
+ * 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: Effective per-family capture switches combining the local
+ *               CaptureConfiguration flags with the kernel-derived Capture Plan bits.
+ *               Before the first plan arrives every family follows the local flags only
+ *               (today's behavior); once a plan lands, effective(feature) = local flag
+ *               AND plan bit. The gate is the single family chokepoint consulted by
+ *               RawEventCapture and the observer reconciliation.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+
+/// Immutable effective feature snapshot. The focus knobs stay `nil` until a
+/// plan arrives so pre-plan behavior remains byte-identical to the plan-less
+/// capture pipeline; Apple has no dwell machinery yet, so the knobs are
+/// carried for future focus observers and for parity with Android.
+public struct EffectiveCaptureFeatures: Equatable {
+    public let navigation: Bool
+    public let pageView: Bool
+    public let clicks: Bool
+    public let scrolls: Bool
+    public let lifecycle: Bool
+    public let deepLink: Bool
+    public let focus: Bool
+    public let remoteKey: Bool
+    public let focusDwellThresholdMs: Int64?
+    public let focusDedupeMs: Int64?
+    public let repeatUnchangedDwell: Bool
+    /// F3 sections family. Unlike the families above, sections stay OFF until
+    /// the first plan arrives: the sections observation engine is plan-driven
+    /// machinery (install on bit on, uninstall on bit off), so pre-plan
+    /// behavior remains byte-identical to the sections-less pipeline.
+    public let sections: Bool
+    /// Sections knobs from the latest plan; `nil` before the first plan.
+    public let sectionsPlan: ForgeCapturePlan.Sections?
+    /// F4 attribution family (`raw_attribution`, kernel-gated by `rc.at`).
+    /// Mirrors sections: OFF until the first plan arrives, because deep-link
+    /// derivation is plan-driven machinery that needs the plan knobs, so
+    /// pre-plan behavior remains byte-identical to the attribution-less
+    /// pipeline.
+    public let attribution: Bool
+    /// Attribution knobs from the latest plan; `nil` before the first plan.
+    public let attributionPlan: ForgeCapturePlan.Attribution?
+
+    public init(
+        navigation: Bool,
+        pageView: Bool,
+        clicks: Bool,
+        scrolls: Bool,
+        lifecycle: Bool,
+        deepLink: Bool,
+        focus: Bool,
+        remoteKey: Bool,
+        focusDwellThresholdMs: Int64?,
+        focusDedupeMs: Int64?,
+        repeatUnchangedDwell: Bool,
+        sections: Bool = false,
+        sectionsPlan: ForgeCapturePlan.Sections? = nil,
+        attribution: Bool = false,
+        attributionPlan: ForgeCapturePlan.Attribution? = nil
+    ) {
+        self.navigation = navigation
+        self.pageView = pageView
+        self.clicks = clicks
+        self.scrolls = scrolls
+        self.lifecycle = lifecycle
+        self.deepLink = deepLink
+        self.focus = focus
+        self.remoteKey = remoteKey
+        self.focusDwellThresholdMs = focusDwellThresholdMs
+        self.focusDedupeMs = focusDedupeMs
+        self.repeatUnchangedDwell = repeatUnchangedDwell
+        self.sections = sections
+        self.sectionsPlan = sectionsPlan
+        self.attribution = attribution
+        self.attributionPlan = attributionPlan
+    }
+}
+
+/// Combines the local configuration flags with an optional kernel plan.
+/// Pre-plan defaults mirror the historical routing exactly: deep links follow
+/// the navigation switch, scrolls/swipes follow the click switch, and the
+/// focus/remote-key families (which have no local Apple switch) stay open.
+public func effectiveCaptureFeatures(
+    configuration: CaptureConfiguration,
+    plan: ForgeCapturePlan?
+) -> EffectiveCaptureFeatures {
+    func bit(_ bit: UInt32) -> Bool { plan?.isEnabled(bit) ?? true }
+    return EffectiveCaptureFeatures(
+        navigation: configuration.navigationEnabled && bit(ForgeCapturePlan.Bits.navigation),
+        pageView: configuration.navigationEnabled && bit(ForgeCapturePlan.Bits.pageView),
+        clicks: configuration.clickEnabled && bit(ForgeCapturePlan.Bits.clicks),
+        scrolls: configuration.clickEnabled && bit(ForgeCapturePlan.Bits.scrolls),
+        lifecycle: configuration.lifecycleEnabled && bit(ForgeCapturePlan.Bits.lifecycle),
+        deepLink: configuration.navigationEnabled && bit(ForgeCapturePlan.Bits.deepLink),
+        focus: bit(ForgeCapturePlan.Bits.focus),
+        remoteKey: bit(ForgeCapturePlan.Bits.remoteKey),
+        focusDwellThresholdMs: plan?.focus.dwellThresholdMs,
+        focusDedupeMs: plan?.focus.dedupeMs,
+        repeatUnchangedDwell: plan?.focus.repeatUnchangedDwell ?? false,
+        // Sections are plan-driven machinery: closed before the first plan.
+        sections: plan.map { $0.isEnabled(ForgeCapturePlan.Bits.sections) } ?? false,
+        sectionsPlan: plan?.sections,
+        // Attribution derivation is plan-driven machinery too: closed before
+        // the first plan (no local Apple switch; the plan bit decides).
+        attribution: plan.map { $0.isEnabled(ForgeCapturePlan.Bits.attribution) } ?? false,
+        attributionPlan: plan?.attribution
+    )
+}
+
+/// Thread-safe holder for the current effective features. `apply` is safe to
+/// call from the runtime callback thread; readers observe a consistent
+/// immutable snapshot.
+public final class CapturePlanGate {
+    private let configuration: CaptureConfiguration
+    private let lock = NSLock()
+    private var currentFeatures: EffectiveCaptureFeatures
+    private var currentPlan: ForgeCapturePlan?
+
+    public init(configuration: CaptureConfiguration) {
+        self.configuration = configuration
+        self.currentFeatures = effectiveCaptureFeatures(configuration: configuration, plan: nil)
+    }
+
+    public var features: EffectiveCaptureFeatures {
+        lock.lock()
+        defer { lock.unlock() }
+        return currentFeatures
+    }
+
+    public var plan: ForgeCapturePlan? {
+        lock.lock()
+        defer { lock.unlock() }
+        return currentPlan
+    }
+
+    public func apply(_ plan: ForgeCapturePlan) {
+        let features = effectiveCaptureFeatures(configuration: configuration, plan: plan)
+        lock.lock()
+        currentPlan = plan
+        currentFeatures = features
+        lock.unlock()
+    }
+
+    /// Family gate for normalized `raw_*` event names. Mirrors the historical
+    /// CaptureConfiguration routing with the plan bits ANDed in; scroll/swipe
+    /// events separate from tap/click through the dedicated scrolls bit while
+    /// both keep the local `clickEnabled` switch.
+    public func isEventFamilyEnabled(_ eventName: String) -> Bool {
+        let features = features
+        switch eventName {
+        case RawEventName.screenView, RawEventName.fragmentView, RawEventName.composeView:
+            return features.navigation
+        case RawEventName.pageView:
+            return features.pageView
+        case RawEventName.deepLinkReceived:
+            return features.deepLink
+        case RawEventName.tap, RawEventName.click:
+            return features.clicks
+        case RawEventName.scroll, RawEventName.swipe:
+            return features.scrolls
+        case RawEventName.focusChange, RawEventName.focusDwell:
+            return features.focus
+        case RawEventName.remoteKey:
+            return features.remoteKey
+        case RawEventName.sectionVisible, RawEventName.sectionHidden,
+             RawEventName.contentImpression, RawEventName.contentDwell:
+            return features.sections
+        case RawEventName.attribution:
+            return features.attribution
+        case RawEventName.applicationForeground, RawEventName.applicationBackground:
+            return features.lifecycle
+        default:
+            return eventName.hasPrefix("raw_")
+        }
+    }
+}

package/ios/ForgeApple/Sources/NPAWForgeCapture/CrashCapture.swift

@@ -0,0 +1,120 @@
+/**
+ * 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: Bounded safe crash record persistence and next-launch retry support for Apple capture.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+
+struct CrashRecord: Codable, Equatable {
+    let id: String
+    let timestampMs: Int64
+    let name: String
+    let reason: String
+    let stack: String
+
+    init(exception: NSException) {
+        let timestamp = ForgeClock.nowMs()
+        self.timestampMs = timestamp
+        self.name = exception.name.rawValue
+        self.reason = exception.reason ?? "unknown"
+        self.stack = exception.callStackSymbols.joined(separator: "\n")
+        self.id = Self.stableId(name: self.name, reason: self.reason, timestampMs: timestamp, stack: self.stack)
+    }
+
+    func payload(deliveryMode: String) -> [String: String] {
+        [
+            "data.crashId": id,
+            "data.deliveryMode": deliveryMode,
+            "data.crashTimestampMs": String(timestampMs),
+            "data.exception.name": name,
+            "data.exception.reason": reason,
+            "data.exception.stack": String(stack.prefix(16_384)),
+            "data.runtimeFamily": "apple",
+        ]
+    }
+
+    private static func stableId(name: String, reason: String, timestampMs: Int64, stack: String) -> String {
+        let bucket = timestampMs / 10_000
+        let raw = "\(name)|\(reason.prefix(256))|\(stack.components(separatedBy: "\n").first ?? "")|\(bucket)"
+        return String(raw.hashValue)
+    }
+}
+
+final class CrashRecordStore {
+    static let defaultStore = CrashRecordStore(directory: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
+        .appendingPathComponent("forge-crashes", isDirectory: true))
+
+    private let directory: URL?
+    private let maxPending = 5
+    private let lock = NSLock()
+
+    init(directory: URL?) {
+        self.directory = directory
+    }
+
+    func store(_ record: CrashRecord) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let directory else { return }
+        try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        var records = loadPendingUnlocked().filter { $0.id != record.id }
+        records.append(record)
+        records.sort { $0.timestampMs > $1.timestampMs }
+        records = Array(records.prefix(maxPending))
+        clearUnlocked()
+        let encoder = JSONEncoder()
+        for item in records {
+            if let data = try? encoder.encode(item) {
+                try? data.write(to: path(for: item.id), options: [.atomic])
+            }
+        }
+    }
+
+    func loadPending() -> [CrashRecord] {
+        lock.lock()
+        defer { lock.unlock() }
+        return loadPendingUnlocked()
+    }
+
+    func markSent(_ id: String) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let directory else { return }
+        let files = (try? FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil)) ?? []
+        for file in files where file.lastPathComponent.contains(id) {
+            try? FileManager.default.removeItem(at: file)
+        }
+    }
+
+    private func loadPendingUnlocked() -> [CrashRecord] {
+        guard let directory else { return [] }
+        let files = (try? FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil)) ?? []
+        let decoder = JSONDecoder()
+        return files.compactMap { file in
+            guard let data = try? Data(contentsOf: file) else { return nil }
+            return try? decoder.decode(CrashRecord.self, from: data)
+        }.sorted { $0.timestampMs > $1.timestampMs }
+    }
+
+    private func clearUnlocked() {
+        guard let directory else { return }
+        let files = (try? FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil)) ?? []
+        files.forEach { try? FileManager.default.removeItem(at: $0) }
+    }
+
+    private func path(for id: String) -> URL {
+        directory?.appendingPathComponent("\(id).crash") ?? URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("\(id).crash")
+    }
+}