@apex-inc/capacitor-plugin 0.3.5 → 0.3.7

package/ios/Sources/ApexCapacitorPlugin/BatchSender.swift

@@ -0,0 +1,241 @@
+//
+//  BatchSender.swift
+//  Apex Capacitor Plugin
+//
+//  Drains the NativeOfflineQueue by POSTing batches of events to
+//  `${apiBaseUrl}/api/events`. Mirrors the JS-side BatchSender so the
+//  on-disk queue isn't stranded.
+//
+//  Before this file shipped (plugin <= 0.3.5), `track()` on iOS
+//  enqueued events to the native file-backed queue and `flushQueue()`
+//  was a no-op — events accumulated forever and never reached Apex.
+//  See MMP-205 friction-log F6 for the bug write-up.
+//
+//  Concurrency model:
+//   - Serial DispatchQueue gates send attempts so two flushes don't
+//     race over the same batch.
+//   - URLSession callbacks come in on the URLSession's delegate
+//     queue; we hop back to the serial queue to mutate the offline
+//     queue (markSent / markFailed).
+//
+
+import Foundation
+
+public final class NativeBatchSender {
+
+    public enum SendOutcome {
+        case success
+        case nonRetryable(Int)
+        case retryableExhausted(String)
+    }
+
+    private let apiBaseUrl: String
+    private let projectKey: String
+    private let platformHeader: String
+    private let batchSize: Int
+    private let maxRetries: Int
+    private let baseBackoffMs: Int
+    private let debug: Bool
+    private let urlSession: URLSession
+
+    private let serial = DispatchQueue(label: "inc.apex.batch-sender")
+    private var inFlight = false
+
+    public init(
+        apiBaseUrl: String,
+        projectKey: String,
+        platformHeader: String = "ios",
+        batchSize: Int = 50,
+        maxRetries: Int = 3,
+        baseBackoffMs: Int = 1000,
+        debug: Bool = false,
+        urlSession: URLSession = .shared
+    ) {
+        // Strip trailing slashes; URL joining below assumes none.
+        var trimmed = apiBaseUrl
+        while trimmed.hasSuffix("/") { trimmed.removeLast() }
+        self.apiBaseUrl = trimmed
+        self.projectKey = projectKey
+        self.platformHeader = platformHeader
+        self.batchSize = max(1, batchSize)
+        self.maxRetries = max(1, maxRetries)
+        self.baseBackoffMs = max(0, baseBackoffMs)
+        self.debug = debug
+        self.urlSession = urlSession
+    }
+
+    /// Drains the queue, one batch at a time, with exponential backoff
+    /// on retryable failures. Safe to call concurrently — only one
+    /// flush actually runs at a time; concurrent callers no-op.
+    ///
+    /// Accumulator is passed by value through the recursion (no inout).
+    /// The previous inout-based design tripped Swift's exclusivity
+    /// runtime check at line 85 because the same `totalFlushed` local
+    /// was both captured by the `done` closure and passed inout — a
+    /// classic simultaneous-access violation that traps in debug builds.
+    public func flush(queue: NativeOfflineQueue, completion: @escaping (Int, Int) -> Void) {
+        serial.async { [weak self] in
+            guard let self = self else { completion(0, 0); return }
+            if self.inFlight {
+                // Caller will be picked up by the in-flight flush.
+                let remaining = (try? queue.size()) ?? 0
+                completion(0, remaining)
+                return
+            }
+            self.inFlight = true
+            self.drainLoop(queue: queue, accumulated: 0) { [weak self] flushed in
+                self?.serial.async {
+                    self?.inFlight = false
+                    let remaining = (try? queue.size()) ?? 0
+                    completion(flushed, remaining)
+                }
+            }
+        }
+    }
+
+    /// Recursive drain. `accumulated` is the running total of successfully
+    /// flushed events; `done` is invoked exactly once with the final count.
+    private func drainLoop(
+        queue: NativeOfflineQueue,
+        accumulated: Int,
+        done: @escaping (Int) -> Void
+    ) {
+        let batch: [NativeQueuedEvent]
+        do {
+            batch = try queue.peek(batchSize: batchSize)
+        } catch {
+            if debug { print("[apex-capacitor] peek failed: \(error)") }
+            done(accumulated)
+            return
+        }
+        if batch.isEmpty {
+            done(accumulated)
+            return
+        }
+
+        sendBatchWithRetry(batch, attempt: 0) { [weak self] outcome in
+            guard let self = self else { done(accumulated); return }
+            self.serial.async {
+                let ids = batch.map { $0.id }
+                switch outcome {
+                case .success:
+                    try? queue.markSent(ids: ids)
+                    if self.debug { print("[apex-capacitor] flushed batch of \(batch.count)") }
+                    self.drainLoop(
+                        queue: queue,
+                        accumulated: accumulated + batch.count,
+                        done: done
+                    )
+                case .nonRetryable(let status):
+                    if self.debug { print("[apex-capacitor] non-retryable HTTP \(status); leaving events queued") }
+                    done(accumulated)
+                case .retryableExhausted(let err):
+                    try? queue.markFailed(ids: ids)
+                    if self.debug { print("[apex-capacitor] retries exhausted: \(err)") }
+                    done(accumulated)
+                }
+            }
+        }
+    }
+
+    private func sendBatchWithRetry(
+        _ batch: [NativeQueuedEvent],
+        attempt: Int,
+        completion: @escaping (SendOutcome) -> Void
+    ) {
+        guard !batch.isEmpty else { completion(.success); return }
+        guard let url = URL(string: "\(apiBaseUrl)/api/events") else {
+            completion(.nonRetryable(0))
+            return
+        }
+
+        // The server accepts `{ projectKey, events: [{ id, ...payload }] }`.
+        // We unwrap the queued envelope so the `id` lives at the top
+        // level of each event object (matches what /api/events expects
+        // and what the JS-side BatchSender produces).
+        let body: [String: Any] = [
+            "projectKey": projectKey,
+            "events": batch.map { ev -> [String: Any] in
+                var flat = ev.payload.mapValues { $0.value }
+                flat["id"] = ev.id
+                return flat
+            },
+        ]
+
+        var request = URLRequest(url: url)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.setValue(projectKey, forHTTPHeaderField: "X-Apex-Project-Key")
+        request.setValue(platformHeader, forHTTPHeaderField: "X-Apex-Platform")
+        request.timeoutInterval = 20
+
+        do {
+            request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
+        } catch {
+            completion(.nonRetryable(0))
+            return
+        }
+
+        if debug { print("[apex-capacitor] POST \(url.absoluteString) (\(batch.count) events, attempt \(attempt + 1)/\(maxRetries))") }
+
+        let task = urlSession.dataTask(with: request) { [weak self] _, response, error in
+            guard let self = self else { return }
+
+            if let error = error {
+                self.retryOrFail(
+                    batch: batch,
+                    attempt: attempt,
+                    errorMessage: error.localizedDescription,
+                    completion: completion
+                )
+                return
+            }
+
+            guard let http = response as? HTTPURLResponse else {
+                self.retryOrFail(
+                    batch: batch,
+                    attempt: attempt,
+                    errorMessage: "non-HTTP response",
+                    completion: completion
+                )
+                return
+            }
+
+            if (200..<300).contains(http.statusCode) {
+                completion(.success)
+                return
+            }
+            if (400..<500).contains(http.statusCode) {
+                // Client error — don't retry; preserves events for
+                // inspection but stops hammering the server.
+                completion(.nonRetryable(http.statusCode))
+                return
+            }
+            // 5xx / unknown — retryable.
+            self.retryOrFail(
+                batch: batch,
+                attempt: attempt,
+                errorMessage: "HTTP \(http.statusCode)",
+                completion: completion
+            )
+        }
+        task.resume()
+    }
+
+    private func retryOrFail(
+        batch: [NativeQueuedEvent],
+        attempt: Int,
+        errorMessage: String,
+        completion: @escaping (SendOutcome) -> Void
+    ) {
+        if attempt + 1 >= maxRetries {
+            completion(.retryableExhausted(errorMessage))
+            return
+        }
+        let backoffMs = baseBackoffMs * Int(pow(2.0, Double(attempt)))
+        if debug { print("[apex-capacitor] retry in \(backoffMs)ms (\(errorMessage))") }
+        DispatchQueue.global().asyncAfter(deadline: .now() + .milliseconds(backoffMs)) { [weak self] in
+            self?.sendBatchWithRetry(batch, attempt: attempt + 1, completion: completion)
+        }
+    }
+}

