@apex-inc/capacitor-plugin 0.3.9 → 2.2.0

package/ios/Sources/ApexCapacitorPlugin/ApexEvents.swift

@@ -0,0 +1,124 @@
+/**
+ * Apex Spec — canonical event name constants for the iOS SDK.
+ *
+ * Hand-authored from `app/src/lib/core/apex-spec/events.ts`. Kept in sync
+ * via the parity test at
+ * `app/src/lib/core/apex-spec/__tests__/sdk-parity.test.ts` — CI fails if a
+ * canonical name is added/renamed/removed in the registry without a matching
+ * update here.
+ *
+ * Usage from Swift:
+ *
+ *   plugin.track(type: ApexEvents.addToCart, data: ["product_id": "sku_123"])
+ *
+ * Each constant is the unversioned canonical name as the developer writes it
+ * in `track()` calls. Versions are an internal storage primitive; the SDK
+ * never carries a version field.
+ */
+
+import Foundation
+
+public enum ApexEvents {
+    // MARK: Commerce
+    public static let addToCart = "add_to_cart"
+    public static let removeFromCart = "remove_from_cart"
+    public static let productView = "product_view"
+    public static let addToWishlist = "add_to_wishlist"
+    public static let checkoutStarted = "checkout_started"
+    public static let inAppPurchase = "in_app_purchase"
+    public static let purchaseRefunded = "purchase_refunded"
+    public static let subscriptionEvent = "subscription_event"
+    public static let orderPlaced = "order_placed"
+    public static let firstSaleCompleted = "first_sale_completed"
+
+    // MARK: Marketing (merchant-fired triggers)
+    public static let priceDropped = "price_dropped"
+    public static let restockDue = "restock_due"
+    public static let reviewRequestDue = "review_request_due"
+
+    // MARK: Identity
+    public static let userSignedUp = "user_signed_up"
+    public static let userSignedIn = "user_signed_in"
+    public static let userSignedOut = "user_signed_out"
+    public static let userIdentified = "user_identified"
+
+    // MARK: Lifecycle
+    public static let appInstall = "app_install"
+    public static let appOpen = "app_open"
+    public static let appBackground = "app_background"
+    public static let appUninstall = "app_uninstall"
+    public static let appReinstall = "app_reinstall"
+
+    // MARK: Session
+    public static let sessionStart = "session_start"
+    public static let sessionEnd = "session_end"
+
+    // MARK: Engagement
+    public static let pageView = "page_view"
+    public static let pageview = "pageview"
+    public static let screenView = "screen_view"
+    public static let search = "search"
+    public static let share = "share"
+    public static let contentView = "content_view"
+    public static let formSubmit = "form_submit"
+    public static let click = "click"
+    public static let engagement = "engagement"
+    public static let heartbeat = "heartbeat"
+    public static let rageClick = "rage_click"
+    public static let deadClick = "dead_click"
+    public static let goalConversion = "goal_conversion"
+    public static let onboardingStepCompleted = "onboarding_step_completed"
+
+    // MARK: Product (PLG lifecycle outcomes)
+    public static let onboardingCompleted = "onboarding_completed"
+    public static let activated = "activated"
+
+    // MARK: Communication
+    public static let pushReceived = "push_received"
+    public static let pushOpened = "push_opened"
+    public static let emailOpened = "email_opened"
+    public static let emailClicked = "email_clicked"
+    public static let inAppMessageSeen = "in_app_message_seen"
+    public static let inAppMessageClicked = "in_app_message_clicked"
+
+    // MARK: Deep link
+    public static let deepLinkOpen = "deep_link_open"
+
+    // MARK: Attribution
+    public static let reattribution = "reattribution"
+    public static let reengagement = "reengagement"
+
+    // MARK: Smart banner
+    public static let smartBannerImpression = "smart_banner_impression"
+    public static let smartBannerClick = "smart_banner_click"
+    public static let smartBannerDismiss = "smart_banner_dismiss"
+
+    // MARK: System
+    public static let custom = "custom"
+    public static let lifecycleTransition = "lifecycle_transition"
+    public static let jsError = "js_error"
+
+    /// Apex Spec semver this SDK implements. Bumped together with
+    /// `APEX_SPEC_VERSION` in the TypeScript registry.
+    public static let specVersion = "1.1.0"
+
+    /// Complete list of every canonical event name. Used internally for
+    /// validation; iterate this set if you need to enumerate the spec.
+    public static let all: [String] = [
+        addToCart, removeFromCart, productView, addToWishlist, checkoutStarted,
+        inAppPurchase, purchaseRefunded, subscriptionEvent,
+        userSignedUp, userSignedIn, userSignedOut, userIdentified,
+        appInstall, appOpen, appBackground, appUninstall, appReinstall,
+        sessionStart, sessionEnd,
+        pageView, pageview, screenView, search, share, contentView, formSubmit,
+        click, engagement, heartbeat, rageClick, deadClick, goalConversion,
+        onboardingStepCompleted,
+        onboardingCompleted, activated,
+        pushReceived, pushOpened, emailOpened, emailClicked,
+        inAppMessageSeen, inAppMessageClicked,
+        deepLinkOpen,
+        reattribution, reengagement,
+        smartBannerImpression, smartBannerClick, smartBannerDismiss,
+        custom, lifecycleTransition, jsError,
+    ]
+}

