@apex-inc/capacitor-plugin 0.1.0

package/ios/Sources/ApexCapacitorPlugin/OfflineQueue.swift

@@ -0,0 +1,191 @@
+//
+//  OfflineQueue.swift
+//  Apex Capacitor Plugin
+//
+//  Durable event queue backed by a file inside the app container. Using
+//  an append-only file on disk keeps things simple — events are small
+//  JSON blobs, we never query by index, and Core Data overhead isn't
+//  justified at the volumes we expect (single-digit events per session
+//  typical, capped at `maxSize`).
+//
+//  Thread-safe via a serial dispatch queue. The JS-side queue is the
+//  source of truth; this native queue exists so events survive
+//  app termination on iOS 14+ where the JS queue would be lost.
+//
+
+import Foundation
+
+public struct NativeQueuedEvent: Codable, Equatable {
+    public let id: String
+    public let payload: [String: AnyCodable]
+    public var attempts: Int
+    public let enqueuedAt: Date
+}
+
+public enum OfflineQueueError: Error {
+    case missingId
+    case encodingFailed
+}
+
+public final class NativeOfflineQueue {
+    private let fileURL: URL
+    private let maxSize: Int
+    private let queue = DispatchQueue(label: "inc.apex.offline-queue")
+
+    public init(fileURL: URL, maxSize: Int = 1000) {
+        self.fileURL = fileURL
+        self.maxSize = max(1, maxSize)
+        ensureStorageDirectory()
+    }
+
+    public func enqueue(_ event: NativeQueuedEvent) throws {
+        if event.id.isEmpty { throw OfflineQueueError.missingId }
+        try queue.sync {
+            var events = try readLocked()
+            events.append(event)
+            if events.count > maxSize {
+                events.removeFirst(events.count - maxSize)
+            }
+            try writeLocked(events)
+        }
+    }
+
+    public func peek(batchSize: Int) throws -> [NativeQueuedEvent] {
+        if batchSize < 1 { return [] }
+        return try queue.sync {
+            let all = try readLocked()
+            return Array(all.prefix(batchSize))
+        }
+    }
+
+    public func markSent(ids: [String]) throws {
+        if ids.isEmpty { return }
+        try queue.sync {
+            var events = try readLocked()
+            let idSet = Set(ids)
+            events.removeAll { idSet.contains($0.id) }
+            try writeLocked(events)
+        }
+    }
+
+    public func markFailed(ids: [String]) throws {
+        if ids.isEmpty { return }
+        try queue.sync {
+            var events = try readLocked()
+            let idSet = Set(ids)
+            events = events.map { event in
+                if idSet.contains(event.id) {
+                    return NativeQueuedEvent(
+                        id: event.id,
+                        payload: event.payload,
+                        attempts: event.attempts + 1,
+                        enqueuedAt: event.enqueuedAt
+                    )
+                }
+                return event
+            }
+            try writeLocked(events)
+        }
+    }
+
+    public func size() throws -> Int {
+        return try queue.sync {
+            try readLocked().count
+        }
+    }
+
+    public func oldestEventAt() throws -> Date? {
+        return try queue.sync {
+            let events = try readLocked()
+            return events.first?.enqueuedAt
+        }
+    }
+
+    public func clear() throws {
+        try queue.sync {
+            try writeLocked([])
+        }
+    }
+
+    // MARK: - Private
+
+    private func ensureStorageDirectory() {
+        let dir = fileURL.deletingLastPathComponent()
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    }
+
+    private func readLocked() throws -> [NativeQueuedEvent] {
+        guard FileManager.default.fileExists(atPath: fileURL.path) else { return [] }
+        let data = try Data(contentsOf: fileURL)
+        if data.isEmpty { return [] }
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        return try decoder.decode([NativeQueuedEvent].self, from: data)
+    }
+
+    private func writeLocked(_ events: [NativeQueuedEvent]) throws {
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601
+        let data = try encoder.encode(events)
+        try data.write(to: fileURL, options: .atomic)
+    }
+}
+
+/// Minimal Codable wrapper for heterogeneous JSON values.
+public struct AnyCodable: Codable, Equatable {
+    public let value: Any
+
+    public init(_ value: Any) {
+        self.value = value
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        if container.decodeNil() {
+            self.value = NSNull()
+        } else if let v = try? container.decode(Bool.self) {
+            self.value = v
+        } else if let v = try? container.decode(Int.self) {
+            self.value = v
+        } else if let v = try? container.decode(Double.self) {
+            self.value = v
+        } else if let v = try? container.decode(String.self) {
+            self.value = v
+        } else if let v = try? container.decode([AnyCodable].self) {
+            self.value = v.map { $0.value }
+        } else if let v = try? container.decode([String: AnyCodable].self) {
+            self.value = v.mapValues { $0.value }
+        } else {
+            self.value = NSNull()
+        }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        switch value {
+        case is NSNull:
+            try container.encodeNil()
+        case let v as Bool:
+            try container.encode(v)
+        case let v as Int:
+            try container.encode(v)
+        case let v as Double:
+            try container.encode(v)
+        case let v as String:
+            try container.encode(v)
+        case let v as [Any]:
+            try container.encode(v.map { AnyCodable($0) })
+        case let v as [String: Any]:
+            try container.encode(v.mapValues { AnyCodable($0) })
+        default:
+            try container.encodeNil()
+        }
+    }
+
+    public static func == (lhs: AnyCodable, rhs: AnyCodable) -> Bool {
+        // Best-effort equality for Codable containers. Used in tests only.
+        let l = String(describing: lhs.value)
+        let r = String(describing: rhs.value)
+        return l == r
+    }
+}