package/ios/Sources/ApexCapacitorPluginBridge/ApexCapacitorPlugin.swift

@@ -12,6 +12,7 @@
 
 import Foundation
 import Capacitor
+import UIKit
 import UserNotifications
 
 @objc(ApexCapacitorPlugin)
@@ -70,6 +71,12 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     private var apiBaseUrl: String = ""
     private var projectKey: String = ""
 
+    // MMP-205 — native batch sender. Drains offlineQueue to /api/events.
+    // Until 0.3.6 this was a no-op; events accumulated on disk and never
+    // reached the server. See friction-log F6.
+    private var batchSender: NativeBatchSender?
+    private var flushTimer: Timer?
+
     public override func load() {
         let defaults = UserDefaults.standard
         visitorId = defaults.string(forKey: "apex.visitorId") ?? UUID().uuidString.lowercased()
@@ -175,9 +182,56 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             fileURL: queueFile,
             maxSize: call.getInt("offlineQueueMaxSize") ?? 1000
         )
+
+        // MMP-205 — wire up the native batch sender so events actually
+        // leave the device. Kicks an immediate flush + starts a 30s
+        // periodic flush + flushes on every foreground transition.
+        batchSender = NativeBatchSender(
+            apiBaseUrl: apiBaseUrl,
+            projectKey: projectKey,
+            platformHeader: "ios",
+            debug: debug
+        )
+        scheduleFlushTimer()
+        observeForegroundForFlush()
+        kickFlush(reason: "initialize")
+
         call.resolve()
     }
 
