@apex-inc/capacitor-plugin 0.3.8 → 2.1.0

package/android/src/main/java/inc/apex/capacitor/ApexFirebaseMessagingService.kt

@@ -0,0 +1,99 @@
+package inc.apex.capacitor
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import androidx.core.app.NotificationCompat
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
+
+/**
+ * FCM messaging service for Android push.
+ *
+ *   - `onNewToken`        — registers the (refreshed) device token with
+ *                           Apex via `ApexCapacitorPlugin.registerTokenFromService`.
+ *   - `onMessageReceived` — for foreground/data messages, posts a system
+ *                           notification whose tap PendingIntent re-opens
+ *                           the launcher activity carrying the apex push
+ *                           data (`apex_url`, `apex_messageId`,
+ *                           `apex_apexToken`) as extras. The plugin reads
+ *                           those on launch and fires `pushClicked`, which
+ *                           the app uses to report engagement + route.
+ *
+ * For background "notification" messages the system tray renders the
+ * banner directly and FCM copies the `data` bag into the launcher
+ * intent extras on tap — same `apex_*` keys, same plugin handling.
+ */
+class ApexFirebaseMessagingService : FirebaseMessagingService() {
+
+    override fun onNewToken(token: String) {
+        super.onNewToken(token)
+        try {
+            ApexCapacitorPlugin.registerTokenFromService(applicationContext, token)
+        } catch (_: Throwable) {
+            // best-effort — a registration failure must not crash the service
+        }
+    }
+
+    override fun onMessageReceived(message: RemoteMessage) {
+        super.onMessageReceived(message)
+        val data = message.data
+        val title = message.notification?.title ?: data["title"] ?: "Notification"
+        val body = message.notification?.body ?: data["body"] ?: ""
+
+        val launch = packageManager.getLaunchIntentForPackage(packageName)
+        if (launch != null) {
+            launch.flags =
+                Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+            data["url"]?.let { launch.putExtra("apex_url", it) }
+            data["messageId"]?.let { launch.putExtra("apex_messageId", it) }
+            data["apexToken"]?.let { launch.putExtra("apex_apexToken", it) }
+        }
+
+        val flags =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+                PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+            } else {
+                PendingIntent.FLAG_UPDATE_CURRENT
+            }
+        val contentIntent =
+            launch?.let {
+                PendingIntent.getActivity(this, message.messageId?.hashCode() ?: 0, it, flags)
+            }
+
+        ensureChannel()
+        val notification = NotificationCompat.Builder(this, CHANNEL_ID)
+            .setContentTitle(title)
+            .setContentText(body)
+            .setSmallIcon(applicationInfo.icon)
+            .setAutoCancel(true)
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+            .apply { if (contentIntent != null) setContentIntent(contentIntent) }
+            .build()
+
+        val mgr = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        mgr.notify(message.messageId?.hashCode() ?: System.currentTimeMillis().toInt(), notification)
+    }
+
+    private fun ensureChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val mgr = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            if (mgr.getNotificationChannel(CHANNEL_ID) == null) {
+                mgr.createNotificationChannel(
+                    NotificationChannel(
+                        CHANNEL_ID,
+                        "Notifications",
+                        NotificationManager.IMPORTANCE_HIGH,
+                    ),
+                )
+            }
+        }
+    }
+
+    companion object {
+        private const val CHANNEL_ID = "apex_default"
+    }
+}

package/android/src/main/java/inc/apex/capacitor/NativeBatchSender.kt

