@apex-inc/capacitor-plugin 0.1.0

package/dist/web.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Web fallback implementation of `ApexCapacitorPlugin`.
+ *
+ * Runs when the app is in a browser or Capacitor PWA context where no native
+ * iOS/Android bridge is present. Provides best-effort behavior for every
+ * method — identifiers return null, ATT is a no-op (returns `authorized`),
+ * SKAN is a no-op, deep links come from `window.location`, and events are
+ * batched + sent over fetch via the normal offline queue.
+ *
+ * This module deliberately keeps the heavy lifting (queue, session, batch)
+ * in separate files so unit tests can cover them without DOM mocking.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApexCapacitorWeb = void 0;
+const core_1 = require("@capacitor/core");
+const batch_sender_1 = require("./batch-sender");
+const event_id_1 = require("./event-id");
+const offline_queue_1 = require("./offline-queue");
+const session_manager_1 = require("./session-manager");
+const VISITOR_ID_KEY = "apex.visitorId";
+class ApexCapacitorWeb extends core_1.WebPlugin {
+    constructor() {
+        super(...arguments);
+        this.testMode = false;
+        this.debug = false;
+        this.initialized = false;
+    }
+    async initialize(options) {
+        if (this.initialized)
+            return;
+        this.testMode = options.testMode ?? false;
+        this.debug = options.debug ?? false;
+        const storage = typeof indexedDB !== "undefined" ? new offline_queue_1.IndexedDBStorage() : new offline_queue_1.InMemoryStorage();
+        this.queue = new offline_queue_1.OfflineQueue({
+            storage,
+            maxSize: options.offlineQueueMaxSize ?? 1000,
+            onEvicted: (ev) => {
+                if (this.debug)
+                    console.warn("[apex-capacitor] queue eviction", ev.event.id);
+            },
+        });
+        this.session = new session_manager_1.SessionManager({
+            timeoutMinutes: options.sessionTimeoutMinutes ?? 30,
+            onSessionStart: (s) => this.emitSession("sessionStart", s),
+            onSessionEnd: (s) => this.emitSession("sessionEnd", s),
+        });
+        this.sender = new batch_sender_1.BatchSender({
+            apiUrl: options.apiUrl,
+            projectKey: options.projectKey,
+            platformHeader: "web",
+            debug: this.debug,
+        });
+        this.visitorId = this.loadOrCreateVisitorId();
+        this.initialized = true;
+    }
+    async requestTrackingAuthorization() {
+        return { status: "authorized" };
+    }
+    async getTrackingStatus() {
+        return { status: "authorized" };
+    }
+    async getAdvertisingId() {
+        return { id: null, fallback: null };
+    }
+    async getInstallReferrer() {
+        return { referrer: null };
+    }
+    async getVisitorId() {
+        if (!this.visitorId) {
+            this.visitorId = this.loadOrCreateVisitorId();
+        }
+        return { visitorId: this.visitorId };
+    }
+    async setVisitorId(options) {
+        this.visitorId = options.visitorId;
+        this.saveVisitorId(options.visitorId);
+    }
+    async updateConversionValue(_options) {
+        // No-op on web / non-iOS.
+    }
+    async getInitialDeepLink() {
+        if (typeof window !== "undefined" && window.location) {
+            return { url: window.location.href };
+        }
+        return { url: null };
+    }
+    async getDeviceInfo() {
+        // Best-effort on web — mostly placeholders so callers get consistent shape.
+        const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+        const locale = typeof navigator !== "undefined" ? navigator.language : "en-US";
+        const tz = typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC";
+        return {
+            platform: "android", // Web falls back to android shape; native overrides when present.
+            osVersion: "unknown",
+            model: ua.substring(0, 64),
+            appVersion: "0.0.0",
+            bundleId: typeof location !== "undefined" ? location.host : "web",
+            timezone: tz,
+            locale,
+        };
+    }
+    async startSession() {
+        this.ensureInitialized();
+        const snapshot = this.session.forceStart();
+        return { sessionId: snapshot.sessionId };
+    }
+    async endSession() {
+        if (!this.session)
+            return;
+        this.session.endSession();
+    }
+    async getCurrentSession() {
+        const current = this.session?.getCurrent() ?? null;
+        return {
+            sessionId: current?.sessionId ?? null,
+            startedAt: current?.startedAt ?? null,
+        };
+    }
+    async track(event) {
+        this.ensureInitialized();
+        const sessionSnapshot = this.session.recordActivity();
+        const stamped = {
+            ...event,
+            id: event.id ?? (0, event_id_1.generateEventId)(),
+            timestamp: event.timestamp ?? new Date().toISOString(),
+            sessionId: event.sessionId ?? sessionSnapshot.sessionId,
+        };
+        if (this.testMode) {
+            stamped.data = { ...(stamped.data ?? {}), __testMode: true };
+        }
+        if (stamped.id && !(0, event_id_1.isValidEventId)(stamped.id)) {
+            // Developer mis-set id — overwrite rather than fail the track() call.
+            if (this.debug)
+                console.warn("[apex-capacitor] invalid event.id, regenerating");
+            stamped.id = (0, event_id_1.generateEventId)();
+        }
+        await this.queue.enqueue(stamped);
+        // Attempt delivery; errors are swallowed — events stay queued for next flush.
+        void this.sender.flush(this.queue).catch((err) => {
+            if (this.debug)
+                console.warn("[apex-capacitor] flush error", err);
+        });
+    }
+    async getQueueSize() {
+        if (!this.queue)
+            return { count: 0, oldestEventAt: null };
+        const [count, oldestEventAt] = await Promise.all([
+            this.queue.size(),
+            this.queue.oldestEventAt(),
+        ]);
+        return { count, oldestEventAt };
+    }
+    async flushQueue() {
+        this.ensureInitialized();
+        const result = await this.sender.flush(this.queue);
+        return { flushed: result.flushed, remaining: result.remaining };
+    }
+    async setTestMode(options) {
+        this.testMode = options.enabled;
+    }
+    async removeAllListeners() {
+        await super.removeAllListeners();
+    }
+    emitSession(eventName, session) {
+        const payload = eventName === "sessionStart"
+            ? { sessionId: session.sessionId }
+            : {
+                sessionId: session.sessionId,
+                durationSeconds: session.durationSeconds ?? 0,
+            };
+        this.notifyListeners(eventName, payload);
+    }
+    loadOrCreateVisitorId() {
+        if (typeof localStorage !== "undefined") {
+            const existing = localStorage.getItem(VISITOR_ID_KEY);
+            if (existing)
+                return existing;
+            const fresh = (0, event_id_1.generateEventId)();
+            try {
+                localStorage.setItem(VISITOR_ID_KEY, fresh);
+            }
+            catch {
+                // Storage quota / private mode — fall through to in-memory.
+            }
+            return fresh;
+        }
+        return (0, event_id_1.generateEventId)();
+    }
+    saveVisitorId(id) {
+        if (typeof localStorage !== "undefined") {
+            try {
+                localStorage.setItem(VISITOR_ID_KEY, id);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    ensureInitialized() {
+        if (!this.initialized || !this.queue || !this.session || !this.sender) {
+            throw new Error("Apex plugin not initialized. Call initialize() before using other methods.");
+        }
+    }
+}
+exports.ApexCapacitorWeb = ApexCapacitorWeb;
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"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"}

package/ios/Package.swift

@@ -0,0 +1,34 @@
+// swift-tools-version: 5.9
+//
+// This manifest builds the pure-logic portion of @apex-inc/capacitor-plugin
+// for standalone test runs via `swift test`. The Capacitor-dependent plugin
+// entry point (ApexCapacitorPlugin.swift) lives in a sibling folder and is
+// compiled only through the CocoaPods build path (see .podspec) because it
+// imports the Capacitor framework.
+//
+// Consumers installing the plugin in a Capacitor app get BOTH sources via
+// `npx cap sync` + CocoaPods — this split is purely a testability concern.
+//
+import PackageDescription
+
+let package = Package(
+    name: "ApexCapacitorPlugin",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(
+            name: "ApexCapacitorPlugin",
+            targets: ["ApexCapacitorPlugin"]
+        ),
+    ],
+    targets: [
+        .target(
+            name: "ApexCapacitorPlugin",
+            path: "Sources/ApexCapacitorPlugin"
+        ),
+        .testTarget(
+            name: "ApexCapacitorPluginTests",
+            dependencies: ["ApexCapacitorPlugin"],
+            path: "Tests/ApexCapacitorPluginTests"
+        ),
+    ]
+)

package/ios/Sources/ApexCapacitorPlugin/AdvertisingIdProvider.swift

@@ -0,0 +1,66 @@
+//
+//  AdvertisingIdProvider.swift
+//  Apex Capacitor Plugin
+//
+//  Provides IDFA when ATT is authorized, falls back to IDFV (identifier for
+//  vendor) when denied or not yet prompted. IDFA may return an all-zero UUID
+//  ("00000000-0000-0000-0000-000000000000") when Limit Ad Tracking is on —
+//  we detect that and substitute IDFV with an explicit fallback flag.
+//
+
+import Foundation
+import AdSupport
+#if canImport(UIKit)
+import UIKit
+#endif
+
+public struct AdvertisingIdResult: Equatable {
+    public let id: String?
+    public let fallback: String?   // "idfv" when IDFA unavailable, nil when IDFA is fresh
+}
+
+private let zeroIdfa = "00000000-0000-0000-0000-000000000000"
+
+public final class AdvertisingIdProvider {
+    private let attManager: AttManager
+    private let idfaProvider: () -> String?
+    private let idfvProvider: () -> String?
+
+    public init(
+        attManager: AttManager = AttManager(),
+        idfaProvider: @escaping () -> String? = AdvertisingIdProvider.defaultIdfaProvider,
+        idfvProvider: @escaping () -> String? = AdvertisingIdProvider.defaultIdfvProvider
+    ) {
+        self.attManager = attManager
+        self.idfaProvider = idfaProvider
+        self.idfvProvider = idfvProvider
+    }
+
+    public func current() -> AdvertisingIdResult {
+        let status = attManager.currentStatus()
+        if status == .authorized {
+            if let idfa = idfaProvider(), idfa != zeroIdfa {
+                return AdvertisingIdResult(id: idfa, fallback: nil)
+            }
+        }
+        // ATT denied / restricted / not-determined, OR IDFA returned zero-UUID.
+        if let idfv = idfvProvider() {
+            return AdvertisingIdResult(id: idfv, fallback: "idfv")
+        }
+        return AdvertisingIdResult(id: nil, fallback: nil)
+    }
+
+    // MARK: - Defaults
+
+    public static var defaultIdfaProvider: () -> String? = {
+        return ASIdentifierManager.shared().advertisingIdentifier.uuidString.lowercased()
+    }
+
+    public static var defaultIdfvProvider: () -> String? = {
+        #if canImport(UIKit)
+        return UIDevice.current.identifierForVendor?.uuidString.lowercased()
+        #else
+        return nil
+        #endif
+    }
+}

package/ios/Sources/ApexCapacitorPlugin/AttManager.swift

@@ -0,0 +1,82 @@
+//
+//  AttManager.swift
+//  Apex Capacitor Plugin
+//
+//  Wraps iOS App Tracking Transparency (ATT). Reports status and requests
+//  authorization. Maps Apple's ATTrackingManager.AuthorizationStatus enum
+//  to the stable string contract used by the TS interface.
+//
+
+import Foundation
+import AppTrackingTransparency
+
+public enum AttStatus: String {
+    case authorized = "authorized"
+    case denied = "denied"
+    case restricted = "restricted"
+    case notDetermined = "not-determined"
+
+    /// Stable mapping from Apple's rawValue-less enum to our string contract.
+    /// Apple's constants: notDetermined=0, restricted=1, denied=2, authorized=3.
+    public static func from(authorizationRawValue: UInt) -> AttStatus {
+        switch authorizationRawValue {
+        case 0: return .notDetermined
+        case 1: return .restricted
+        case 2: return .denied
+        case 3: return .authorized
+        default: return .notDetermined
+        }
+    }
+}
+
+/// Thin wrapper around ATTrackingManager. The actual UI prompt can only be
+/// driven from a real iOS runtime, so tests cover the enum mapping; the
+/// live prompt is verified on-device.
+public final class AttManager {
+    private let tracker: AttTrackerProtocol
+
+    public init(tracker: AttTrackerProtocol = DefaultAttTracker()) {
+        self.tracker = tracker
+    }
+
+    /// Returns the current ATT status without presenting the prompt.
+    public func currentStatus() -> AttStatus {
+        return tracker.currentStatus()
+    }
+
+    /// Presents the ATT prompt (once per install) and completes with the
+    /// resulting status.
+    public func request(completion: @escaping (AttStatus) -> Void) {
+        tracker.requestAuthorization { rawValue in
+            completion(AttStatus.from(authorizationRawValue: rawValue))
+        }
+    }
+}
+
+/// Abstraction around ATTrackingManager so tests can inject fakes.
+public protocol AttTrackerProtocol {
+    func currentStatus() -> AttStatus
+    func requestAuthorization(completion: @escaping (UInt) -> Void)
+}
+
+public final class DefaultAttTracker: AttTrackerProtocol {
+    public init() {}
+
+    public func currentStatus() -> AttStatus {
+        if #available(iOS 14, *) {
+            let raw = UInt(ATTrackingManager.trackingAuthorizationStatus.rawValue)
+            return AttStatus.from(authorizationRawValue: raw)
+        }
+        return .authorized // Pre-iOS 14 has no ATT, tracking implicitly allowed.
+    }
+
+    public func requestAuthorization(completion: @escaping (UInt) -> Void) {
+        if #available(iOS 14, *) {
+            ATTrackingManager.requestTrackingAuthorization { status in
+                completion(UInt(status.rawValue))
+            }
+        } else {
+            completion(3) // authorized
+        }
+    }
+}