package/ios/Sources/ApexCapacitorPlugin/SessionManager.swift

@@ -0,0 +1,113 @@
+//
+//  SessionManager.swift
+//  Apex Capacitor Plugin
+//
+//  Native mirror of the TS SessionManager — starts on first activity, ends
+//  after `timeoutMinutes` of inactivity. The JS bridge side also runs a
+//  session manager; the native one handles background-state transitions
+//  (which JS timers can't observe reliably) so sessions end cleanly when
+//  the OS suspends the app.
+//
+
+import Foundation
+
+public struct NativeSessionSnapshot: Equatable {
+    public let sessionId: String
+    public let startedAt: Date
+    public var lastActivityAt: Date
+    public var eventCount: Int
+    public var endedAt: Date?
+    public var durationSeconds: Int?
+}
+
+public final class NativeSessionManager {
+    private let timeoutSeconds: TimeInterval
+    private let clock: () -> Date
+    private let onStart: ((NativeSessionSnapshot) -> Void)?
+    private let onEnd: ((NativeSessionSnapshot) -> Void)?
+    private var timer: Timer?
+    private(set) public var current: NativeSessionSnapshot?
+    private let queue = DispatchQueue(label: "inc.apex.session-manager")
+
+    public init(
+        timeoutMinutes: Int = 30,
+        clock: @escaping () -> Date = { Date() },
+        onStart: ((NativeSessionSnapshot) -> Void)? = nil,
+        onEnd: ((NativeSessionSnapshot) -> Void)? = nil
+    ) {
+        self.timeoutSeconds = TimeInterval(timeoutMinutes * 60)
+        self.clock = clock
+        self.onStart = onStart
+        self.onEnd = onEnd
+    }
+
+    public func recordActivity() -> NativeSessionSnapshot {
+        return queue.sync { () -> NativeSessionSnapshot in
+            let now = clock()
+            if current == nil {
+                let snapshot = NativeSessionSnapshot(
+                    sessionId: UUID().uuidString.lowercased(),
+                    startedAt: now,
+                    lastActivityAt: now,
+                    eventCount: 1,
+                    endedAt: nil,
+                    durationSeconds: nil
+                )
+                current = snapshot
+                onStart?(snapshot)
+            } else {
+                var s = current!
+                s.lastActivityAt = now
+                s.eventCount += 1
+                current = s
+            }
+            scheduleTimeoutLocked()
+            return current!
+        }
+    }
+
+    public func endSession() {
+        queue.sync {
+            endSessionLocked()
+        }
+    }
+
+    public func forceStart() -> NativeSessionSnapshot {
+        queue.sync {
+            if current != nil {
+                endSessionLocked()
+            }
+        }
+        return recordActivity()
+    }
+
+    public func getCurrent() -> NativeSessionSnapshot? {
+        return queue.sync { current }
+    }
+
+    // MARK: - Private
+
+    private func scheduleTimeoutLocked() {
+        timer?.invalidate()
+        let timer = Timer.scheduledTimer(withTimeInterval: timeoutSeconds, repeats: false) { [weak self] _ in
+            self?.queue.async {
+                self?.endSessionLocked()
+            }
+        }
+        RunLoop.main.add(timer, forMode: .common)
+        self.timer = timer
+    }
+
+    private func endSessionLocked() {
+        guard var snapshot = current else { return }
+        timer?.invalidate()
+        timer = nil
+
+        let endAt = clock()
+        snapshot.endedAt = endAt
+        let duration = max(0, Int(endAt.timeIntervalSince(snapshot.startedAt)))
+        snapshot.durationSeconds = duration
+        onEnd?(snapshot)
+        current = nil
+    }
+}