@@ -0,0 +1,260 @@
+package inc.apex.capacitor
+
+import org.json.JSONArray
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.concurrent.Executor
+import java.util.concurrent.Executors
+
+/**
+ * MMP-215 — Drains [NativeOfflineQueue] by POSTing batches of events to
+ * `${apiBaseUrl}/api/events`. Mirrors the iOS `BatchSender.swift` so the
+ * on-disk Android queue isn't stranded.
+ *
+ * Before this class shipped, `flushQueue()` on Android was a no-op —
+ * `track()` enqueued to the native file-backed queue and nothing ever
+ * drained it, so any event captured while the Capacitor webview wasn't
+ * mounted was lost forever. iOS shipped its sender in MMP-205; this is
+ * the parity port.
+ *
+ * Concurrency model:
+ *  - Serial single-threaded executor gates send attempts so two flushes
+ *    don't race over the same batch (parity with Swift's serial
+ *    DispatchQueue).
+ *  - HTTP is synchronous via `HttpURLConnection` (no OkHttp / coroutines
+ *    dep — keeps APK delta small). The whole drain runs on the executor.
+ *  - Retry backoff sleeps on the executor thread; since callers fire
+ *    `flush()` and observe via the completion callback, blocking the
+ *    serial thread for a retry doesn't surface as a UI freeze.
+ */
+class NativeBatchSender(
+    apiBaseUrl: String,
+    private val projectKey: String,
+    private val platformHeader: String = "android",
+    private val apiKey: String? = null,
+    batchSize: Int = 50,
+    maxRetries: Int = 3,
+    baseBackoffMs: Long = 1000L,
+    private val debug: Boolean = false,
+    private val httpClient: HttpClient = DefaultHttpClient(),
+    private val executor: Executor = Executors.newSingleThreadExecutor { r ->
+        Thread(r, "inc.apex.batch-sender").apply { isDaemon = true }
+    },
+    private val sleeper: (Long) -> Unit = { ms -> Thread.sleep(ms) },
+) {
+
+    private val apiBaseUrl: String = apiBaseUrl.trimEnd('/')
+    private val batchSize: Int = maxOf(1, batchSize)
+    private val maxRetries: Int = maxOf(1, maxRetries)
+    private val baseBackoffMs: Long = maxOf(0L, baseBackoffMs)
+
+    @Volatile
+    private var inFlight: Boolean = false
+    private val inFlightLock = Any()
+
+    /**
+     * Drains the queue, one batch at a time, with exponential backoff on
+     * retryable failures. Safe to call concurrently — only one flush runs
+     * at a time; concurrent callers receive `(0, currentSize)` and the
+     * in-flight drain keeps going.
+     *
+     * @param callback fires exactly once with (flushed, remaining).
+     */
+    fun flush(queue: NativeOfflineQueue, callback: (flushed: Int, remaining: Int) -> Unit) {
+        executor.execute {
+            synchronized(inFlightLock) {
+                if (inFlight) {
+                    if (debug) log("flush called while drain in flight — no-op")
+                    callback(0, queue.size())
+                    return@execute
+                }
+                inFlight = true
+            }
+            val flushed = try {
+                drainLoop(queue, accumulated = 0)
+            } catch (t: Throwable) {
+                if (debug) log("drainLoop unexpected throw: ${t.message}")
+                0
+            } finally {
+                synchronized(inFlightLock) { inFlight = false }
+            }
+            callback(flushed, queue.size())
+        }
+    }
+
+    /**
+     * Recursive drain. Returns the running total of successfully flushed
+     * events. Stops at the first non-retryable error or exhausted retry.
+     */
+    private fun drainLoop(queue: NativeOfflineQueue, accumulated: Int): Int {
+        val batch = try {
+            queue.peek(batchSize)
+        } catch (e: Exception) {
+            if (debug) log("peek failed: ${e.message}")
+            return accumulated
+        }
+        if (batch.isEmpty()) return accumulated
+
+        return when (val outcome = sendBatchWithRetry(batch, attempt = 0)) {
+            SendOutcome.Success -> {
+                queue.markSent(batch.map { it.id })
+                if (debug) log("flushed batch of ${batch.size}")
+                drainLoop(queue, accumulated + batch.size)
+            }
+            is SendOutcome.NonRetryable -> {
+                if (debug) log("non-retryable HTTP ${outcome.statusCode}; leaving events queued")
+                accumulated
+            }
+            is SendOutcome.RetryableExhausted -> {
+                queue.markFailed(batch.map { it.id })
+                if (debug) log("retries exhausted: ${outcome.errorMessage}")
+                accumulated
+            }
+        }
+    }
+
+    private fun sendBatchWithRetry(
+        batch: List<NativeQueuedEvent>,
+        attempt: Int,
+    ): SendOutcome {
+        if (batch.isEmpty()) return SendOutcome.Success
+
+        val url = "$apiBaseUrl/api/events"
+        val body = buildRequestBody(batch)
+        val headers = mutableMapOf(
+            "Content-Type" to "application/json",
+            "X-Apex-Project-Key" to projectKey,
+            "X-Apex-Platform" to platformHeader,
+        )
+        apiKey?.let { headers["x-apex-api-key"] = it }
+
+        if (debug) log("POST $url (${batch.size} events, attempt ${attempt + 1}/$maxRetries)")
+
+        val response = try {
+            httpClient.send(url, headers, body, timeoutMs = 20_000)
+        } catch (e: Exception) {
+            return retryOrFail(batch, attempt, e.message ?: "network error")
+        }
+
+        return when {
+            response.statusCode in 200..299 -> SendOutcome.Success
+            response.statusCode in 400..499 ->
+                // Client error — don't retry; events stay queued for
+                // inspection but we stop hammering the server.
+                SendOutcome.NonRetryable(response.statusCode)
+            else ->
+                retryOrFail(
+                    batch,
+                    attempt,
+                    response.errorMessage ?: "HTTP ${response.statusCode}",
+                )
+        }
+    }
+
+    private fun retryOrFail(
+        batch: List<NativeQueuedEvent>,
+        attempt: Int,
+        errorMessage: String,
+    ): SendOutcome {
+        if (attempt + 1 >= maxRetries) {
+            return SendOutcome.RetryableExhausted(errorMessage)
+        }
+        val backoffMs = baseBackoffMs shl attempt
+        if (debug) log("retry in ${backoffMs}ms ($errorMessage)")
+        sleeper(backoffMs)
+        return sendBatchWithRetry(batch, attempt + 1)
+    }
+
+    private fun buildRequestBody(batch: List<NativeQueuedEvent>): ByteArray {
+        // Server accepts `{ projectKey, events: [{ id, ...payload }] }`.
+        // Unwrap the queued envelope so `id` lives at the top level of
+        // each event (matches /api/events expectations and the JS-side
+        // BatchSender shape).
+        //
+        // MMP-081 — stamp `clientType="native-android"` if the queued
+        // payload didn't already carry one (caller-supplied values win,
+        // which preserves test fixtures and unusual workflows).
+        val eventsArray = JSONArray()
+        for (event in batch) {
+            val flat = JSONObject(event.payload.toMap())
+            flat.put("id", event.id)
+            if (!flat.has("clientType") || flat.isNull("clientType")) {
+                flat.put("clientType", "native-android")
+            }
+            eventsArray.put(flat)
+        }
+        val payload = JSONObject()
+            .put("projectKey", projectKey)
+            .put("events", eventsArray)
+        return payload.toString().toByteArray(Charsets.UTF_8)
+    }
+
+    private fun log(msg: String) {
+        println("[apex-capacitor] $msg")
+    }
+
+    // ── Result types ──────────────────────────────────────────────────
+
+    sealed class SendOutcome {
+        object Success : SendOutcome()
+        data class NonRetryable(val statusCode: Int) : SendOutcome()
+        data class RetryableExhausted(val errorMessage: String) : SendOutcome()
+    }
+
+    // ── HTTP abstraction (test-swappable) ─────────────────────────────
+
+    /**
+     * Minimal HTTP transport. Tests inject a fake; production uses
+     * [DefaultHttpClient]. Synchronous by design — the caller is already
+     * on the executor thread.
+     */
+    interface HttpClient {
+        fun send(
+            url: String,
+            headers: Map<String, String>,
+            body: ByteArray,
+            timeoutMs: Int,
+        ): HttpResponse
+    }
+
+    data class HttpResponse(
+        val statusCode: Int,
+        val errorMessage: String? = null,
+    )
+
+    /**
+     * Production HTTP client. Uses [HttpURLConnection] — same approach
+     * as the rest of the plugin (no OkHttp dependency).
+     */
+    class DefaultHttpClient : HttpClient {
+        override fun send(
+            url: String,
+            headers: Map<String, String>,
+            body: ByteArray,
+            timeoutMs: Int,
+        ): HttpResponse {
+            val conn = (URL(url).openConnection() as HttpURLConnection).apply {
+                requestMethod = "POST"
+                doOutput = true
+                connectTimeout = timeoutMs
+                readTimeout = timeoutMs
+                useCaches = false
+                for ((k, v) in headers) setRequestProperty(k, v)
+            }
+            try {
+                conn.outputStream.use { it.write(body) }
+                val code = conn.responseCode
+                return HttpResponse(statusCode = code)
+            } catch (e: Exception) {
+                return HttpResponse(statusCode = 0, errorMessage = e.message ?: "io error")
+            } finally {
+                try {
+                    conn.disconnect()
+                } catch (_: Exception) {
+                    // best-effort
+                }
+            }
+        }
+    }
+}

