@npaw/forge-react-native 9.6.1

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

@@ -0,0 +1,297 @@
+/**
+ * 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: Typed kernel-derived Capture Plan surfaced to Apple observers. The
+ *               plan tells the binding which capture observer families are worth
+ *               installing (bitmask), plus the focus/limit knobs and remote behavior
+ *               hints for adapters. The kernel intake gates remain the semantic
+ *               authority; the plan is an optimization signal, never the only gate.
+ */
+
+import Foundation
+
+/// Kernel-computed capture plan delivered whenever the kernel-derived plan
+/// hash changes (first session start onward, and after remote-config
+/// refreshes). Test bits with ``isEnabled(_:)`` and the ``Bits`` constants.
+public struct ForgeCapturePlan: Equatable {
+    /// Monotonic emission sequence for the runtime instance.
+    public let planSeq: UInt64
+    /// Family bitmask; see ``Bits``.
+    public let bits: UInt32
+    /// Remote config version the plan was derived from, when known.
+    public let configVersion: String?
+    public let focus: Focus
+    public let limits: Limits
+    public let behavior: Behavior
+    public let sections: Sections
+    public let attribution: Attribution
+    /// Canonical plan hash as a decimal string (full 64-bit value).
+    public let hash: String
+
+    public init(
+        planSeq: UInt64,
+        bits: UInt32,
+        configVersion: String? = nil,
+        focus: Focus,
+        limits: Limits,
+        behavior: Behavior = Behavior(),
+        sections: Sections = Sections(),
+        attribution: Attribution = Attribution(),
+        hash: String
+    ) {
+        self.planSeq = planSeq
+        self.bits = bits
+        self.configVersion = configVersion
+        self.focus = focus
+        self.limits = limits
+        self.behavior = behavior
+        self.sections = sections
+        self.attribution = attribution
+        self.hash = hash
+    }
+
+    public func isEnabled(_ bit: UInt32) -> Bool {
+        bits & bit != 0
+    }
+
+    /// Focus observer knobs the binding needs to run dwell detection.
+    public struct Focus: Equatable {
+        public let dwellThresholdMs: Int64
+        public let dedupeMs: Int64
+        public let repeatUnchangedDwell: Bool
+
+        public init(dwellThresholdMs: Int64, dedupeMs: Int64, repeatUnchangedDwell: Bool) {
+            self.dwellThresholdMs = dwellThresholdMs
+            self.dedupeMs = dedupeMs
+            self.repeatUnchangedDwell = repeatUnchangedDwell
+        }
+    }
+
+    /// Privacy-derived extraction limits applied while building payloads.
+    public struct Limits: Equatable {
+        public let maxTargetTextLength: Int
+        public let maxPayloadFields: Int
+
+        public init(maxTargetTextLength: Int, maxPayloadFields: Int) {
+            self.maxTargetTextLength = maxTargetTextLength
+            self.maxPayloadFields = maxPayloadFields
+        }
+    }
+
+    /// Remote behavior hints observed by adapters (`bh.v`); applied at the
+    /// next view start, never hot-swapped mid-view. `joinMethod` uses the
+    /// canonical tokens `ff`, `ph`, `rd`, or `auto`.
+    public struct Behavior: Equatable {
+        public let joinMethod: String?
+        public let seekHeuristicEnabled: Bool?
+        public let seekJumpThresholdMs: Int64?
+        public let metadataSamplingMs: Int64?
+
+        public init(
+            joinMethod: String? = nil,
+            seekHeuristicEnabled: Bool? = nil,
+            seekJumpThresholdMs: Int64? = nil,
+            metadataSamplingMs: Int64? = nil
+        ) {
+            self.joinMethod = joinMethod
+            self.seekHeuristicEnabled = seekHeuristicEnabled
+            self.seekJumpThresholdMs = seekJumpThresholdMs
+            self.metadataSamplingMs = metadataSamplingMs
+        }
+    }
+
+    /// F3 sections auto-capture knobs (`raw_section_visible`,
+    /// `raw_section_hidden`, `raw_content_impression`, `raw_content_dwell`).
+    /// The CSS selectors are Web-only and carried purely for contract parity;
+    /// Apple discovers sections through explicit registrations,
+    /// `accessibilityIdentifier` markers, and the native-id remote lists.
+    public struct Sections: Equatable {
+        /// Minimum visible-area ratio (0-100) for a section/item to count as visible.
+        public let visibilityThresholdPct: Int
+        /// Continuous visible time an item must sustain before an impression fires.
+        public let impressionMinVisibleMs: Int64
+        /// Focus time on a tracked item before a dwell fires.
+        public let dwellMs: Int64
+        /// Maximum distinct items tracked per screen; extra targets are ignored.
+        public let maxTrackedItems: Int
+        /// Maximum distinct sections tracked per screen; extra targets are ignored.
+        public let maxSections: Int
+        /// Web-only CSS selector; never used on Apple.
+        public let sectionSelector: String?
+        /// Web-only CSS selector; never used on Apple.
+        public let itemSelector: String?
+        /// Exact `accessibilityIdentifier` matches adopted as sections.
+        public let sectionNativeIds: [String]
+        /// Exact `accessibilityIdentifier` matches adopted as items.
+        public let itemNativeIds: [String]
+        /// Remote naming hint (`auto`, `hd`, ...); Apple names come from
+        /// registrations/markers, so this stays a diagnostic passthrough.
+        public let nameFrom: String
+
+        public init(
+            visibilityThresholdPct: Int = 50,
+            impressionMinVisibleMs: Int64 = 1000,
+            dwellMs: Int64 = 1000,
+            maxTrackedItems: Int = 200,
+            maxSections: Int = 20,
+            sectionSelector: String? = nil,
+            itemSelector: String? = nil,
+            sectionNativeIds: [String] = [],
+            itemNativeIds: [String] = [],
+            nameFrom: String = "auto"
+        ) {
+            self.visibilityThresholdPct = visibilityThresholdPct
+            self.impressionMinVisibleMs = impressionMinVisibleMs
+            self.dwellMs = dwellMs
+            self.maxTrackedItems = maxTrackedItems
+            self.maxSections = maxSections
+            self.sectionSelector = sectionSelector
+            self.itemSelector = itemSelector
+            self.sectionNativeIds = sectionNativeIds
+            self.itemNativeIds = itemNativeIds
+            self.nameFrom = nameFrom
+        }
+    }
+
+    /// F4 attribution auto-capture knobs (`raw_attribution`, kernel-gated by
+    /// `rc.at`). `extraQueryKeys` EXTENDS the built-in click-id list (gclid,
+    /// fbclid, ttclid, msclkid, dclid, twclid); `utm_*` handling is always on
+    /// while the family bit is enabled. The kernel's Install Referrer knob is
+    /// Android-only and intentionally not surfaced on Apple (see
+    /// ``fromUniFFIFlat``).
+    public struct Attribution: Equatable {
+        /// Extra query-parameter keys captured verbatim on top of the
+        /// built-in click-id list; never replaces `utm_*` handling.
+        public let extraQueryKeys: [String]
+        /// Whether the redacted landing/deep-link URL rides along as `utmUrl`.
+        public let includeLandingUrl: Bool
+        /// Whether incoming deep links are parsed into `raw_attribution`.
+        public let deriveFromDeepLinks: Bool
+
+        public init(
+            extraQueryKeys: [String] = [],
+            includeLandingUrl: Bool = true,
+            deriveFromDeepLinks: Bool = true
+        ) {
+            self.extraQueryKeys = extraQueryKeys
+            self.includeLandingUrl = includeLandingUrl
+            self.deriveFromDeepLinks = deriveFromDeepLinks
+        }
+    }
+
+    /// Frozen wire contract mirroring `forge_kernel::capture_plan::bits`;
+    /// values must never be reassigned.
+    public enum Bits {
+        public static let navigation: UInt32 = 1 << 0
+        public static let pageView: UInt32 = 1 << 1
+        public static let clicks: UInt32 = 1 << 2
+        public static let scrolls: UInt32 = 1 << 3
+        public static let lifecycle: UInt32 = 1 << 4
+        public static let deepLink: UInt32 = 1 << 5
+        public static let focus: UInt32 = 1 << 6
+        public static let remoteKey: UInt32 = 1 << 7
+        public static let errors: UInt32 = 1 << 8
+        public static let webVitals: UInt32 = 1 << 9
+        public static let network: UInt32 = 1 << 10
+        // Bit positions `1 << 11` and `1 << 12` are permanently RESERVED. They
+        // carried the removed request/response body-content capture flags. The
+        // kernel never sets them and this binding must ignore them; the
+        // positions stay unassigned so existing bits never renumber.
+        public static let sections: UInt32 = 1 << 13
+        public static let attribution: UInt32 = 1 << 14
+    }
+}
+
+extension ForgeCapturePlan {
+    /// Flat-field factory mirroring the UniFFI `AppleCapturePlan` dictionary
+    /// shape. The native runtime mapping and the plan-gating tests share it so
+    /// the typed plan and the wire dictionary cannot drift silently.
+    /// `targetDataAttributes` is a Web-only knob and is intentionally dropped
+    /// on Apple; the sections CSS selectors are carried for contract parity
+    /// but never drive Apple capture. `attributionInstallReferrerEnabled` is
+    /// accepted for the one-to-one passthrough but dropped: the Install
+    /// Referrer source is the Android Play Store API and has no Apple
+    /// counterpart, so no Apple observer can ever consume the knob.
+    static func fromUniFFIFlat(
+        planSeq: UInt64,
+        bits: UInt32,
+        configVersion: String?,
+        focusDwellThresholdMs: UInt64,
+        focusDedupeMs: UInt64,
+        focusRepeatUnchangedDwell: Bool,
+        maxTargetTextLength: UInt32,
+        maxPayloadFields: UInt32,
+        joinMethod: String?,
+        seekHeuristicEnabled: Bool?,
+        seekJumpThresholdMs: UInt64?,
+        metadataSamplingMs: UInt64?,
+        sectionsVisibilityThresholdPct: UInt32,
+        sectionsImpressionMinVisibleMs: UInt64,
+        sectionsDwellMs: UInt64,
+        sectionsMaxTrackedItems: UInt32,
+        sectionsMaxSections: UInt32,
+        sectionsSectionSelector: String?,
+        sectionsItemSelector: String?,
+        sectionsSectionNativeIds: [String],
+        sectionsItemNativeIds: [String],
+        sectionsNameFrom: String,
+        targetDataAttributes: [String],
+        attributionExtraQueryKeys: [String],
+        attributionIncludeLandingUrl: Bool,
+        attributionDeriveFromDeepLinks: Bool,
+        attributionInstallReferrerEnabled: Bool,
+        hash: String
+    ) -> ForgeCapturePlan {
+        func i64(_ value: UInt64) -> Int64 {
+            value > UInt64(Int64.max) ? Int64.max : Int64(value)
+        }
+        return ForgeCapturePlan(
+            planSeq: planSeq,
+            bits: bits,
+            configVersion: configVersion,
+            focus: Focus(
+                dwellThresholdMs: i64(focusDwellThresholdMs),
+                dedupeMs: i64(focusDedupeMs),
+                repeatUnchangedDwell: focusRepeatUnchangedDwell
+            ),
+            limits: Limits(
+                maxTargetTextLength: Int(maxTargetTextLength),
+                maxPayloadFields: Int(maxPayloadFields)
+            ),
+            behavior: Behavior(
+                joinMethod: joinMethod,
+                seekHeuristicEnabled: seekHeuristicEnabled,
+                seekJumpThresholdMs: seekJumpThresholdMs.map(i64),
+                metadataSamplingMs: metadataSamplingMs.map(i64)
+            ),
+            sections: Sections(
+                visibilityThresholdPct: Int(sectionsVisibilityThresholdPct),
+                impressionMinVisibleMs: i64(sectionsImpressionMinVisibleMs),
+                dwellMs: i64(sectionsDwellMs),
+                maxTrackedItems: Int(sectionsMaxTrackedItems),
+                maxSections: Int(sectionsMaxSections),
+                sectionSelector: sectionsSectionSelector,
+                itemSelector: sectionsItemSelector,
+                sectionNativeIds: sectionsSectionNativeIds,
+                itemNativeIds: sectionsItemNativeIds,
+                nameFrom: sectionsNameFrom
+            ),
+            // attributionInstallReferrerEnabled is dropped here: Android-only
+            // (Play Install Referrer); Apple has no equivalent source.
+            attribution: Attribution(
+                extraQueryKeys: attributionExtraQueryKeys,
+                includeLandingUrl: attributionIncludeLandingUrl,
+                deriveFromDeepLinks: attributionDeriveFromDeepLinks
+            ),
+            hash: hash
+        )
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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: Wall-clock and monotonic timing helpers for Apple binding events.
+ */
+
+import Foundation
+
+public enum ForgeClock {
+    public static func nowMs() -> Int64 {
+        Int64(Date().timeIntervalSince1970 * 1000)
+    }
+
+    public static func elapsedRealtimeMs() -> Int64 {
+        Int64(ProcessInfo.processInfo.systemUptime * 1000)
+    }
+
+    public static func elapsedRealtimeMs(anchorTimestampMs: Int64) -> Int64 {
+        elapsedRealtimeMs()
+    }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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 binding log levels, families, and default platform sink.
+ */
+
+import Foundation
+
+@objc(NPAWForgeLogLevel)
+public enum ForgeLogLevel: Int {
+    case off
+    case error
+    case warning
+    case info
+    case debug
+    case trace
+
+    public var wireName: String {
+        switch self {
+        case .off: return "off"
+        case .error: return "error"
+        case .warning: return "warning"
+        case .info: return "info"
+        case .debug: return "debug"
+        case .trace: return "trace"
+        }
+    }
+
+    public static func from(_ value: Any?, default defaultLevel: ForgeLogLevel = .warning) -> ForgeLogLevel {
+        if let level = value as? ForgeLogLevel {
+            return level
+        }
+        guard let raw = value.map({ String(describing: $0).lowercased() }) else {
+            return defaultLevel
+        }
+        switch raw {
+        case "off": return .off
+        case "error": return .error
+        case "warn", "warning": return .warning
+        case "info": return .info
+        case "debug": return .debug
+        case "trace": return .trace
+        default: return defaultLevel
+        }
+    }
+}
+
+public enum ForgeLogFamily: String {
+    case video = "Video"
+    case ad = "Ad"
+    case session = "Session"
+    case capture = "Capture"
+    case network = "Network"
+    case config = "Config"
+    case lifecycle = "Lifecycle"
+    case transport = "Transport"
+    case storage = "Storage"
+    case diagnostics = "Diagnostics"
+}
+
+public protocol ForgeLogSink: AnyObject {
+    func log(level: ForgeLogLevel, family: ForgeLogFamily, message: String, attributes: [String: String])
+}
+
+public final class OSLogForgeLogSink: ForgeLogSink {
+    public init() {}
+
+    public func log(level: ForgeLogLevel, family: ForgeLogFamily, message: String, attributes: [String: String]) {
+        let rendered = "[\(family.rawValue)] \(message) \(attributes)"
+        guard level != .off else { return }
+        NSLog("[NPAW-Forge-Apple] %@", rendered)
+    }
+}
+
+public final class ForgeLogger {
+    private var level: ForgeLogLevel
+    private let sink: ForgeLogSink?
+
+    public init(level: ForgeLogLevel = .warning, sink: ForgeLogSink? = OSLogForgeLogSink()) {
+        self.level = level
+        self.sink = sink
+    }
+
+    public func setLevel(_ level: ForgeLogLevel) {
+        self.level = level
+    }
+
+    public func effectiveLevel() -> ForgeLogLevel {
+        level
+    }
+
+    public func warning(family: ForgeLogFamily, action: String, details: [String: String] = [:]) {
+        guard level.rawValue >= ForgeLogLevel.warning.rawValue else { return }
+        sink?.log(level: .warning, family: family, message: action, attributes: details)
+    }
+
+    public func error(family: ForgeLogFamily, action: String, details: [String: String] = [:]) {
+        guard level.rawValue >= ForgeLogLevel.error.rawValue else { return }
+        sink?.log(level: .error, family: family, message: action, attributes: details)
+    }
+}

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

@@ -0,0 +1,89 @@
+/**
+ * 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 outcome and diagnostic types returned by the Forge Apple binding.
+ */
+
+import Foundation
+
+@objc(NPAWForgeOutcomeCode)
+public enum ForgeOutcomeCode: Int, Equatable {
+    case accepted
+    case deferred
+    case dropped
+    case ignoredDuplicate
+    case ignoredInvalidState
+    case blockedDependency
+    case unsupportedCapability
+    case failedWithDiagnostic
+    case ignoredBeforeSessionStart
+
+    public var wireName: String {
+        switch self {
+        case .accepted: return "accepted"
+        case .deferred: return "deferred"
+        case .dropped: return "dropped"
+        case .ignoredDuplicate: return "ignored_duplicate"
+        case .ignoredBeforeSessionStart: return "ignored_before_session_start"
+        case .ignoredInvalidState: return "ignored_invalid_state"
+        case .blockedDependency: return "blocked_dependency"
+        case .unsupportedCapability: return "unsupported_capability"
+        case .failedWithDiagnostic: return "failed_with_diagnostic"
+        }
+    }
+}
+
+@objc(NPAWForgeOutcome)
+public final class ForgeOutcome: NSObject {
+    @objc public let code: ForgeOutcomeCode
+    @objc public let reason: String?
+    public let details: [String: String]
+
+    public var isAccepted: Bool { code == .accepted }
+
+    public init(code: ForgeOutcomeCode, reason: String? = nil, details: [String: String] = [:]) {
+        self.code = code
+        self.reason = reason
+        self.details = details
+    }
+
+    @objc public static let accepted = ForgeOutcome(code: .accepted)
+    @objc public static let deferred = ForgeOutcome(code: .deferred)
+    @objc public static let dropped = ForgeOutcome(code: .dropped)
+    @objc public static let ignoredDuplicate = ForgeOutcome(code: .ignoredDuplicate)
+    @objc public static let ignoredBeforeSessionStart = ForgeOutcome(code: .ignoredBeforeSessionStart)
+    @objc public static let ignoredInvalidState = ForgeOutcome(code: .ignoredInvalidState)
+    @objc public static let blockedDependency = ForgeOutcome(code: .blockedDependency)
+    @objc public static let unsupportedCapability = ForgeOutcome(code: .unsupportedCapability)
+
+    @objc public static func failedWithDiagnostic(_ reason: String) -> ForgeOutcome {
+        ForgeOutcome(code: .failedWithDiagnostic, reason: reason)
+    }
+
+    public override var description: String {
+        if let reason {
+            return "\(code.wireName):\(reason)"
+        }
+        return code.wireName
+    }
+}
+
+public struct ForgeDiagnostic: Equatable {
+    public let code: String
+    public let message: String
+    public let attributes: [String: String]
+
+    public init(code: String, message: String, attributes: [String: String] = [:]) {
+        self.code = code
+        self.message = message
+        self.attributes = attributes
+    }
+}