package/ios/Sources/ApexCapacitorPlugin/SkanManager.swift

@@ -0,0 +1,95 @@
+//
+//  SkanManager.swift
+//  Apex Capacitor Plugin
+//
+//  Wraps SKAdNetwork conversion value updates.
+//
+//  - SKAN 3.0 (iOS 11.3-14.x): `SKAdNetwork.updateConversionValue(Int)` — fine value 0-63.
+//  - SKAN 4.0 (iOS 16.1+): `SKAdNetwork.updatePostbackConversionValue(_:coarseValue:completionHandler:)`
+//    — fine value 0-63 plus optional coarse value (`.low`, `.medium`, `.high`).
+//
+//  The class validates inputs (0-63 fine) and routes to the correct API
+//  based on iOS availability and whether a coarse value is provided.
+//
+
+import Foundation
+import StoreKit
+
+public enum SkanCoarseValue: String {
+    case low = "low"
+    case medium = "medium"
+    case high = "high"
+}
+
+public enum SkanError: Error, Equatable {
+    case fineValueOutOfRange(Int)
+}
+
+public final class SkanManager {
+    private let updater: SkanUpdaterProtocol
+
+    public init(updater: SkanUpdaterProtocol = DefaultSkanUpdater()) {
+        self.updater = updater
+    }
+
+    /// Validates `fineValue` is in 0...63. Throws on out-of-range.
+    public static func validateFineValue(_ fineValue: Int) throws {
+        if fineValue < 0 || fineValue > 63 {
+            throw SkanError.fineValueOutOfRange(fineValue)
+        }
+    }
+
+    /// Updates SKAN conversion value. Uses SKAN 4.0 postback API when a coarse
+    /// value is supplied and runtime supports it; otherwise falls back to the
+    /// legacy SKAN 3.0 `updateConversionValue`.
+    public func update(
+        fineValue: Int,
+        coarseValue: SkanCoarseValue? = nil,
+        completion: @escaping (Error?) -> Void
+    ) {
+        do {
+            try SkanManager.validateFineValue(fineValue)
+        } catch {
+            completion(error)
+            return
+        }
+        updater.updateConversionValue(fineValue: fineValue, coarseValue: coarseValue, completion: completion)
+    }
+}
+
+public protocol SkanUpdaterProtocol {
+    func updateConversionValue(
+        fineValue: Int,
+        coarseValue: SkanCoarseValue?,
+        completion: @escaping (Error?) -> Void
+    )
+}
+
+public final class DefaultSkanUpdater: SkanUpdaterProtocol {
+    public init() {}
+
+    public func updateConversionValue(
+        fineValue: Int,
+        coarseValue: SkanCoarseValue?,
+        completion: @escaping (Error?) -> Void
+    ) {
+        if let coarse = coarseValue, #available(iOS 16.1, *) {
+            let apiCoarse: SKAdNetwork.CoarseConversionValue
+            switch coarse {
+            case .low: apiCoarse = .low
+            case .medium: apiCoarse = .medium
+            case .high: apiCoarse = .high
+            }
+            SKAdNetwork.updatePostbackConversionValue(fineValue, coarseValue: apiCoarse) { error in
+                completion(error)
+            }
+        } else if #available(iOS 15.4, *) {
+            SKAdNetwork.updatePostbackConversionValue(fineValue) { error in
+                completion(error)
+            }
+        } else {
+            SKAdNetwork.updateConversionValue(fineValue)
+            completion(nil)
+        }
+    }
+}

package/ios/Sources/ApexCapacitorPluginBridge/ApexCapacitorPlugin.swift