package/dist/batch-sender.d.ts

@@ -16,6 +16,12 @@ export interface BatchSenderOptions {
     apiUrl?: string;
     /** Project key attached to each request. Required. */
     projectKey: string;
+    /**
+     * Optional workspace-bound SDK key (`apex_uk_*` / `apex_sk_*`).
+     * Forwarded as `x-apex-api-key` on every batch so the server can
+     * authorize quarantine-mode auto-stitch.
+     */
+    apiKey?: string;
     /** Max events sent per batch. Default 50. */
     batchSize?: number;
     /** Max retry attempts before giving up on a batch. Default 3. */
@@ -40,6 +46,7 @@ export interface FlushResult {
 export declare class BatchSender {
     private readonly apiUrl;
     private readonly projectKey;
+    private readonly apiKey?;
     /** Exposed for callers (e.g. getVariant) that need to address the same server. */
     getApiUrl(): string;
     private readonly batchSize;
@@ -54,6 +61,11 @@ export declare class BatchSender {
      * Flushes as many events from the queue as possible, one batch at a time,
      * with exponential backoff on retryable failures. Stops early on
      * non-retryable errors (400/401/403) and leaves remaining events queued.
+     *
+     * MOBX-005 (post-mortem #5) — every flush starts with queue hygiene:
+     * events older than 7 days or with more than 20 failed delivery
+     * attempts are evicted so a poisoned head can never block fresh
+     * events indefinitely.
      */
     flush(queue: OfflineQueue): Promise<FlushResult>;
     private sendBatchWithRetry;

package/dist/batch-sender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch-sender.d.ts","sourceRoot":"","sources":["../src/batch-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,sDAAsD;IACtD,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;IAC3C,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,kFAAkF;IAClF,SAAS,IAAI,MAAM;IAInB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAA4B;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,EAAE,kBAAkB;IAiBvC;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;YAgCxC,kBAAkB;YAyClB,SAAS;CAoBxB"}
+{"version":3,"file":"batch-sender.d.ts","sourceRoot":"","sources":["../src/batch-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,sDAAsD;IACtD,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;IAC3C,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IAEjC,kFAAkF;IAClF,SAAS,IAAI,MAAM;IAInB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAA4B;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,EAAE,kBAAkB;IAkBvC;;;;;;;;;OASG;IACG,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;YA8CxC,kBAAkB;YAyClB,SAAS;CA2BxB"}

package/dist/batch-sender.js

@@ -21,6 +21,7 @@ class BatchSender {
     constructor(options) {
         this.apiUrl = (options.apiUrl ?? "https://api.apex.inc").replace(/\/+$/, "");
         this.projectKey = options.projectKey;
+        this.apiKey = options.apiKey;
         this.batchSize = options.batchSize ?? 50;
         this.maxRetries = options.maxRetries ?? 3;
         this.baseBackoffMs = options.baseBackoffMs ?? 1000;
@@ -37,11 +38,28 @@ class BatchSender {
      * Flushes as many events from the queue as possible, one batch at a time,
      * with exponential backoff on retryable failures. Stops early on
      * non-retryable errors (400/401/403) and leaves remaining events queued.
+     *
+     * MOBX-005 (post-mortem #5) — every flush starts with queue hygiene:
+     * events older than 7 days or with more than 20 failed delivery
+     * attempts are evicted so a poisoned head can never block fresh
+     * events indefinitely.
      */
     async flush(queue) {
         let flushed = 0;
         let attemptedBatches = 0;
         let lastError;
+        try {
+            const evicted = await queue.evictStale({
+                maxAttempts: 20,
+                maxAgeMs: 7 * 24 * 60 * 60 * 1000,
+            });
+            if (evicted > 0 && this.debug) {
+                console.warn(`[apex-capacitor] evicted ${evicted} stale event(s) from the offline queue (TTL 7d / 20 attempts)`);
+            }
+        }
+        catch {
+            /* hygiene is best-effort — never block the flush */
+        }
         while (true) {
             const batch = await queue.peek(this.batchSize);
             if (batch.length === 0)
@@ -108,6 +126,13 @@ class BatchSender {
         if (this.platformHeader) {
             headers["X-Apex-Platform"] = this.platformHeader;
         }
+        if (this.apiKey) {
+            // Phase 2-quarantine — workspace-bound SDK key. The server uses
+            // this to authorize auto-stitch on `user_signed_up` /
+            // `user_identified`. Missing key means events still flow but
+            // auto-stitch is suppressed (the fail-closed default).
+            headers["x-apex-api-key"] = this.apiKey;
+        }
         return this.fetchFn(`${this.apiUrl}/api/events`, {
             method: "POST",
             headers,

package/dist/batch-sender.js.map

@@ -1 +1 @@
-{"version":3,"file":"batch-sender.js","sourceRoot":"","sources":["../src/batch-sender.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"batch-sender.js","sourceRoot":"","sources":["../src/batch-sender.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAsCH,MAAa,WAAW;IAKtB,kFAAkF;IAClF,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAUD,YAAY,OAA2B;QACrC,IAAI,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,sBAAsB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC7E,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;QACnD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAK,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAkB,CAAC;QACvF,IAAI,CAAC,OAAO;YACV,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACnF,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QAEpC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,KAAmB;QAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,gBAAgB,GAAG,CAAC,CAAC;QACzB,IAAI,SAA6B,CAAC;QAElC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC;gBACrC,WAAW,EAAE,EAAE;gBACf,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;aAClC,CAAC,CAAC;YACH,IAAI,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC9B,OAAO,CAAC,IAAI,CACV,4BAA4B,OAAO,+DAA+D,CACnG,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;QAED,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM;YAC9B,gBAAgB,IAAI,CAAC,CAAC;YAEtB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAErD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACjF,MAAM,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAC/B,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;YAC1B,CAAC;iBAAM,IAAI,OAAO,CAAC,MAAM,KAAK,qBAAqB,EAAE,CAAC;gBACpD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACjF,MAAM,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBACjC,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;gBAC1B,MAAM,CAAC,6BAA6B;YACtC,CAAC;iBAAM,CAAC;gBACN,0DAA0D;gBAC1D,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;gBAC1B,MAAM;YACR,CAAC;QACH,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC7D,CAAC;IAEO,KAAK,CAAC,kBAAkB,CAC9B,KAAoB;QAMpB,IAAI,SAAS,GAAG,SAAS,CAAC;QAC1B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YAC3D,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBAE7C,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;oBAChB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAC/B,CAAC;gBAED,iEAAiE;gBACjE,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;oBACpD,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;gBACvE,CAAC;gBAED,sDAAsD;gBACtD,SAAS,GAAG,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,SAAS,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/D,CAAC;YAED,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,GAAG,CAAC,IAAI,OAAO,CAAC;gBAClD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,GAAG,CACT,uCAAuC,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,OAAO,OAAO,OAAO,SAAS,GAAG,CAC3G,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC7D,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,KAAoB;QAC1C,MAAM,IAAI,GAAG;YACX,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SAClC,CAAC;QAEF,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,oBAAoB,EAAE,IAAI,CAAC,UAAU;SACtC,CAAC;QACF,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC;QACnD,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,gEAAgE;YAChE,sDAAsD;YACtD,6DAA6D;YAC7D,uDAAuD;YACvD,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1C,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,aAAa,EAAE;YAC/C,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;CACF;AAhKD,kCAgKC"}

package/dist/cart-helpers.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Journey Exit Semantics — SDK catch-up.
+ *
+ * Typed cart helpers. Operators who reach for "track an add-to-cart"
+ * with the raw `Apex.track({ type: "add_to_cart", data: { ... } })`
+ * have to invent the data shape — which means the server-side cart
+ * rollup writer (Phase 2) reads inconsistent SKUs/qtys/IDs and the
+ * `Contact.cart` state drifts.
+ *
+ * These helpers emit the canonical shape the rollup expects so
+ * branches on `cart.itemCount` / `cart.valueCents` light up
+ * automatically with zero downstream configuration.
+ *
+ * All helpers delegate to `Apex.track()` so the existing offline
+ * queue / batch-sender / session-manager paths stay unchanged.
+ */
+/**
+ * Canonical line shape consumed by the server-side cart rollup. Mirrors
+ * the same interface in `@apex-inc/sdk` for documentation parity.
+ */
+export interface CartLine {
+    /** Merchant SKU. Required for stable identity. */
+    sku: string;
+    /** Items in the line. Negative deltas clamp at 0 server-side. */
+    qty: number;
+    priceCents?: number;
+    currency?: string;
+    /** Display name for the Contact-drawer rendering. */
+    name?: string;
+    /**
+     * Stable line identifier when one SKU can have multiple cart lines
+     * (e.g. configurable products with different variants). Defaults
+     * to `sku` server-side when omitted.
+     */
+    stableLineId?: string;
+}
+/** Add an item to the cart. */
+export declare function trackCartAdd(line: CartLine): Promise<void>;
+/** Remove an item from the cart. */
+export declare function trackCartRemove(opts: {
+    sku: string;
+    qty: number;
+    stableLineId?: string;
+    cartValueCents?: number;
+    currency?: string;
+}): Promise<void>;
+/**
+ * Full-cart reconciliation. Use whenever the app loads the source-of-
+ * truth cart (login restore, foreground refresh, cart screen mount).
+ * The rollup writer replaces stored lines wholesale on this event,
+ * which heals drift caused by missed add/remove deltas.
+ */
+export declare function trackCartSnapshot(opts: {
+    lines: CartLine[];
+    currency?: string;
+}): Promise<void>;
+/** Clear the cart on successful checkout. */
+export declare function trackCheckoutCompleted(opts: {
+    orderId: string;
+    totalCents: number;
+    currency?: string;
+}): Promise<void>;
+//# sourceMappingURL=cart-helpers.d.ts.map

package/dist/cart-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart-helpers.d.ts","sourceRoot":"","sources":["../src/cart-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,+BAA+B;AAC/B,wBAAsB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED,oCAAoC;AACpC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhB;AAED,6CAA6C;AAC7C,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB"}

package/dist/cart-helpers.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Journey Exit Semantics — SDK catch-up.
+ *
+ * Typed cart helpers. Operators who reach for "track an add-to-cart"
+ * with the raw `Apex.track({ type: "add_to_cart", data: { ... } })`
+ * have to invent the data shape — which means the server-side cart
+ * rollup writer (Phase 2) reads inconsistent SKUs/qtys/IDs and the
+ * `Contact.cart` state drifts.
+ *
+ * These helpers emit the canonical shape the rollup expects so
+ * branches on `cart.itemCount` / `cart.valueCents` light up
+ * automatically with zero downstream configuration.
+ *
+ * All helpers delegate to `Apex.track()` so the existing offline
+ * queue / batch-sender / session-manager paths stay unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackCartAdd = trackCartAdd;
+exports.trackCartRemove = trackCartRemove;
+exports.trackCartSnapshot = trackCartSnapshot;
+exports.trackCheckoutCompleted = trackCheckoutCompleted;
+const index_1 = require("./index");
+const events_1 = require("./events");
+/** Add an item to the cart. */
+async function trackCartAdd(line) {
+    await index_1.Apex.track({ type: events_1.ApexEvents.AddToCart, data: { ...line } });
+}
+/** Remove an item from the cart. */
+async function trackCartRemove(opts) {
+    await index_1.Apex.track({ type: events_1.ApexEvents.RemoveFromCart, data: { ...opts } });
+}
+/**
+ * Full-cart reconciliation. Use whenever the app loads the source-of-
+ * truth cart (login restore, foreground refresh, cart screen mount).
+ * The rollup writer replaces stored lines wholesale on this event,
+ * which heals drift caused by missed add/remove deltas.
+ */
+async function trackCartSnapshot(opts) {
+    // `cart_snapshot` isn't in the published ApexEvents enum yet (it's
+    // a Phase-2 addition). Passing the canonical string lets older
+    // plugin versions still emit it cleanly; the server route accepts
+    // arbitrary string event types.
+    await index_1.Apex.track({ type: "cart_snapshot", data: { ...opts } });
+}
+/** Clear the cart on successful checkout. */
+async function trackCheckoutCompleted(opts) {
+    await index_1.Apex.track({ type: "checkout_completed", data: { ...opts } });
+}
+//# sourceMappingURL=cart-helpers.js.map

package/dist/cart-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart-helpers.js","sourceRoot":"","sources":["../src/cart-helpers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AA2BH,oCAEC;AAGD,0CAQC;AAQD,8CASC;AAGD,wDAMC;AAhED,mCAA+B;AAC/B,qCAAsC;AAuBtC,+BAA+B;AACxB,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,MAAM,YAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,mBAAU,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,oCAAoC;AAC7B,KAAK,UAAU,eAAe,CAAC,IAMrC;IACC,MAAM,YAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,mBAAU,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,iBAAiB,CAAC,IAGvC;IACC,mEAAmE;IACnE,+DAA+D;IAC/D,kEAAkE;IAClE,gCAAgC;IAChC,MAAM,YAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,6CAA6C;AACtC,KAAK,UAAU,sBAAsB,CAAC,IAI5C;IACC,MAAM,YAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}