@apex-inc/capacitor-plugin 0.3.9 → 2.2.0

package/ios/Sources/ApexCapacitorPluginBridge/ApexCapacitorPlugin.swift

@@ -14,6 +14,9 @@ import Foundation
 import Capacitor
 import UIKit
 import UserNotifications
+#if canImport(StoreKit)
+import StoreKit
+#endif
 
 @objc(ApexCapacitorPlugin)
 public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificationCenterDelegate {
@@ -30,6 +33,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         CAPPluginMethod(name: "getInstallReferrer", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getVisitorId", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "setVisitorId", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "identify", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "updateConversionValue", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getInitialDeepLink", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getDeviceInfo", returnType: CAPPluginReturnPromise),
@@ -69,13 +73,26 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     private var testMode = false
     private var debug = false
     private var apiBaseUrl: String = ""
-    private var projectKey: String = ""
+    private var workspaceKey: String = ""
+    // Phase 2-SDK — optional workspace-bound API key forwarded as
+    // `x-apex-api-key` on every event POST and on `identify()`.
+    private var apiKey: String? = nil
 
     // 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?
+
+    // MMP-061 — cached release channel + source. Detected once per
+    // launch in `initialize()` and stamped on every event + push token
+    // registration. iOS authoritative path uses AppTransaction (iOS
+    // 16+) or appStoreReceiptURL.lastPathComponent fallback. Re-detect
+    // on `app_open` events since a re-install over an existing build
+    // can change the receipt path.
+    private var releaseChannel: String = "unknown"
+    private var releaseChannelSource: String = "auto"
+    private var lastReleaseChannelDetectedAt: Date = Date(timeIntervalSince1970: 0)
     // MMP-207 — debounced flush. Without this, every `track()` call
     // kicked a POST, so 8 quick taps = 8 separate single-event HTTP
     // requests. With debounce, rapid-fire events coalesce into one
@@ -169,15 +186,38 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     // MARK: - Lifecycle
 
     @objc public func initialize(_ call: CAPPluginCall) {
-        let pk = call.getString("projectKey") ?? ""
+        let pk = call.getString("workspaceKey") ?? ""
         if pk.isEmpty {
-            call.reject("projectKey is required")
+            call.reject("workspaceKey is required")
             return
         }
-        projectKey = pk
-        apiBaseUrl = call.getString("apiUrl") ?? "https://api.apex.inc"
+        workspaceKey = pk
+        apiBaseUrl = call.getString("apiUrl") ?? "https://app.apex.inc"
         testMode = call.getBool("testMode") ?? false
         debug = call.getBool("debug") ?? false
+        // Phase 2-SDK — workspace-bound API key (optional). Stamped on
+        // every outbound request as `x-apex-api-key` so the server can
+        // authorize quarantine-mode auto-stitch.
+        let rawKey = call.getString("apiKey") ?? ""
+        apiKey = rawKey.isEmpty ? nil : rawKey
+
+        // MMP-061 — release channel detection. iOS uses the receipt URL
+        // + StoreKit 2 AppTransaction. Any JS-supplied override on iOS
+        // is ignored (receipt URL is authoritative) but we log a warn
+        // so the discrepancy is visible during development.
+        let jsOverride = call.getString("releaseChannel")
+        if let override = jsOverride, !override.isEmpty {
+            if debug {
+                print("[apex-capacitor] WARN: ignoring releaseChannel='\(override)' override on iOS — AppTransaction / receipt URL is authoritative. Server will record releaseChannelSource=auto.")
+            }
+        }
+        let detected = detectReleaseChannelSync()
+        releaseChannel = detected
+        releaseChannelSource = "auto"
+        lastReleaseChannelDetectedAt = Date()
+        if debug {
+            print("[apex-capacitor] releaseChannel detected = \(detected)")
+        }
         let queueDir = FileManager.default
             .urls(for: .applicationSupportDirectory, in: .userDomainMask)
             .first!
@@ -193,17 +233,45 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         // periodic flush + flushes on every foreground transition.
         batchSender = NativeBatchSender(
             apiBaseUrl: apiBaseUrl,
-            projectKey: projectKey,
+            workspaceKey: workspaceKey,
             platformHeader: "ios",
+            apiKey: apiKey,
             debug: debug
         )
         scheduleFlushTimer()
         observeForegroundForFlush()
         kickFlush(reason: "initialize")
 
+        // Push token persistence (post-MMP-177 fix): iOS keeps notification
+        // permission across reinstalls, but the dashboard / sample-app UI
+        // forgets the token between launches. By installing a persistent
+        // `onTokenReceived` hook AND triggering a silent re-register when
+        // permission is already granted, we (a) surface the token on
+        // every cold start without re-prompting the user and (b) re-upload
+        // it to the backend with the latest metadata — critical because
+        // older plugin builds didn't ship the `environment` field, so
+        // legacy tokens were getting routed to the wrong APNs endpoint.
+        pushManager.onTokenReceived = { [weak self] token in
+            self?.handleTokenArrived(token)
+        }
+        pushManager.silentRegisterIfAuthorized()
+
         call.resolve()
     }
 
+    /// Forward a freshly-arrived APNs device token to JS listeners and
+    /// register it with the Apex backend. Shared by the explicit
+    /// `registerForPushNotifications()` path and the silent re-register
+    /// path triggered by `initialize` so neither one drifts ahead of
+    /// the other.
+    private func handleTokenArrived(_ token: String) {
+        notifyListeners("pushTokenReceived", data: [
+            "token": token,
+            "platform": "ios"
+        ])
+        registerTokenWithApex(token: token)
+    }
+
     /// Schedules a periodic 30s flush so events that arrive in bursts
     /// (or during background) leave the device on a steady cadence.
     private func scheduleFlushTimer() {
@@ -266,24 +334,12 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
 
     @objc public func registerForPushNotifications(_ call: CAPPluginCall) {
         pushManager.requestAuthorizationAndRegister { [weak self] outcome in
-            guard let self = self else {
-                call.resolve(["permission": outcome.permission.rawValue, "token": outcome.token as Any])
-                return
-            }
-
-            // Surface the token to JS subscribers.
-            if let token = outcome.token {
-                self.notifyListeners("pushTokenReceived", data: [
-                    "token": token,
-                    "platform": "ios"
-                ])
-                // Auto-register with the Apex backend so the dashboard
-                // sees this device immediately. The wizard relies on
-                // this so the test-push step finds a registered token
-                // without the customer wiring anything explicitly.
-                self.registerTokenWithApex(token: token)
-            }
-
+            // `handleTokenArrived` is invoked by the manager's
+            // `onTokenReceived` hook installed during `initialize`, so
+            // we DON'T re-fire it here — doing so would double-register
+            // the token with the Apex backend. We only resolve the
+            // JS promise with the registration outcome.
+            _ = self
             call.resolve([
                 "permission": outcome.permission.rawValue,
                 "token": outcome.token as Any
@@ -291,22 +347,132 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         }
     }
 
+    /// Detect the APNs environment this build was provisioned against.
+    ///
+    /// iOS issues two kinds of device tokens for the same physical device —
+    /// sandbox tokens for development builds (Xcode debug + Xcode-archive
+    /// development distributions) and production tokens for everything else
+    /// (TestFlight, App Store). The two are routed to different APNs
+    /// endpoints; sending a sandbox token to the production endpoint (or
+    /// vice versa) results in `BadDeviceToken` and the push is dropped.
+    ///
+    /// We report the environment alongside the token at registration time
+    /// so the server-side dispatcher can route each push to the right
+    /// endpoint without the merchant guessing.
+    ///
+    /// Detection strategy:
+    ///   - `#if DEBUG` — Xcode debug builds always use sandbox APNs.
+    ///   - Release builds: inspect the embedded provisioning profile's
+    ///     `aps-environment` entitlement when accessible; default to
+    ///     "production" for App Store / TestFlight distributions.
+    private func detectApnsEnvironment() -> String {
+        #if DEBUG
+        return "sandbox"
+        #else
+        // Release builds: try the embedded provisioning profile's
+        // aps-environment entitlement. If we can't read it (App Store
+        // builds typically can't), assume production — TestFlight + App
+        // Store both use the production APNs gateway.
+        if let profilePath = Bundle.main.path(forResource: "embedded", ofType: "mobileprovision"),
+           let profileData = try? Data(contentsOf: URL(fileURLWithPath: profilePath)),
+           let profileString = String(data: profileData, encoding: .ascii) {
+            if profileString.contains("aps-environment") &&
+               profileString.range(of: "<string>development</string>", options: .literal) != nil {
+                return "sandbox"
+            }
+        }
+        return "production"
+        #endif
+    }
+
+    /// MMP-061 — detect the build's `releaseChannel`. This is orthogonal
+    /// to `detectApnsEnvironment()`: a TestFlight build is `releaseChannel
+    /// = "testflight"` but its APNs environment is `"production"` (TestFlight
+    /// uses the prod APNs gateway). Filtering test-pushes by APNs
+    /// environment alone would route them to App Store users too.
+    ///
+    /// Detection waterfall (order matters):
+    ///   1. **iOS Simulator** — always `xcode-debug`, regardless of any
+    ///      receipt or AppTransaction signal. `sandboxReceipt` is also
+    ///      present in the simulator, so without this guard every
+    ///      simulator-driven event would tag as `testflight`.
+    ///   2. **`#if DEBUG`** — Xcode-attached debug build → `xcode-debug`.
+    ///      AppTransaction.shared is `.unverified` for unsigned dev
+    ///      builds; this case is the cheapest one to handle first.
+    ///   3. **StoreKit 2 AppTransaction** (iOS 16+) — the canonical
+    ///      authoritative signal. Maps `.xcode` → `xcode-debug`,
+    ///      `.sandbox` → `testflight`, `.production` → `app-store`.
+    ///      Best-effort: if AppTransaction fails to validate (offline,
+    ///      .unverified), fall through to step 4 rather than returning
+    ///      `unknown`.
+    ///   4. **`appStoreReceiptURL.lastPathComponent`** fallback — works
+    ///      offline and on iOS 15 and below. `"sandboxReceipt"` → TestFlight
+    ///      (we already excluded simulator + DEBUG above so this is the
+    ///      genuine TestFlight case). `"receipt"` → `app-store`. Anything
+    ///      else (nil URL, enterprise / in-house distribution) → `unknown`.
+    ///
+    /// Note: we make this synchronous so `initialize()` can stamp the
+    /// channel before the first event lands. AppTransaction.shared is an
+    /// async API — we fall through to the receipt-URL path inside the
+    /// sync flow rather than blocking, and a follow-up async refresh
+    /// could be wired in if validation drift turns up in the wild.
+    private func detectReleaseChannelSync() -> String {
+        // Step 1 — iOS Simulator. Critical bug-prevention check; the
+        // simulator's `sandboxReceipt` would otherwise look identical
+        // to a real TestFlight build.
+        #if targetEnvironment(simulator)
+        return "xcode-debug"
+        #endif
+
+        // Step 2 — Xcode-attached debug build.
+        #if DEBUG
+        return "xcode-debug"
+        #endif
+
+        // Step 3 + 4 below run only on release builds on real devices.
+
+        // Step 4 — receipt URL fallback (works offline, all iOS versions).
+        // The receipt is set at install time and re-set after a re-install,
+        // so re-detecting on `app_open` keeps it fresh after a TestFlight
+        // → App Store upgrade on the same device.
+        if let receiptURL = Bundle.main.appStoreReceiptURL {
+            let last = receiptURL.lastPathComponent
+            if last == "sandboxReceipt" {
+                return "testflight"
+            }
+            if last == "receipt" {
+                return "app-store"
+            }
+        }
+
+        // Enterprise / in-house distribution / missing receipt → unknown.
+        return "unknown"
+    }
+
     private func registerTokenWithApex(token: String) {
-        guard !apiBaseUrl.isEmpty, !projectKey.isEmpty else {
+        guard !apiBaseUrl.isEmpty, !workspaceKey.isEmpty else {
             if debug { print("[apex-capacitor] skipping push-token registration: plugin not initialized") }
             return
         }
         guard let url = URL(string: "\(apiBaseUrl)/api/mobile/push-token") else { return }
         let bundleId = Bundle.main.bundleIdentifier ?? ""
         let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0.0.0"
+        let environment = detectApnsEnvironment()
+        if debug { print("[apex-capacitor] registering push token with environment=\(environment) releaseChannel=\(releaseChannel)") }
         let body: [String: Any] = [
-            "projectKey": projectKey,
+            "workspaceKey": workspaceKey,
             "visitorId": visitorId,
             "platform": "ios",
             "token": token,
             "bundleId": bundleId,
             "sdkVersion": "0.3.0",
-            "appVersion": appVersion
+            "appVersion": appVersion,
+            "environment": environment,
+            // MMP-061 — orthogonal to `environment`. TestFlight tokens
+            // are `releaseChannel: "testflight"` AND `environment:
+            // "production"` because TestFlight uses prod APNs.
+            "releaseChannel": releaseChannel,
+            "releaseChannelSource": releaseChannelSource
         ]
         guard let data = try? JSONSerialization.data(withJSONObject: body) else { return }
         var request = URLRequest(url: url)
@@ -353,6 +519,78 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         call.resolve()
     }
 
+    // MARK: - Identity (Phase 2-SDK)
+
+    /// POSTs to `${apiBaseUrl}/api/identity/stitch` with the current
+    /// visitor id + supplied email + optional userId/traits. The
+    /// server resolves the email to an Apex Contact, stamps
+    /// `verifiedAt = now`, and runs the verified-mode downstream
+    /// pipeline (affiliate stamping, scoring, journey dispatch).
+    ///
+    /// Failure semantics mirror the JS web fallback: rejects on
+    /// non-2xx responses + network errors so the caller can decide
+    /// whether to retry. We deliberately don't queue identify to the
+    /// offline queue — promoting a Contact has different ordering
+    /// guarantees than firing a track event, and merchants tend to
+    /// wire identify behind a one-shot boundary.
+    @objc public func identify(_ call: CAPPluginCall) {
+        guard let email = call.getString("email")?.trimmingCharacters(in: .whitespaces),
+              !email.isEmpty else {
+            call.reject("email is required")
+            return
+        }
+        let userId = call.getString("userId")
+        let traits = call.getObject("traits") ?? [:]
+
+        guard let url = URL(string: "\(apiBaseUrl)/api/identity/stitch") else {
+            call.reject("invalid apiBaseUrl")
+            return
+        }
+        var body: [String: Any] = [
+            "visitorId": visitorId,
+            "email": email,
+            "workspaceKey": workspaceKey,
+            "timestamp": ISO8601DateFormatter().string(from: Date()),
+        ]
+        if let userId = userId, !userId.isEmpty {
+            body["userId"] = userId
+        }
+        if !traits.isEmpty {
+            body["metadata"] = traits
+        }
+
+        var request = URLRequest(url: url)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.setValue("sdk", forHTTPHeaderField: "x-apex-source")
+        request.setValue(workspaceKey, forHTTPHeaderField: "x-apex-workspace")
+        if let key = apiKey {
+            request.setValue(key, forHTTPHeaderField: "x-apex-api-key")
+        }
+        do {
+            request.httpBody = try JSONSerialization.data(withJSONObject: body)
+        } catch {
+            call.reject("Failed to encode identify payload: \(error.localizedDescription)")
+            return
+        }
+
+        URLSession.shared.dataTask(with: request) { _, response, error in
+            if let error = error {
+                call.reject("identify network error: \(error.localizedDescription)")
+                return
+            }
+            guard let http = response as? HTTPURLResponse else {
+                call.reject("identify: missing HTTP response")
+                return
+            }
+            if (200...299).contains(http.statusCode) {
+                call.resolve()
+            } else {
+                call.reject("identify: server rejected (HTTP \(http.statusCode))")
+            }
+        }.resume()
+    }
+
     // MARK: - SKAN
 
     @objc public func updateConversionValue(_ call: CAPPluginCall) {
@@ -391,7 +629,10 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             "appVersion": meta.appVersion,
             "bundleId": meta.bundleId,
             "timezone": meta.timezone,
-            "locale": meta.locale
+            "locale": meta.locale,
+            // MMP-061 — surface to sample apps + developer-facing UIs.
+            "releaseChannel": releaseChannel,
+            "releaseChannelSource": releaseChannelSource
         ])
     }
 
@@ -450,6 +691,25 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         // showed nothing. The visitor id is the stable per-install id
         // we mint in load() and persist to UserDefaults.
         codablePayload["visitorId"] = AnyCodable(visitorId)
+
+        // MMP-061 — stamp release channel under event.mobile so the
+        // server's TrackingEvent shape lands the field in the right
+        // slot. Re-detect on `app_open` so a re-install over the same
+        // device (TestFlight → App Store upgrade) gets the freshest
+        // channel value rather than the cached one from app cold start.
+        let evType = call.getString("type") ?? ""
+        if evType == "app_open" {
+            releaseChannel = detectReleaseChannelSync()
+            lastReleaseChannelDetectedAt = Date()
+            if debug { print("[apex-capacitor] app_open → re-detected releaseChannel = \(releaseChannel)") }
+        }
+        var mobileSlot: [String: Any] = [:]
+        if let existing = codablePayload["mobile"]?.value as? [String: Any] {
+            mobileSlot = existing
+        }
+        mobileSlot["releaseChannel"] = releaseChannel
+        mobileSlot["releaseChannelSource"] = releaseChannelSource
+        codablePayload["mobile"] = AnyCodable(mobileSlot)
         let event = NativeQueuedEvent(
             id: id,
             payload: codablePayload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/capacitor-plugin",
-  "version": "0.3.9",
+  "version": "2.2.0",
   "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",