@@ -0,0 +1,269 @@
+//
+//  ApexCapacitorPlugin.swift
+//  Apex Capacitor Plugin
+//
+//  Main plugin class registered with Capacitor. Thin orchestration layer —
+//  actual logic lives in the companion Manager/Provider classes so the
+//  pure-Swift pieces remain testable without the Capacitor SDK loaded.
+//
+//  Methods must be @objc-annotated for Capacitor's ObjC bridge to expose
+//  them to JS. CAPPluginCall is Capacitor's request/response wrapper.
+//
+
+import Foundation
+import Capacitor
+
+@objc(ApexCapacitorPlugin)
+public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin {
+
+    // CAPBridgedPlugin metadata for Capacitor 6+ runtime registration.
+    public let identifier = "ApexCapacitorPlugin"
+    public let jsName = "ApexCapacitorPlugin"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "initialize", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "requestTrackingAuthorization", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getTrackingStatus", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getAdvertisingId", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getInstallReferrer", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getVisitorId", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setVisitorId", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "updateConversionValue", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getInitialDeepLink", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getDeviceInfo", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "startSession", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "endSession", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getCurrentSession", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "track", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getQueueSize", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "flushQueue", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setTestMode", returnType: CAPPluginReturnPromise),
+    ]
+
+    // MARK: - Dependencies (lazy; constructed after initialize())
+
+    private var attManager = AttManager()
+    private var skanManager = SkanManager()
+    private var deviceInfo = DeviceInfo()
+    private var deepLinks = DeepLinkManager()
+    private var adIds = AdvertisingIdProvider()
+    private lazy var sessionManager: NativeSessionManager = {
+        return NativeSessionManager(
+            onStart: { [weak self] snapshot in
+                self?.notifyListeners("sessionStart", data: ["sessionId": snapshot.sessionId])
+            },
+            onEnd: { [weak self] snapshot in
+                self?.notifyListeners("sessionEnd", data: [
+                    "sessionId": snapshot.sessionId,
+                    "durationSeconds": snapshot.durationSeconds ?? 0
+                ])
+            }
+        )
+    }()
+
+    private var offlineQueue: NativeOfflineQueue?
+    private var visitorId: String = ""
+    private var testMode = false
+    private var debug = false
+
+    public override func load() {
+        let defaults = UserDefaults.standard
+        visitorId = defaults.string(forKey: "apex.visitorId") ?? UUID().uuidString.lowercased()
+        defaults.set(visitorId, forKey: "apex.visitorId")
+
+        deepLinks.setWarmLinkHandler { [weak self] url in
+            self?.notifyListeners("deepLink", data: ["url": url.absoluteString])
+        }
+    }
+
+    // MARK: - Lifecycle
+
+    @objc public func initialize(_ call: CAPPluginCall) {
+        let projectKey = call.getString("projectKey") ?? ""
+        if projectKey.isEmpty {
+            call.reject("projectKey is required")
+            return
+        }
+        testMode = call.getBool("testMode") ?? false
+        debug = call.getBool("debug") ?? false
+        let queueDir = FileManager.default
+            .urls(for: .applicationSupportDirectory, in: .userDomainMask)
+            .first!
+            .appendingPathComponent("apex-capacitor")
+        let queueFile = queueDir.appendingPathComponent("events.json")
+        offlineQueue = NativeOfflineQueue(
+            fileURL: queueFile,
+            maxSize: call.getInt("offlineQueueMaxSize") ?? 1000
+        )
+        call.resolve()
+    }
+
+    // MARK: - ATT
+
+    @objc public func requestTrackingAuthorization(_ call: CAPPluginCall) {
+        attManager.request { status in
+            call.resolve(["status": status.rawValue])
+        }
+    }
+
+    @objc public func getTrackingStatus(_ call: CAPPluginCall) {
+        call.resolve(["status": attManager.currentStatus().rawValue])
+    }
+
+    // MARK: - Identifiers
+
+    @objc public func getAdvertisingId(_ call: CAPPluginCall) {
+        let result = adIds.current()
+        call.resolve([
+            "id": result.id as Any,
+            "fallback": result.fallback as Any
+        ])
+    }
+
+    @objc public func getInstallReferrer(_ call: CAPPluginCall) {
+        // iOS has no equivalent of Play Install Referrer.
+        call.resolve(["referrer": NSNull()])
+    }
+
+    @objc public func getVisitorId(_ call: CAPPluginCall) {
+        call.resolve(["visitorId": visitorId])
+    }
+
+    @objc public func setVisitorId(_ call: CAPPluginCall) {
+        guard let id = call.getString("visitorId"), !id.isEmpty else {
+            call.reject("visitorId is required")
+            return
+        }
+        visitorId = id
+        UserDefaults.standard.set(id, forKey: "apex.visitorId")
+        call.resolve()
+    }
+
+    // MARK: - SKAN
+
+    @objc public func updateConversionValue(_ call: CAPPluginCall) {
+        let fineValue = call.getInt("fineValue") ?? 0
+        var coarse: SkanCoarseValue? = nil
+        if let raw = call.getString("coarseValue") {
+            coarse = SkanCoarseValue(rawValue: raw)
+        }
+        skanManager.update(fineValue: fineValue, coarseValue: coarse) { error in
+            if let error = error {
+                call.reject("SKAN update failed: \(error.localizedDescription)")
+            } else {
+                call.resolve()
+            }
+        }
+    }
+
+    // MARK: - Deep Linking
+
+    @objc public func getInitialDeepLink(_ call: CAPPluginCall) {
+        if let url = deepLinks.consumeInitialUrl() {
+            call.resolve(["url": url.absoluteString])
+        } else {
+            call.resolve(["url": NSNull()])
+        }
+    }
+
+    // MARK: - Device Info
+
+    @objc public func getDeviceInfo(_ call: CAPPluginCall) {
+        let meta = deviceInfo.collect()
+        call.resolve([
+            "platform": meta.platform,
+            "osVersion": meta.osVersion,
+            "model": meta.model,
+            "appVersion": meta.appVersion,
+            "bundleId": meta.bundleId,
+            "timezone": meta.timezone,
+            "locale": meta.locale
+        ])
+    }
+
+    // MARK: - Sessions
+
+    @objc public func startSession(_ call: CAPPluginCall) {
+        let snapshot = sessionManager.forceStart()
+        call.resolve(["sessionId": snapshot.sessionId])
+    }
+
+    @objc public func endSession(_ call: CAPPluginCall) {
+        sessionManager.endSession()
+        call.resolve()
+    }
+
+    @objc public func getCurrentSession(_ call: CAPPluginCall) {
+        let current = sessionManager.getCurrent()
+        call.resolve([
+            "sessionId": current?.sessionId ?? NSNull(),
+            "startedAt": current?.startedAt.iso8601String ?? NSNull()
+        ])
+    }
+
+    // MARK: - Events & Queue
+
+    @objc public func track(_ call: CAPPluginCall) {
+        guard let queue = offlineQueue else {
+            call.reject("Plugin not initialized — call initialize() first")
+            return
+        }
+
+        let id = call.getString("id") ?? UUID().uuidString.lowercased()
+        let payloadDict = call.options.compactMapValues { $0 }
+        var codablePayload: [String: AnyCodable] = [:]
+        for (k, v) in payloadDict {
+            codablePayload[k] = AnyCodable(v)
+        }
+        let event = NativeQueuedEvent(
+            id: id,
+            payload: codablePayload,
+            attempts: 0,
+            enqueuedAt: Date()
+        )
+        do {
+            try queue.enqueue(event)
+            call.resolve()
+        } catch {
+            call.reject("Failed to enqueue event: \(error.localizedDescription)")
+        }
+    }
+
+    @objc public func getQueueSize(_ call: CAPPluginCall) {
+        guard let queue = offlineQueue else {
+            call.resolve(["count": 0, "oldestEventAt": NSNull()])
+            return
+        }
+        do {
+            let count = try queue.size()
+            let oldest = try queue.oldestEventAt()?.iso8601String
+            call.resolve([
+                "count": count,
+                "oldestEventAt": oldest ?? NSNull()
+            ])
+        } catch {
+            call.reject("Failed to read queue: \(error.localizedDescription)")
+        }
+    }
+
+    @objc public func flushQueue(_ call: CAPPluginCall) {
+        // Flush is handled by the JS side through the same offline queue
+        // protocol. Native queue is drained by the batch sender which runs
+        // in JS. Here we just report no-op success.
+        call.resolve(["flushed": 0, "remaining": (try? offlineQueue?.size()) ?? 0])
+    }
+
+    @objc public func setTestMode(_ call: CAPPluginCall) {
+        testMode = call.getBool("enabled") ?? false
+        call.resolve()
+    }
+}
+
+// MARK: - Date ISO 8601 helper
+
+private extension Date {
+    var iso8601String: String {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter.string(from: self)
+    }
+}