+    /// Schedules a periodic 30s flush so events that arrive in bursts
+    /// (or during background) leave the device on a steady cadence.
+    private func scheduleFlushTimer() {
+        flushTimer?.invalidate()
+        DispatchQueue.main.async { [weak self] in
+            self?.flushTimer = Timer.scheduledTimer(withTimeInterval: 30.0, repeats: true) { [weak self] _ in
+                self?.kickFlush(reason: "timer")
+            }
+        }
+    }
+
+    private func observeForegroundForFlush() {
+        NotificationCenter.default.addObserver(
+            forName: UIApplication.willEnterForegroundNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.kickFlush(reason: "foreground")
+        }
+    }
+
+    /// Fire-and-forget flush. Safe to call freely; the sender's serial
+    /// queue ensures only one drain runs at a time.
+    private func kickFlush(reason: String) {
+        guard let queue = offlineQueue, let sender = batchSender else { return }
+        if debug { print("[apex-capacitor] flush kicked (\(reason))") }
+        sender.flush(queue: queue) { [weak self] flushed, remaining in
+            if self?.debug == true && (flushed > 0 || remaining > 0) {
+                print("[apex-capacitor] flush done — sent \(flushed), remaining \(remaining)")
+            }
+        }
+    }
+
     // MARK: - ATT
 
     @objc public func requestTrackingAuthorization(_ call: CAPPluginCall) {
@@ -361,6 +415,15 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
                 codablePayload[key] = AnyCodable(v)
             }
         }
+
+        // MMP-205 — stamp testMode + platform on every event so the
+        // server-side dashboards' filters work. Mirrors the JS-side
+        // BatchSender which does the same in web.ts.
+        if testMode {
+            codablePayload["testMode"] = AnyCodable(true)
+        }
+        codablePayload["platform"] = AnyCodable("ios")
+        codablePayload["timestamp"] = AnyCodable(ISO8601DateFormatter().string(from: Date()))
         let event = NativeQueuedEvent(
             id: id,
             payload: codablePayload,
@@ -369,6 +432,10 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         )
         do {
             try queue.enqueue(event)
+            // MMP-205 — kick a flush after every track so single-event
+            // sessions don't sit in the queue until the periodic timer.
+            // The sender's serial gate makes this safe to spam.
+            kickFlush(reason: "track")
             call.resolve()
         } catch {
             call.reject("Failed to enqueue event: \(error.localizedDescription)")
@@ -393,10 +460,16 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     }
 
     @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])
+        // MMP-205 — properly drain the native queue via the native
+        // BatchSender. The previous no-op (events stranded on disk)
+        // is friction-log F6.
+        guard let queue = offlineQueue, let sender = batchSender else {
+            call.resolve(["flushed": 0, "remaining": 0])
+            return
+        }
+        sender.flush(queue: queue) { flushed, remaining in
+            call.resolve(["flushed": flushed, "remaining": remaining])
+        }
     }
 
     @objc public func setTestMode(_ call: CAPPluginCall) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/capacitor-plugin",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Apex Capacitor plugin — iOS/Android attribution, events, deep linking, SKAN, and offline-tolerant tracking for Capacitor apps.",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",