@apex-inc/capacitor-plugin 2.4.1 → 2.5.1

package/README.md

@@ -4,7 +4,7 @@ Apex Capacitor plugin — iOS and Android attribution, events, deep linking, SKA
 
 Ships alongside `apex.js` (the web snippet) so a Capacitor app gets unified identity and events across WebView + native APIs with one dependency pattern.
 
-> **Scope.** This plugin is for Capacitor apps. Native iOS (Swift), native Android (Kotlin), React Native, and Flutter apps need their own SDKs — see https://apex.inc/docs/mobile/which-sdk.
+> **Scope.** This plugin is for Capacitor apps. Native iOS (Swift), native Android (Kotlin), React Native, and Flutter apps need their own SDKs — see https://app.apex.inc/docs/mobile/which-sdk.
 
 > **Try it in 5 minutes.** The [sample app](https://github.com/apex-incorporated/capacitor-sample-app) is a three-screen Capacitor + React app that exercises every API in this plugin. `git clone`, `npm install`, `npm run dev`, watch events land in your Apex dashboard.
 
@@ -25,9 +25,10 @@ import { Apex } from "@apex-inc/capacitor-plugin";
 await Apex.initialize({
   workspaceKey: "prj_your_key",
   // Optional:
-  // apiKey: "apex_sk_…",       // see "API keys" below — unlocks verified identity stitching
+  // apiKey: "apex_pk_…", // app key only; see "API keys" below
   // apiUrl: "https://app.apex.inc",
   // autoTrackScreenViews: true, // default — screen_view auto-fires from SPA navigation
+  // autoConversionValues: true, // default — Apex drives SKAdNetwork values from Set up Apex (iOS)
   // sessionTimeoutMinutes: 30,
   // offlineQueueMaxSize: 1000,
   // testMode: false,
@@ -45,15 +46,30 @@ into your router instead.
 
 ### API keys
 
-`identify()` and server-trusted flows work best with a workspace SDK key
-(`apex_sk_…`). Mint one in the Apex dashboard under **Settings →
-Workspace → AI agents & API keys**, and pass it as `apiKey` in
-`initialize()`. Without a key, identity stitches from untrusted contexts
-may be quarantined (held un-verified) rather than applied — events still
-flow, but traits and journey triggers wait until a verified stitch.
-Treat the value like a publishable key: assume it can be extracted from
-the app bundle; Apex rate-limits per key + per visitor to keep leaked
-keys low-yield.
+Use an app key (`apex_pk_…`). Make one under Settings, Organization, API
+keys with the **App key** preset. It is safe to ship: it gives your app its
+own rate limit and lets a sign-up add a new person, but it never changes a
+person already in Apex, never counts revenue, and never sends anything to
+your ad platforms.
+
+Do not put a server key (`apex_sk_…`) or a personal key (`apex_uk_…`) in
+your app. Anyone can unpack an app and read the key, and either one lets
+them send purchases Apex counts as revenue and passes to your ad
+platforms. Send purchases from your server with a server key and the
+[Server Events API](https://app.apex.inc/docs/api/server-events), or
+connect the App Store or Google Play.
+
+### Signed sign-ins
+
+To attach a sign-in to someone already in Apex, have your server sign the
+email with your workspace's sign-in secret and pass the result as
+`userHash`:
+
+```ts
+await Apex.identify({ email, userHash }); // userHash comes from your backend
+```
+
+See [Signed sign-ins](https://app.apex.inc/docs/identity/signed-sign-ins).
 
 ## Track events
 
@@ -163,25 +179,61 @@ if (!id && fallback === "idfv") {
 
 ## SKAdNetwork conversion values (iOS 4.0+)
 
+You do not have to write this code. In the Apex dashboard, **Set up Apex →
+Mobile → Say what Apple's numbers mean** asks one question (which event
+means an install was worth it) and turns it into the full table of what
+Apple's 0–63 values mean for your app. With `autoConversionValues` on
+(the default on iOS), the plugin:
+
+- fetches that table on `initialize()`, caches it for a day, and
+  revalidates by ETag;
+- calls `SKAdNetwork.updatePostbackConversionValue` whenever `track()`
+  sees an event in the table, in the postback window the install is in;
+- only ever moves the value up within a window, and stops after day 35
+  when Apple stops listening.
+
+With `debug: true` every decision is logged as
+`[apex-capacitor] skan updatePostbackConversionValue(32, high) for purchase in window 1`.
+
+Read the table the plugin is acting on:
+
+```ts
+const { schema, mobileAppId, fetchedAt } = await Apex.getConversionValueSchema();
+```
+
+If you would rather run your own ladder, call `updateConversionValue`
+yourself. The first manual call turns automatic values off for that
+install — manual always wins — or pass `autoConversionValues: false` at
+`initialize()`.
+
 ```ts
 await Apex.updateConversionValue({
   fineValue: 42,
   coarseValue: "high",
+  lockWindow: false, // true asks Apple to send this window's postback now
 });
 ```
 
+Android has no SKAdNetwork; both calls are no-ops there.
+
 ## Deep links
 
 ```ts
 // Cold start: read the URL that opened the app (if any).
-const { url } = await Apex.getInitialDeepLink();
+const { url, deepLinkHint } = await Apex.getInitialDeepLink();
 
 // Warm-start / subsequent links while running:
-await Apex.addListener("deepLink", ({ url }) => {
-  handleRoute(url);
+await Apex.addListener("deepLink", ({ url, deepLinkHint }) => {
+  handleRoute(url, deepLinkHint);
 });
 ```
 
+`deepLinkHint` is the value the merchant set on the Apex Link (`apex_dl` on the
+URL), handed over already parsed. It's null when the link didn't carry one. Use
+it when your in-app routes don't look like your web routes — the link can say
+`checkout` and your router can honor that without parsing a web path it doesn't
+recognize. Apex never interprets the value.
+
 ## Sessions
 
 ```ts

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

@@ -4,6 +4,8 @@ import android.content.Context
 import android.content.SharedPreferences
 import android.net.Uri
 import android.os.Build
+import android.os.Handler
+import android.os.Looper
 import android.provider.Settings
 import com.android.installreferrer.api.InstallReferrerClient
 import com.android.installreferrer.api.InstallReferrerStateListener
@@ -50,11 +52,24 @@ class ApexCapacitorPlugin : Plugin() {
 
     private var offlineQueue: NativeOfflineQueue? = null
     private var batchSender: NativeBatchSender? = null
+    private val flushHandler = Handler(Looper.getMainLooper())
+    private var flushTimer: Runnable? = null
+    private var pendingTrackFlush: Runnable? = null
     private var prefs: SharedPreferences? = null
     private var visitorId: String = ""
     private var testMode: Boolean = false
     private var debug: Boolean = false
     private var lastInstallReferrer: String? = null
+
+    // Deferred deep linking. The Play referrer is the ONLY thing that
+    // survives the browser-tap → store → first-launch gap on Android, so
+    // `getInstallReferrer` has to be able to answer during first launch
+    // rather than returning null because the Play service hasn't
+    // connected yet. Calls that arrive before the fetch completes are
+    // parked and flushed by the listener.
+    private var installReferrerResolved: Boolean = false
+    private var installReferrerClickSeconds: Long = 0
+    private val pendingReferrerCalls = mutableListOf<PluginCall>()
     // Phase 2-SDK — workspace-bound SDK key forwarded as
     // `x-apex-api-key` on every event POST + on `identify()`.
     private var apiKey: String? = null
@@ -83,7 +98,9 @@ class ApexCapacitorPlugin : Plugin() {
             }
 
         deepLinks.setWarmLinkHandler { url ->
-            val data = JSObject().put("url", url)
+            val data = JSObject()
+                .put("url", url)
+                .put("deepLinkHint", DeepLinkManager.apexHint(url) ?: JSONObject.NULL)
             notifyListeners("deepLink", data)
         }
 
@@ -156,6 +173,8 @@ class ApexCapacitorPlugin : Plugin() {
             apiKey = apiKey,
             debug = debug,
         )
+        scheduleFlushTimer()
+        kickFlush("initialize")
 
         // MMP-061 — release channel detection. Unlike iOS, Play doesn't
         // surface internal/closed/open tracks at the device level
@@ -383,8 +402,20 @@ class ApexCapacitorPlugin : Plugin() {
 
     @PluginMethod
     fun getInstallReferrer(call: PluginCall) {
-        val data = JSObject().put("referrer", lastInstallReferrer ?: JSONObject.NULL)
-        call.resolve(data)
+        if (installReferrerResolved) {
+            resolveInstallReferrer(call)
+            return
+        }
+        // Park the call until the Play service answers. Bounded, because
+        // first launch is the most latency-sensitive moment in the app's
+        // life and a wedged Play service must never hold up a screen.
+        synchronized(pendingReferrerCalls) { pendingReferrerCalls.add(call) }
+        Handler(Looper.getMainLooper()).postDelayed({
+            val stillPending = synchronized(pendingReferrerCalls) {
+                pendingReferrerCalls.remove(call)
+            }
+            if (stillPending) resolveInstallReferrer(call)
+        }, REFERRER_WAIT_MS)
     }
 
     @PluginMethod
@@ -442,6 +473,10 @@ class ApexCapacitorPlugin : Plugin() {
         if (traits != null) {
             payload.put("metadata", traits)
         }
+        val userHash = call.getString("userHash")
+        if (!userHash.isNullOrEmpty()) {
+            payload.put("userHash", userHash)
+        }
 
         Thread {
             try {
@@ -709,6 +744,7 @@ class ApexCapacitorPlugin : Plugin() {
                 conn.setRequestProperty("x-apex-source", "sdk")
                 conn.setRequestProperty("x-apex-visitor-id", visitorId)
                 conn.setRequestProperty("x-apex-workspace", workspaceKey)
+                conn.setRequestProperty("x-apex-release-channel", releaseChannel)
                 apiKey?.let { conn.setRequestProperty("x-apex-api-key", it) }
                 conn.connectTimeout = 10000
                 conn.readTimeout = 15000
@@ -755,17 +791,23 @@ class ApexCapacitorPlugin : Plugin() {
      */
     private fun enqueueExposure(experimentId: String, variant: String) {
         val queue = offlineQueue ?: return
+        // App version that saw the variant — the mobile equivalent of the web
+        // build id. Enables version-adoption curves + version-gating during a
+        // staged rollout (Phase 5, 2026-07-20).
+        val appVersion = try {
+            context.packageManager.getPackageInfo(context.packageName, 0).versionName ?: "0.0.0"
+        } catch (_: Exception) {
+            "0.0.0"
+        }
         val payload = mutableMapOf<String, Any?>()
         payload["type"] = "experiment_exposure"
         payload["data"] = mapOf(
             "experiment_id" to experimentId,
             "variant_key" to variant,
             "surface" to "mobile",
+            "app_version" to appVersion,
         )
-        if (testMode) payload["testMode"] = true
-        payload["platform"] = "android"
-        payload["timestamp"] = java.time.Instant.now().toString()
-        payload["visitorId"] = visitorId
+        TrackStamps.apply(payload, visitorId, testMode, java.time.Instant.now().toString())
         payload["clientType"] = "native-android"
         payload["mobile"] = mutableMapOf<String, Any?>(
             "releaseChannel" to releaseChannel,
@@ -779,7 +821,7 @@ class ApexCapacitorPlugin : Plugin() {
         )
         try {
             queue.enqueue(event)
-            batchSender?.flush(queue) { _, _ -> }
+            kickFlush("track")
         } catch (e: Exception) {
             if (debug) println("[apex-capacitor] exposure enqueue failed: ${e.message}")
         }
@@ -796,7 +838,10 @@ class ApexCapacitorPlugin : Plugin() {
     @PluginMethod
     fun getInitialDeepLink(call: PluginCall) {
         val url = deepLinks.consumeInitialUrl()
-        val data = JSObject().put("url", url ?: JSONObject.NULL)
+        val hint = url?.let { DeepLinkManager.apexHint(it) }
+        val data = JSObject()
+            .put("url", url ?: JSONObject.NULL)
+            .put("deepLinkHint", hint ?: JSONObject.NULL)
         call.resolve(data)
     }
 
@@ -871,6 +916,7 @@ class ApexCapacitorPlugin : Plugin() {
         val id = call.getString("id") ?: UUID.randomUUID().toString().lowercase()
         val payload = mutableMapOf<String, Any?>()
         call.data.keys().forEach { key -> payload[key] = call.data.opt(key) }
+        TrackStamps.apply(payload, visitorId, testMode, java.time.Instant.now().toString())
 
         // MMP-061 — stamp release channel under event.mobile so the
         // server's TrackingEvent shape lands the field in the right
@@ -907,6 +953,7 @@ class ApexCapacitorPlugin : Plugin() {
         )
         try {
             queue.enqueue(event)
+            kickFlush("track")
             call.resolve()
         } catch (e: Exception) {
             call.reject("Failed to enqueue event: ${e.message}")
@@ -962,11 +1009,7 @@ class ApexCapacitorPlugin : Plugin() {
         consentGranted = granted
         if (granted) {
             // Resume: flush anything captured before this point.
-            val queue = offlineQueue
-            val sender = batchSender
-            if (queue != null && sender != null) {
-                sender.flush(queue) { _, _ -> }
-            }
+            kickFlush("consent")
         } else {
             // Revoke: drop anything queued but not yet sent.
             try {
@@ -984,6 +1027,54 @@ class ApexCapacitorPlugin : Plugin() {
 
     // ── Internal ──────────────────────────────────────────────────────
 
+    override fun handleOnResume() {
+        super.handleOnResume()
+        kickFlush("foreground")
+    }
+
+    override fun handleOnDestroy() {
+        flushTimer?.let { flushHandler.removeCallbacks(it) }
+        pendingTrackFlush?.let { flushHandler.removeCallbacks(it) }
+        super.handleOnDestroy()
+    }
+
+    /** Sends the queue every 30s so bursts and background captures leave the device. */
+    private fun scheduleFlushTimer() {
+        flushTimer?.let { flushHandler.removeCallbacks(it) }
+        val tick = object : Runnable {
+            override fun run() {
+                kickFlush("timer")
+                flushHandler.postDelayed(this, FLUSH_INTERVAL_MS)
+            }
+        }
+        flushTimer = tick
+        flushHandler.postDelayed(tick, FLUSH_INTERVAL_MS)
+    }
+
+    /**
+     * Fire-and-forget send. Track-triggered sends wait 250ms so a burst of
+     * taps goes as one batch. The sender only runs one drain at a time.
+     */
+    private fun kickFlush(reason: String) {
+        val queue = offlineQueue ?: return
+        val sender = batchSender ?: return
+        val run = Runnable {
+            if (debug) println("[apex-capacitor] flush kicked ($reason)")
+            sender.flush(queue) { flushed, remaining ->
+                if (debug && (flushed > 0 || remaining > 0)) {
+                    println("[apex-capacitor] flush done — sent $flushed, remaining $remaining")
+                }
+            }
+        }
+        if (reason == "track") {
+            pendingTrackFlush?.let { flushHandler.removeCallbacks(it) }
+            pendingTrackFlush = run
+            flushHandler.postDelayed(run, TRACK_FLUSH_DEBOUNCE_MS)
+        } else {
+            run.run()
+        }
+    }
+
     private fun fetchInstallReferrer() {
         val client = InstallReferrerClient.newBuilder(context).build()
         client.startConnection(object : InstallReferrerStateListener {
@@ -992,6 +1083,11 @@ class ApexCapacitorPlugin : Plugin() {
                     if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
                         val details = client.installReferrer
                         lastInstallReferrer = details.installReferrer
+                        // The tap's own timestamp, not the install's. A
+                        // deferred link is only worth honouring while the
+                        // user still remembers tapping it, so JS ages the
+                        // referrer out against this.
+                        installReferrerClickSeconds = details.referrerClickTimestampSeconds
                     }
                 } catch (_: Exception) {
                     // ignore
@@ -999,13 +1095,36 @@ class ApexCapacitorPlugin : Plugin() {
                     try {
                         client.endConnection()
                     } catch (_: Exception) { }
+                    flushPendingReferrerCalls()
                 }
             }
 
-            override fun onInstallReferrerServiceDisconnected() { }
+            // A disconnect before the first response means Play will not
+            // answer this launch. Resolve the waiters with what we have
+            // (nothing) rather than leaving them to time out one by one.
+            override fun onInstallReferrerServiceDisconnected() {
+                flushPendingReferrerCalls()
+            }
         })
     }
 
+    private fun flushPendingReferrerCalls() {
+        installReferrerResolved = true
+        val waiting = synchronized(pendingReferrerCalls) {
+            val copy = pendingReferrerCalls.toList()
+            pendingReferrerCalls.clear()
+            copy
+        }
+        for (call in waiting) resolveInstallReferrer(call)
+    }
+
+    private fun resolveInstallReferrer(call: PluginCall) {
+        val data = JSObject()
+            .put("referrer", lastInstallReferrer ?: JSONObject.NULL)
+            .put("clickTimestamp", installReferrerClickSeconds)
+        call.resolve(data)
+    }
+
     companion object {
         /**
          * Weak-ish reference to the live plugin so the FCM messaging
@@ -1015,6 +1134,17 @@ class ApexCapacitorPlugin : Plugin() {
         @Volatile
         var activePlugin: ApexCapacitorPlugin? = null
 
+        /**
+         * How long `getInstallReferrer` will wait for Play before
+         * answering with what it has. Google's own samples see the
+         * connection settle in well under a second; past that the user is
+         * staring at a held-back first screen for a nice-to-have.
+         */
+        private const val REFERRER_WAIT_MS = 2500L
+
+        private const val FLUSH_INTERVAL_MS = 30_000L
+        private const val TRACK_FLUSH_DEBOUNCE_MS = 250L
+
         /**
          * Register a (possibly refreshed) FCM token with Apex from the
          * messaging service. Reads the persisted workspaceKey / apiBaseUrl

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

@@ -47,6 +47,10 @@ object ApexEvents {
 
     // ─── Identity ───────────────────────────────────────────────────────
     const val USER_SIGNED_UP = "user_signed_up"
+    const val WAITLIST_JOINED = "waitlist_joined"
+    const val USER_INVITED = "user_invited"
+    const val USER_INVITE_ACCEPTED = "user_invite_accepted"
+    const val PASSWORD_RESET_REQUESTED = "password_reset_requested"
     const val USER_SIGNED_IN = "user_signed_in"
     const val USER_SIGNED_OUT = "user_signed_out"
     const val USER_IDENTIFIED = "user_identified"
@@ -73,6 +77,7 @@ object ApexEvents {
     const val CONTENT_VIEW = "content_view"
     const val FORM_SUBMIT = "form_submit"
     const val CLICK = "click"
+    const val UI_ACTION = "ui_action"
     const val ENGAGEMENT = "engagement"
     const val HEARTBEAT = "heartbeat"
     const val RAGE_CLICK = "rage_click"
@@ -147,11 +152,13 @@ object ApexEvents {
     const val USAGE_MILESTONE_REACHED = "usage_milestone_reached"
     const val USER_CHURNED = "user_churned"
     const val USER_REACTIVATED = "user_reactivated"
+    const val TRIAL_EXPIRING = "trial_expiring"
     const val TRIAL_EXPIRED = "trial_expired"
     const val INVOICE_PAID = "invoice_paid"
     const val SUBSCRIPTION_RENEWED = "subscription_renewed"
 
     // Engagement suite (User Lifecycle)
+    const val REPORT_READY = "report_ready"
     const val REPORT_VIEWED = "report_viewed"
     const val CONTENT_VIEWED = "content_viewed"
     const val TASK_COMPLETED = "task_completed"
@@ -168,13 +175,13 @@ object ApexEvents {
     const val CLIENT_REPORT_VIEWED = "client_report_viewed"
 
     /** Apex Spec semver this SDK implements. */
-    const val SPEC_VERSION = "1.3.0"
+    const val SPEC_VERSION = "1.5.0"
 
     /** Complete list of every canonical event name. */
     val ALL: List<String> = listOf(
         ADD_TO_CART, REMOVE_FROM_CART, PRODUCT_VIEW, ADD_TO_WISHLIST, CHECKOUT_STARTED,
         IN_APP_PURCHASE, PURCHASE_REFUNDED, SUBSCRIPTION_EVENT, SUBSCRIPTION_UPGRADED, SUBSCRIPTION_DOWNGRADED,
-        USER_SIGNED_UP, USER_SIGNED_IN, USER_SIGNED_OUT, USER_IDENTIFIED,
+        USER_SIGNED_UP, WAITLIST_JOINED, USER_INVITED, USER_INVITE_ACCEPTED, PASSWORD_RESET_REQUESTED, USER_SIGNED_IN, USER_SIGNED_OUT, USER_IDENTIFIED,
         APP_INSTALL, APP_OPEN, APP_BACKGROUND, APP_UNINSTALL, APP_REINSTALL,
         SESSION_START, SESSION_END,
         PAGE_VIEW, PAGEVIEW, SCREEN_VIEW, SEARCH, SHARE, CONTENT_VIEW, FORM_SUBMIT,
@@ -193,8 +200,8 @@ object ApexEvents {
         SELLER_VIEWED, ITEM_SAVED, INQUIRY_STARTED, MATCH_CREATED, TRANSACTION_CANCELED, DISPUTE_OPENED, REVIEW_SUBMITTED,
         CLIENT_ONBOARDED, CAMPAIGN_MILESTONE_REACHED, CONTRACT_RENEWAL_APPROACHING, NEW_CAPABILITY_LAUNCHED,
         LOYALTY_MILESTONE_REACHED, USAGE_MILESTONE_REACHED, USER_CHURNED, USER_REACTIVATED,
-        TRIAL_EXPIRED, INVOICE_PAID, SUBSCRIPTION_RENEWED,
-        REPORT_VIEWED, CONTENT_VIEWED, TASK_COMPLETED, API_REQUEST_COMPLETED, PROJECT_CREATED,
+        TRIAL_EXPIRING, TRIAL_EXPIRED, INVOICE_PAID, SUBSCRIPTION_RENEWED,
+        REPORT_READY, REPORT_VIEWED, CONTENT_VIEWED, TASK_COMPLETED, API_REQUEST_COMPLETED, PROJECT_CREATED,
         LISTING_VIEWED, MESSAGE_SENT, OFFER_SUBMITTED, TRANSACTION_COMPLETED, TASK_UPDATED,
         ASSET_UPLOADED, COMMENT_ADDED, TIME_LOGGED, CLIENT_REPORT_VIEWED,
     )

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

@@ -35,6 +35,33 @@ class DeepLinkManager {
     }
 
     companion object {
+        /**
+         * The `apex_dl` value an Apex Link carried, or null when it had none.
+         *
+         * Apex appends this on mobile clicks as a pass-through hint the merchant
+         * set on the link. Surfaced already-parsed so the app doesn't have to
+         * pick apart a query string; never interpreted here. Hand-parsed rather
+         * than via `Uri.parse` so this class stays pure Kotlin and testable off
+         * an Android device.
+         */
+        fun apexHint(url: String): String? {
+            val query = url.substringAfter('?', "").substringBefore('#')
+            if (query.isEmpty()) return null
+            for (pair in query.split('&')) {
+                val key = pair.substringBefore('=')
+                if (key != "apex_dl") continue
+                val raw = pair.substringAfter('=', "")
+                if (raw.isEmpty()) return null
+                val decoded = try {
+                    java.net.URLDecoder.decode(raw, "UTF-8")
+                } catch (_: Exception) {
+                    raw
+                }
+                return decoded.ifEmpty { null }
+            }
+            return null
+        }
+
         /** Is this a sensible deep link? Reject `file://` and empty schemes. */
         fun isValidDeepLink(url: String): Boolean {
             if (url.isBlank()) return false

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

@@ -0,0 +1,26 @@
+package inc.apex.capacitor
+
+import org.json.JSONObject
+
+/**
+ * Fields every queued Android event must carry, matching iOS `track()`.
+ * Without `visitorId` the server accepts the batch but sets the event
+ * aside, so it never reaches the debug stream or the dashboards.
+ * Caller-supplied timestamp and visitorId win; platform is always android.
+ */
+internal object TrackStamps {
+    fun apply(
+        payload: MutableMap<String, Any?>,
+        visitorId: String,
+        testMode: Boolean,
+        nowIso: String,
+    ) {
+        payload["platform"] = "android"
+        if (isMissing(payload["timestamp"])) payload["timestamp"] = nowIso
+        if (isMissing(payload["visitorId"])) payload["visitorId"] = visitorId
+        if (testMode) payload["testMode"] = true
+    }
+
+    private fun isMissing(value: Any?): Boolean =
+        value == null || value == JSONObject.NULL || (value is String && value.isBlank())
+}

package/dist/deferred-link.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Deferred deep-link resolution.
+ *
+ * The problem this solves: a user taps a link in Safari or Chrome, does
+ * not have your app, installs it from the store, and opens it. The tap
+ * and the launch share no cookie and no storage, so by default your app
+ * has no idea the user was headed for a specific screen and drops them
+ * on your home screen. The tap that cost you money lands nowhere.
+ *
+ * Apex matches the launch back to the tap server-side and hands you the
+ * destination. Call it once, early, and route on the result:
+ *
+ * ```ts
+ * const link = await Apex.getDeferredDeepLink();
+ * if (link) router.navigateByUrl(link.deepLinkHint ?? new URL(link.url).pathname);
+ * ```
+ *
+ * Two properties worth knowing before you build on it:
+ *
+ *   - **One-shot.** The match key is coarse (network + OS), so a link can
+ *     only be claimed once. Call this on first launch and persist what
+ *     you get; a second call returns null.
+ *   - **Best-effort.** Matching is probabilistic and returns null more
+ *     often than it returns a link — no network address, a VPN between
+ *     tap and install, or a slow install all produce a miss. Treat a
+ *     link as a bonus that improves the first run, never as a
+ *     precondition for it.
+ *
+ * Implemented in TypeScript rather than in the native bridges because it
+ * is one HTTPS call with no platform APIs involved, and the webview can
+ * make it identically on iOS, Android, and in browser preview.
+ */
+export interface DeferredDeepLinkResult {
+    /**
+     * The destination the tap was headed for, with Apex's own routing
+     * params (`apex_dl`, `apex_link`) already stripped.
+     */
+    url: string;
+    /**
+     * The link's `apex_dl` value — whatever screen identifier you put on
+     * the link in Apex. Null when the link carried none.
+     */
+    deepLinkHint: string | null;
+    /** Apex Link slug the tap came through, when it came through one. */
+    slug?: string;
+    /** Affiliate handle, for namespaced partner links. */
+    handle?: string;
+    source?: string;
+    campaign?: string;
+    /** ISO timestamp of the original tap. */
+    clickedAt: string;
+    /**
+     * How the launch was matched to the tap.
+     *
+     * `deterministic` means Google Play handed us the exact link the user
+     * tapped, via the install referrer — there is no guesswork in it.
+     * `probabilistic` means we matched on network address and OS, which is
+     * the best available on iOS and can, on a shared network, be wrong.
+     * Route on either; only gate irreversible actions (granting a credit,
+     * applying a referral bonus) on `deterministic`.
+     */
+    matchType: "deterministic" | "probabilistic";
+}
+export interface FetchDeferredDeepLinkOptions {
+    apiUrl: string;
+    workspaceKey: string;
+    platform: "ios" | "android";
+    apiKey?: string;
+    /** Abort the call after this many ms. Defaults to 5000. */
+    timeoutMs?: number;
+}
+export declare function fetchDeferredDeepLink(options: FetchDeferredDeepLinkOptions): Promise<DeferredDeepLinkResult | null>;
+//# sourceMappingURL=deferred-link.d.ts.map

package/dist/deferred-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-link.d.ts","sourceRoot":"","sources":["../src/deferred-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,SAAS,EAAE,eAAe,GAAG,eAAe,CAAC;CAC9C;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAwCxC"}