package/ios/Sources/ApexCapacitorPlugin/BatchSender.swift

@@ -30,8 +30,11 @@ public final class NativeBatchSender {
     }
 
     private let apiBaseUrl: String
-    private let projectKey: String
+    private let workspaceKey: String
     private let platformHeader: String
+    // Phase 2-SDK — optional workspace-bound API key forwarded as
+    // `x-apex-api-key` on every batch.
+    private let apiKey: String?
     private let batchSize: Int
     private let maxRetries: Int
     private let baseBackoffMs: Int
@@ -43,8 +46,9 @@ public final class NativeBatchSender {
 
     public init(
         apiBaseUrl: String,
-        projectKey: String,
+        workspaceKey: String,
         platformHeader: String = "ios",
+        apiKey: String? = nil,
         batchSize: Int = 50,
         maxRetries: Int = 3,
         baseBackoffMs: Int = 1000,
@@ -55,8 +59,9 @@ public final class NativeBatchSender {
         var trimmed = apiBaseUrl
         while trimmed.hasSuffix("/") { trimmed.removeLast() }
         self.apiBaseUrl = trimmed
-        self.projectKey = projectKey
+        self.workspaceKey = workspaceKey
         self.platformHeader = platformHeader
+        self.apiKey = apiKey
         self.batchSize = max(1, batchSize)
         self.maxRetries = max(1, maxRetries)
         self.baseBackoffMs = max(0, baseBackoffMs)
@@ -149,15 +154,25 @@ public final class NativeBatchSender {
             return
         }
 
-        // The server accepts `{ projectKey, events: [{ id, ...payload }] }`.
+        // The server accepts `{ workspaceKey, 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).
+        //
+        // MMP-081 — stamp `clientType` at send time so events from the
+        // native iOS plugin land server-side as `native-ios`. We don't
+        // overwrite a value the caller already set on the event
+        // (preserves test fixtures and unusual workflows); the typical
+        // path is that the queued payload doesn't carry one and we
+        // fill it in here.
         let body: [String: Any] = [
-            "projectKey": projectKey,
+            "workspaceKey": workspaceKey,
             "events": batch.map { ev -> [String: Any] in
                 var flat = ev.payload.mapValues { $0.value }
                 flat["id"] = ev.id
+                if flat["clientType"] == nil {
+                    flat["clientType"] = "native-ios"
+                }
                 return flat
             },
         ]
@@ -165,8 +180,11 @@ public final class NativeBatchSender {
         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(workspaceKey, forHTTPHeaderField: "X-Apex-Workspace-Key")
         request.setValue(platformHeader, forHTTPHeaderField: "X-Apex-Platform")
+        if let key = apiKey {
+            request.setValue(key, forHTTPHeaderField: "x-apex-api-key")
+        }
         request.timeoutInterval = 20
 
         do {

package/ios/Sources/ApexCapacitorPlugin/OfflineQueue.swift

@@ -165,6 +165,25 @@ public struct AnyCodable: Codable, Equatable {
         switch value {
         case is NSNull:
             try container.encodeNil()
+        case let n as NSNumber:
+            // 2026-05-16 — NSNumber discrimination. Capacitor's JS bridge
+            // hands us every JS number as NSNumber, and Objective-C's
+            // toll-free bridging means `NSNumber(value: 1)` and
+            // `NSNumber(value: true)` both satisfy `as Bool` AND `as Int`.
+            // The previous `case let v as Bool:` branch consumed integer
+            // 1 / 0 first, encoding `quantity: 1` from JS as `quantity:
+            // true` server-side. That broke a) commerce widgets reading
+            // quantity as a number, and b) any journey trigger that
+            // type-checks numeric fields. CFBooleanGetTypeID is the only
+            // reliable way to distinguish a true Bool NSNumber from an
+            // integer NSNumber on Apple platforms.
+            if CFGetTypeID(n) == CFBooleanGetTypeID() {
+                try container.encode(n.boolValue)
+            } else if CFNumberIsFloatType(n) {
+                try container.encode(n.doubleValue)
+            } else {
+                try container.encode(n.int64Value)
+            }
         case let v as Bool:
             try container.encode(v)
         case let v as Int:

package/ios/Sources/ApexCapacitorPlugin/PushNotificationManager.swift

@@ -60,6 +60,18 @@ public final class PushNotificationManager: NSObject {
     private let notificationCenter: NotificationCenter
     private var pendingCompletion: Completion?
 
+    /// Fired on EVERY token arrival, regardless of whether the
+    /// registration was kicked off by an explicit
+    /// `requestAuthorizationAndRegister` call or by `silentRegisterIfAuthorized`.
+    ///
+    /// The plugin uses this to forward the token to JS listeners and to
+    /// re-register the token with the Apex backend. Setting this from
+    /// `initialize` lets us silently refresh the token on every cold
+    /// start when permission is already granted — without this hook the
+    /// merchant would have to manually tap "Enable push" after every
+    /// fresh Xcode install just to surface the token in the dashboard.
+    public var onTokenReceived: ((String) -> Void)?
+
     public init(
         center: UNUserNotificationCenter = .current(),
         application: UIApplication = .shared,
@@ -113,6 +125,36 @@ public final class PushNotificationManager: NSObject {
         }
     }
 
+    /// Re-register for remote notifications WITHOUT prompting when
+    /// permission has already been granted. iOS's permission survives
+    /// app reinstalls (including Xcode debug rebuilds) but the sample
+    /// app's in-memory "have we registered yet?" state does not — so
+    /// merchants kept telling us push permission was "resetting on every
+    /// build". The OS hadn't actually reset anything; we just weren't
+    /// surfacing the fact that permission was still granted.
+    ///
+    /// Calling this on `initialize` re-fires `didRegisterForRemoteNotifications`
+    /// with the device's current token, which flows through `onTokenReceived`
+    /// and refreshes the dashboard registration with the latest plugin
+    /// metadata (including the APNs environment field that older builds
+    /// didn't report).
+    ///
+    /// No-op when permission is denied or hasn't been requested yet —
+    /// the user has to take an explicit action in those cases.
+    public func silentRegisterIfAuthorized() {
+        center.getNotificationSettings { [weak self] settings in
+            guard let self = self else { return }
+            switch settings.authorizationStatus {
+            case .authorized, .provisional, .ephemeral:
+                DispatchQueue.main.async {
+                    self.application.registerForRemoteNotifications()
+                }
+            default:
+                break
+            }
+        }
+    }
+
     // MARK: - AppDelegate bridge
 
     private func observeAppDelegateBridge() {
@@ -137,6 +179,11 @@ public final class PushNotificationManager: NSObject {
         }
         let hex = PushTokenHexFormatter.format(data)
         resolvePending(.init(permission: .granted, token: hex))
+        // Fire after resolvePending so the JS Promise for an explicit
+        // `Apex.registerForPushNotifications()` resolves first, then
+        // the plugin's persistent `onTokenReceived` hook runs to forward
+        // to listeners + the Apex backend.
+        onTokenReceived?(hex)
     }
 
     @objc private func handleDidFail(_: Notification) {