package/ios/Sources/ApexCapacitorPlugin/DeepLinkManager.swift

@@ -0,0 +1,64 @@
+//
+//  DeepLinkManager.swift
+//  Apex Capacitor Plugin
+//
+//  Captures the URL that opens the app (Universal Link or custom scheme).
+//  Retains the cold-start URL so `getInitialDeepLink()` can return it after
+//  JS is ready. Warm-start URLs are delivered via Capacitor's `deepLink`
+//  notification bus.
+//
+//  Intentionally does no URL parsing — that's the server's job. This class
+//  only cares about preserving + forwarding the URL string.
+//
+
+import Foundation
+
+public final class DeepLinkManager {
+    private var initialUrl: URL?
+    private var warmHandler: ((URL) -> Void)?
+    private let queue = DispatchQueue(label: "inc.apex.deep-link")
+
+    public init() {}
+
+    /// Called from the AppDelegate when the app launches from a Universal Link
+    /// or custom URL scheme. Stored for retrieval via `consumeInitialUrl()`.
+    public func setInitialUrl(_ url: URL) {
+        queue.sync {
+            if initialUrl == nil {
+                initialUrl = url
+            }
+        }
+    }
+
+    /// Fetches and clears the cold-start URL. Returns nil if already consumed
+    /// or if the app was launched without a link.
+    public func consumeInitialUrl() -> URL? {
+        return queue.sync { () -> URL? in
+            let url = initialUrl
+            initialUrl = nil
+            return url
+        }
+    }
+
+    /// Called from continue(userActivity:) or open(url:) when the app is
+    /// already running. Dispatches to registered handler (typically the
+    /// Capacitor plugin which forwards to JS listeners).
+    public func deliverWarmLink(_ url: URL) {
+        queue.sync { warmHandler?(url) }
+    }
+
+    /// Register the warm-link handler. Only one handler at a time — replacing
+    /// overwrites the previous.
+    public func setWarmLinkHandler(_ handler: @escaping (URL) -> Void) {
+        queue.sync { warmHandler = handler }
+    }
+
+    /// Validates that a URL looks like a valid app deep link. Used to filter
+    /// spurious launches (e.g. when the app is opened from Spotlight with no
+    /// URL context).
+    public static func isValidDeepLink(_ url: URL) -> Bool {
+        guard let scheme = url.scheme, !scheme.isEmpty else { return false }
+        // https and custom schemes are both valid. file:// is not a deep link.
+        return scheme != "file"
+    }
+}

package/ios/Sources/ApexCapacitorPlugin/DeviceInfo.swift

@@ -0,0 +1,107 @@
+//
+//  DeviceInfo.swift
+//  Apex Capacitor Plugin
+//
+//  Collects device metadata reported on every event and to `getDeviceInfo()`.
+//  All values are pulled from UIDevice, Bundle, and Foundation — no PII,
+//  no identifiers, just platform/os/model/app/timezone/locale.
+//
+
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+public struct DeviceMetadata: Equatable {
+    public let platform: String        // "ios"
+    public let osVersion: String       // e.g. "17.4"
+    public let model: String           // e.g. "iPhone15,2" (machine identifier)
+    public let appVersion: String      // CFBundleShortVersionString
+    public let bundleId: String        // CFBundleIdentifier
+    public let timezone: String        // e.g. "America/New_York"
+    public let locale: String          // e.g. "en-US"
+
+    public init(
+        platform: String,
+        osVersion: String,
+        model: String,
+        appVersion: String,
+        bundleId: String,
+        timezone: String,
+        locale: String
+    ) {
+        self.platform = platform
+        self.osVersion = osVersion
+        self.model = model
+        self.appVersion = appVersion
+        self.bundleId = bundleId
+        self.timezone = timezone
+        self.locale = locale
+    }
+}
+
+public final class DeviceInfo {
+    private let bundle: Bundle
+    private let tzProvider: () -> String
+    private let localeProvider: () -> String
+    private let modelProvider: () -> String
+    private let osVersionProvider: () -> String
+
+    public init(
+        bundle: Bundle = .main,
+        tzProvider: @escaping () -> String = { TimeZone.current.identifier },
+        localeProvider: @escaping () -> String = { Locale.current.identifier.replacingOccurrences(of: "_", with: "-") },
+        modelProvider: @escaping () -> String = DeviceInfo.defaultModelProvider,
+        osVersionProvider: @escaping () -> String = DeviceInfo.defaultOsVersionProvider
+    ) {
+        self.bundle = bundle
+        self.tzProvider = tzProvider
+        self.localeProvider = localeProvider
+        self.modelProvider = modelProvider
+        self.osVersionProvider = osVersionProvider
+    }
+
+    public func collect() -> DeviceMetadata {
+        return DeviceMetadata(
+            platform: "ios",
+            osVersion: osVersionProvider(),
+            model: modelProvider(),
+            appVersion: appVersionFromBundle(),
+            bundleId: bundle.bundleIdentifier ?? "",
+            timezone: tzProvider(),
+            locale: localeProvider()
+        )
+    }
+
+    private func appVersionFromBundle() -> String {
+        let short = bundle.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "0.0.0"
+        return short
+    }
+
+    // MARK: - Default providers
+
+    public static var defaultModelProvider: () -> String = {
+        #if targetEnvironment(simulator)
+        return "iOSSimulator"
+        #else
+        var sysinfo = utsname()
+        uname(&sysinfo)
+        let mirror = Mirror(reflecting: sysinfo.machine)
+        var identifier = ""
+        for child in mirror.children {
+            if let value = child.value as? Int8, value != 0 {
+                identifier.append(Character(UnicodeScalar(UInt8(value))))
+            }
+        }
+        return identifier.isEmpty ? "iPhone" : identifier
+        #endif
+    }
+
+    public static var defaultOsVersionProvider: () -> String = {
+        #if canImport(UIKit)
+        return UIDevice.current.systemVersion
+        #else
+        return ProcessInfo.processInfo.operatingSystemVersionString
+        #endif
+    }
+}