@apex-inc/capacitor-plugin 2.4.0 → 2.5.0

package/dist/esm/events.js.map

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

package/dist/esm/index.d.ts

@@ -12,8 +12,17 @@
  * ```
  */
 import type { ApexCapacitorPlugin } from "./definitions";
+import { SkanAutoConversionValues } from "./skan-conversion-values";
+/** Exposed for tests: the controller behind `autoConversionValues`. */
+export declare function __getSkanAutoConversionValues(): SkanAutoConversionValues | null;
 export declare const Apex: ApexCapacitorPlugin;
 export * from "./definitions";
+export { fetchDeferredDeepLink } from "./deferred-link";
+export type { DeferredDeepLinkResult, FetchDeferredDeepLinkOptions, } from "./deferred-link";
+export { deferredLinkFromReferrer, parseReferrer } from "./referrer-link";
+export type { ReferrerLinkOptions } from "./referrer-link";
+export { SkanAutoConversionValues, fetchSkanConversionSchema, pickConversionValue, skanWindowAt, SKAN_SCHEMA_MAX_AGE_MS, } from "./skan-conversion-values";
+export type { ConversionValueUpdate, FetchSkanSchemaOptions, FetchSkanSchemaResult, SkanAutoConversionValuesOptions, SkanValueStore, } from "./skan-conversion-values";
 export { OfflineQueue, InMemoryStorage, IndexedDBStorage } from "./offline-queue";
 export type { OfflineQueueStorage, OfflineQueueOptions, QueuedEvent } from "./offline-queue";
 export { SessionManager } from "./session-manager";

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,eAAe,CAAC;AAmCvB,eAAO,MAAM,IAAI,EAAE,mBAoBjB,CAAC;AAGH,cAAc,eAAe,CAAC;AAG9B,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAClF,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EACV,kBAAkB,EAClB,WAAW,IAAI,gBAAgB,EAC/B,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAK9C,OAAO,EACL,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,QAAQ,GACd,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAKhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EACV,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,eAAe,CAAC;AAOvB,OAAO,EACL,wBAAwB,EAEzB,MAAM,0BAA0B,CAAC;AAwIlC,uEAAuE;AACvE,wBAAgB,6BAA6B,IAAI,wBAAwB,GAAG,IAAI,CAE/E;AAED,eAAO,MAAM,IAAI,EAAE,mBAkEjB,CAAC;AAGH,cAAc,eAAe,CAAC;AAI9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAK3D,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,+BAA+B,EAC/B,cAAc,GACf,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAClF,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EACV,kBAAkB,EAClB,WAAW,IAAI,gBAAgB,EAC/B,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAK9C,OAAO,EACL,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,QAAQ,GACd,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAKhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EACV,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/esm/index.js

@@ -11,8 +11,11 @@
  * await Apex.track({ type: "app_open" });
  * ```
  */
-import { registerPlugin } from "@capacitor/core";
+import { Capacitor, registerPlugin } from "@capacitor/core";
 import { enableAutoScreenViews } from "./auto-screen-views";
+import { fetchDeferredDeepLink, } from "./deferred-link";
+import { deferredLinkFromReferrer } from "./referrer-link";
+import { SkanAutoConversionValues, } from "./skan-conversion-values";
 /**
  * Capacitor plugin proxy. In a native app, calls route through the bridge to
  * the iOS (Swift) or Android (Kotlin) implementation. In a web context
@@ -36,10 +39,114 @@ const ApexBridge = registerPlugin("ApexCapacitorPlugin", {
 // so the offline queue / batch sender paths are unchanged. Opt out
 // with `initialize({ autoTrackScreenViews: false })`.
 let disposeAutoScreenViews = null;
+/**
+ * Init options retained at the proxy level so `getDeferredDeepLink` can
+ * address the API without a second round trip through the bridge. The
+ * native layers do not expose their config back to JS, and this is the
+ * only caller that needs it.
+ */
+let initOptions = null;
+/**
+ * Marks the deferred link as spent so a relaunch doesn't route the user
+ * again. The server path is one-shot by itself, but Play keeps the
+ * install referrer forever — without this, every cold start of an
+ * Android app would re-navigate to the screen from the original ad tap.
+ */
+const CLAIMED_KEY = "apex_ddl_claimed";
+function alreadyClaimed() {
+    try {
+        return globalThis.localStorage?.getItem(CLAIMED_KEY) === "1";
+    }
+    catch {
+        // Private mode / storage disabled. Falling through means at worst we
+        // resolve twice, which is better than never resolving at all.
+        return false;
+    }
+}
+function markClaimed() {
+    try {
+        globalThis.localStorage?.setItem(CLAIMED_KEY, "1");
+    }
+    catch {
+        /* see alreadyClaimed */
+    }
+}
+/**
+ * Resolve the link the user was headed for before they installed.
+ *
+ * Two mechanisms, tried in order of certainty:
+ *
+ *   1. **Play install referrer (Android, deterministic).** Google
+ *      carries our routing payload across the install gap, so the app
+ *      learns the exact link with no network round trip and no chance of
+ *      matching the wrong person.
+ *   2. **Server fingerprint match (both platforms, probabilistic).** The
+ *      fallback, and the only option on iOS, since the App Store
+ *      forwards nothing.
+ *
+ * Lives at the proxy level rather than in each native bridge because
+ * step 2 is one HTTPS call with no platform APIs in it, and step 1 only
+ * needs the referrer string the bridge already returns.
+ */
+async function getDeferredDeepLink() {
+    const platform = Capacitor.getPlatform();
+    // Web has no install gap to bridge; see the web fallback for why
+    // claiming a link there would be actively wrong.
+    if (platform !== "ios" && platform !== "android")
+        return null;
+    if (alreadyClaimed())
+        return null;
+    if (platform === "android") {
+        try {
+            const { referrer, clickTimestamp } = await ApexBridge.getInstallReferrer();
+            const fromReferrer = deferredLinkFromReferrer(referrer, {
+                clickTimestampSeconds: clickTimestamp,
+            });
+            if (fromReferrer) {
+                markClaimed();
+                return fromReferrer;
+            }
+        }
+        catch {
+            // An older native build without the awaiting referrer method, or a
+            // device with no Play services. Fall through to the server match.
+        }
+    }
+    const workspaceKey = initOptions?.workspaceKey ?? initOptions?.projectKey ?? "";
+    if (!workspaceKey)
+        return null;
+    const resolved = await fetchDeferredDeepLink({
+        apiUrl: initOptions?.apiUrl ?? "https://app.apex.inc",
+        workspaceKey,
+        platform,
+        apiKey: initOptions?.apiKey,
+    });
+    if (resolved)
+        markClaimed();
+    return resolved;
+}
+/**
+ * Mobile Measurement P2 — automatic SKAN conversion values. Lives at the
+ * proxy level for the same reason `screen_view` auto-tracking does: the
+ * decision ("does this event mean something to Apple?") is one HTTPS
+ * fetch plus a table lookup in webview JS, and the send goes through the
+ * bridge's existing `updateConversionValue`. Null when the option is off
+ * or the platform is not iOS.
+ */
+let skanAuto = null;
+function debugLog(options, message) {
+    if (options?.debug)
+        console.log(`[apex-capacitor] ${message}`);
+}
+/** Exposed for tests: the controller behind `autoConversionValues`. */
+export function __getSkanAutoConversionValues() {
+    return skanAuto;
+}
 export const Apex = new Proxy(ApexBridge, {
     get(target, prop, receiver) {
         if (prop === "initialize") {
             return async (options) => {
+                initOptions = options;
                 await target.initialize(options);
                 disposeAutoScreenViews?.();
                 disposeAutoScreenViews = null;
@@ -52,6 +159,47 @@ export const Apex = new Proxy(ApexBridge, {
                         },
                     });
                 }
+                skanAuto = null;
+                const workspaceKey = options?.workspaceKey ?? options?.projectKey ?? "";
+                if (options?.autoConversionValues !== false &&
+                    Capacitor.getPlatform() === "ios" &&
+                    workspaceKey) {
+                    skanAuto = new SkanAutoConversionValues({
+                        update: (value) => target.updateConversionValue(value),
+                        log: (message) => debugLog(options, message),
+                    });
+                    await skanAuto.initialize({
+                        apiUrl: options.apiUrl ?? "https://app.apex.inc",
+                        workspaceKey,
+                        mobileAppId: options.mobileAppId ?? null,
+                    });
+                }
+            };
+        }
+        if (prop === "getDeferredDeepLink") {
+            return getDeferredDeepLink;
+        }
+        if (prop === "track") {
+            return async (event) => {
+                await target.track(event);
+                if (skanAuto && event?.type) {
+                    void skanAuto.onTrack(event.type).catch(() => undefined);
+                }
+            };
+        }
+        if (prop === "updateConversionValue") {
+            return async (value) => {
+                skanAuto?.noteManualUpdate();
+                await target.updateConversionValue(value);
+            };
+        }
+        if (prop === "getConversionValueSchema") {
+            return async () => {
+                if (!skanAuto) {
+                    return { schema: null, mobileAppId: null, etag: null, fetchedAt: 0 };
+                }
+                await skanAuto.whenReady();
+                return skanAuto.getSchema();
             };
         }
         return Reflect.get(target, prop, receiver);
@@ -59,6 +207,14 @@ export const Apex = new Proxy(ApexBridge, {
 });
 // Re-export types so consumers can import them cleanly.
 export * from "./definitions";
+// Deferred deep linking — the resolver is exported for advanced use
+// (e.g. a custom bootstrap that already knows its platform).
+export { fetchDeferredDeepLink } from "./deferred-link";
+export { deferredLinkFromReferrer, parseReferrer } from "./referrer-link";
+// Mobile Measurement P2 — automatic SKAN conversion values. The pure
+// pieces are exported for advanced use (a custom bootstrap that wants to
+// read the table itself) and for tests.
+export { SkanAutoConversionValues, fetchSkanConversionSchema, pickConversionValue, skanWindowAt, SKAN_SCHEMA_MAX_AGE_MS, } from "./skan-conversion-values";
 // Re-export core modules for advanced/test usage.
 export { OfflineQueue, InMemoryStorage, IndexedDBStorage } from "./offline-queue";
 export { SessionManager } from "./session-manager";

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,IAAI,cAAc,GAA4B,IAAI,CAAC;AAEnD,MAAM,UAAU,GAAwB,cAAc,CACpD,qBAAqB,EACrB;IACE,GAAG,EAAE,GAAG,EAAE,CACR,CAAC,cAAc,KAAd,cAAc,GAAK,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAChC,EAAC;CACL,CACF,CAAC;AAEF,sEAAsE;AACtE,sEAAsE;AACtE,qEAAqE;AACrE,sEAAsE;AACtE,mEAAmE;AACnE,sDAAsD;AACtD,IAAI,sBAAsB,GAAwB,IAAI,CAAC;AAEvD,MAAM,CAAC,MAAM,IAAI,GAAwB,IAAI,KAAK,CAAC,UAAU,EAAE;IAC7D,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;QACxB,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1B,OAAO,KAAK,EAAE,OAA0B,EAAiB,EAAE;gBACzD,MAAM,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;gBACjC,sBAAsB,EAAE,EAAE,CAAC;gBAC3B,sBAAsB,GAAG,IAAI,CAAC;gBAC9B,IAAI,OAAO,EAAE,oBAAoB,KAAK,KAAK,EAAE,CAAC;oBAC5C,sBAAsB,GAAG,qBAAqB,CAAC;wBAC7C,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;4BACf,KAAK,MAAM;iCACR,KAAK,CAAC,KAAkB,CAAC;iCACzB,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;wBAC5B,CAAC;qBACF,CAAC,CAAC;gBACL,CAAC;YACH,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC,CAAC;AAEH,wDAAwD;AACxD,cAAc,eAAe,CAAC;AAE9B,kDAAkD;AAClD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAM7C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,8CAA8C;AAC9C,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGzD,oEAAoE;AACpE,+DAA+D;AAC/D,kBAAkB;AAClB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AAExB,uDAAuD;AACvD,kEAAkE;AAClE,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,sEAAsE;AACtE,sEAAsE;AACtE,gEAAgE;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/referrer-link.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Deterministic deferred deep linking on Android, from the Play referrer.
+ *
+ * The server-side path (`./deferred-link.ts`) matches an install back to
+ * a tap using `hash(ip)#platform`, because that is all a browser tap and
+ * a fresh app install have in common. It works, and it is the only thing
+ * available on iOS, but it cannot tell two phones on the same office
+ * wifi apart — which is why it is one-shot and short-windowed.
+ *
+ * Android does not need to guess. Google Play carries one string across
+ * the install gap, the `referrer` param, and Apex packs the link's
+ * routing payload into it at redirect time (`links/play-referrer.ts` on
+ * the server). At first launch the Play Install Referrer API hands that
+ * exact string back, so the app learns precisely which link the user
+ * tapped: no IP, no fingerprint, no ambiguity, and no round trip.
+ *
+ * This module is the parsing half. It is pure so it can be tested
+ * without a device; the plugin proxy owns when to call it.
+ */
+import type { DeferredDeepLinkResult } from "./deferred-link";
+/** Parse a `k=v&k=v` referrer string. Play hands it over URL-encoded. */
+export declare function parseReferrer(raw: string): Record<string, string>;
+export interface ReferrerLinkOptions {
+    /** Unix seconds, from the Play Install Referrer API. 0 when unknown. */
+    clickTimestampSeconds?: number;
+    /** Injectable for tests. */
+    now?: number;
+    maxAgeMs?: number;
+}
+/**
+ * Turn a Play referrer into a deferred deep link, or null when it
+ * carries no Apex routing payload (an organic install, or a referrer
+ * written by another attribution provider).
+ */
+export declare function deferredLinkFromReferrer(raw: string | null | undefined, options?: ReferrerLinkOptions): DeferredDeepLinkResult | null;
+//# sourceMappingURL=referrer-link.d.ts.map

package/dist/esm/referrer-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referrer-link.d.ts","sourceRoot":"","sources":["../../src/referrer-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAuB9D,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUjE;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,OAAO,GAAE,mBAAwB,GAChC,sBAAsB,GAAG,IAAI,CA4C/B"}

package/dist/esm/referrer-link.js

@@ -0,0 +1,103 @@
+/**
+ * Deterministic deferred deep linking on Android, from the Play referrer.
+ *
+ * The server-side path (`./deferred-link.ts`) matches an install back to
+ * a tap using `hash(ip)#platform`, because that is all a browser tap and
+ * a fresh app install have in common. It works, and it is the only thing
+ * available on iOS, but it cannot tell two phones on the same office
+ * wifi apart — which is why it is one-shot and short-windowed.
+ *
+ * Android does not need to guess. Google Play carries one string across
+ * the install gap, the `referrer` param, and Apex packs the link's
+ * routing payload into it at redirect time (`links/play-referrer.ts` on
+ * the server). At first launch the Play Install Referrer API hands that
+ * exact string back, so the app learns precisely which link the user
+ * tapped: no IP, no fingerprint, no ambiguity, and no round trip.
+ *
+ * This module is the parsing half. It is pure so it can be tested
+ * without a device; the plugin proxy owns when to call it.
+ */
+/**
+ * How long a referrer stays worth honouring, matching the server's
+ * routing window. Play keeps the referrer forever, so without an age
+ * check an app reinstalled a year later would route the user to last
+ * year's promotion.
+ */
+const MAX_REFERRER_AGE_MS = 2 * 60 * 60 * 1000;
+/** Set by `play-referrer.ts` on the server. Keep the two in sync. */
+const DEEP_LINK_KEY = "apex_dl";
+const LINK_REF_KEY = "apex_link";
+const DESTINATION_KEY = "apex_dest";
+function decode(value) {
+    try {
+        return decodeURIComponent(value.replace(/\+/g, " "));
+    }
+    catch {
+        return value;
+    }
+}
+/** Parse a `k=v&k=v` referrer string. Play hands it over URL-encoded. */
+export function parseReferrer(raw) {
+    const out = {};
+    for (const segment of raw.split("&")) {
+        const idx = segment.indexOf("=");
+        if (idx <= 0)
+            continue;
+        const key = decode(segment.slice(0, idx));
+        const value = decode(segment.slice(idx + 1));
+        if (key && value)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Turn a Play referrer into a deferred deep link, or null when it
+ * carries no Apex routing payload (an organic install, or a referrer
+ * written by another attribution provider).
+ */
+export function deferredLinkFromReferrer(raw, options = {}) {
+    if (!raw)
+        return null;
+    const params = parseReferrer(raw);
+    const hint = params[DEEP_LINK_KEY] ?? null;
+    const destination = params[DESTINATION_KEY] ?? "";
+    const linkRef = params[LINK_REF_KEY];
+    // No routing payload means this referrer isn't ours to act on. UTMs
+    // alone don't qualify: they say which campaign paid for the install,
+    // not which screen the user was headed for, and routing on a campaign
+    // name would send people somewhere nobody asked for.
+    if (!hint && !destination)
+        return null;
+    const clickSeconds = options.clickTimestampSeconds ?? 0;
+    const clickedAtMs = clickSeconds > 0 ? clickSeconds * 1000 : 0;
+    if (clickedAtMs > 0) {
+        const age = (options.now ?? Date.now()) - clickedAtMs;
+        if (age > (options.maxAgeMs ?? MAX_REFERRER_AGE_MS))
+            return null;
+    }
+    // A namespaced partner link is stamped `handle/slug` — same shape the
+    // server's `linkRefValue` writes.
+    let slug;
+    let handle;
+    if (linkRef) {
+        const parts = linkRef.split("/").filter(Boolean);
+        if (parts.length === 2) {
+            handle = parts[0];
+            slug = parts[1];
+        }
+        else if (parts.length === 1) {
+            slug = parts[0];
+        }
+    }
+    return {
+        url: destination,
+        deepLinkHint: hint,
+        slug,
+        handle,
+        source: params.utm_source,
+        campaign: params.utm_campaign,
+        clickedAt: new Date(clickedAtMs > 0 ? clickedAtMs : Date.now()).toISOString(),
+        matchType: "deterministic",
+    };
+}
+//# sourceMappingURL=referrer-link.js.map

package/dist/esm/referrer-link.js.map

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

package/dist/esm/skan-conversion-values.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Automatic SKAdNetwork conversion values.
+ *
+ * The shop answers one question in Set up Apex ("which event means an
+ * install was worth it?") and Apex turns it into a table of what Apple's
+ * 0–63 numbers mean for the app. This module reads that table and, every
+ * time the app tracks an event that appears in it, tells Apple the new
+ * value — so the shop never writes `updateConversionValue` by hand.
+ *
+ * Behaviour, in order of importance:
+ *
+ *   - **Manual wins.** The first time the app calls
+ *     `Apex.updateConversionValue` itself, automatic updates stop for
+ *     that install. A shop that hand-rolls its ladder keeps its ladder.
+ *   - **Values only go up.** Apple keeps the last value it was given, and
+ *     every network reads the ladder as "higher means more". Within a
+ *     postback window the plugin never sends a lower value than it has
+ *     already sent.
+ *   - **Never in the way.** The schema is fetched once per day and cached;
+ *     a slow or unreachable Apex means the app runs with yesterday's
+ *     table (or none), never a delayed first screen.
+ *
+ * SKAN 4 windows, counted from first launch: window 1 covers days 0–2,
+ * window 2 days 3–7, window 3 days 8–35. After day 35 Apple is no longer
+ * listening and nothing is sent.
+ *
+ * Pure TypeScript on purpose: one HTTPS call and a little arithmetic, no
+ * platform APIs, so it runs identically under the native iOS bridge and
+ * in browser preview (where the update itself is a no-op).
+ */
+import type { SkanCoarseValue } from "./definitions";
+export type SkanWindow = 1 | 2 | 3;
+export interface SkanConversionValueEntry {
+    eventName: string;
+    fineValue: number;
+    coarseValue: SkanCoarseValue;
+    lockWindow?: boolean;
+}
+export interface SkanConversionWindow {
+    window: SkanWindow;
+    values: SkanConversionValueEntry[];
+}
+export interface SkanConversionSchema {
+    windows: SkanConversionWindow[];
+    updatedAt: string;
+}
+/** What {@link fetchSkanConversionSchema} and the cache carry. */
+export interface SkanSchemaSnapshot {
+    schema: SkanConversionSchema | null;
+    mobileAppId: string | null;
+    /** Weak ETag from the server, replayed as `If-None-Match`. */
+    etag: string | null;
+    /** Epoch ms when this snapshot was confirmed fresh. */
+    fetchedAt: number;
+}
+export interface FetchSkanSchemaOptions {
+    apiUrl: string;
+    workspaceKey: string;
+    mobileAppId?: string | null;
+    /** Previous ETag; a matching server tag returns `not_modified`. */
+    etag?: string | null;
+    /** Abort after this many ms. Defaults to 5000. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+export type FetchSkanSchemaResult = {
+    status: "fresh";
+    snapshot: SkanSchemaSnapshot;
+} | {
+    status: "not_modified";
+} | {
+    status: "error";
+};
+export declare function fetchSkanConversionSchema(options: FetchSkanSchemaOptions, now?: () => number): Promise<FetchSkanSchemaResult>;
+/**
+ * Keep only rungs the plugin can act on. The server validates on write,
+ * but a cached snapshot may outlive a schema change, so be strict here
+ * too: a bad rung is dropped, never sent to Apple.
+ */
+export declare function normalizeSchema(raw: SkanConversionSchema | null | undefined): SkanConversionSchema | null;
+/**
+ * Which SKAN 4 postback window a moment falls in, counted from first
+ * launch. Null once Apple has stopped listening (after day 35).
+ */
+export declare function skanWindowAt(installedAt: number, now: number): SkanWindow | null;
+/** What to tell Apple, when an event maps and is worth telling. */
+export interface ConversionValueUpdate {
+    fineValue: number;
+    coarseValue: SkanCoarseValue;
+    lockWindow?: boolean;
+    window: SkanWindow;
+}
+/**
+ * Decide whether tracking `eventName` should change Apple's value.
+ * Returns null when the event has no meaning in the current window or
+ * when the mapped value would not move the ladder up.
+ */
+export declare function pickConversionValue(schema: SkanConversionSchema | null, eventName: string, ctx: {
+    installedAt: number;
+    now: number;
+    highestSent: number | null;
+}): ConversionValueUpdate | null;
+/** Minimal key/value store; `localStorage` fits, so does a Map in tests. */
+export interface SkanValueStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export declare const SKAN_STORAGE_KEYS: {
+    readonly snapshot: "apex_skan_schema_v1";
+    readonly installedAt: "apex_skan_installed_at";
+    readonly manual: "apex_skan_manual";
+    readonly highest: "apex_skan_highest_v1";
+};
+/** How long a cached schema is trusted before revalidating. */
+export declare const SKAN_SCHEMA_MAX_AGE_MS: number;
+export interface SkanAutoConversionValuesOptions {
+    /** Sends the value to Apple (the bridge's `updateConversionValue`). */
+    update: (value: {
+        fineValue: number;
+        coarseValue?: SkanCoarseValue;
+        lockWindow?: boolean;
+    }) => Promise<void>;
+    store?: SkanValueStore | null;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Debug sink; receives one line per decision when set. */
+    log?: (message: string) => void;
+}
+/**
+ * Owns the cached schema and the "what have I already told Apple"
+ * bookkeeping for one install. Created by the plugin proxy on
+ * `initialize({ autoConversionValues: true })`; not something an app
+ * constructs itself.
+ */
+export declare class SkanAutoConversionValues {
+    private readonly update;
+    private readonly store;
+    private readonly fetchImpl?;
+    private readonly now;
+    private readonly log?;
+    private snapshot;
+    private installedAt;
+    private manual;
+    private highest;
+    private ready;
+    private endpoint;
+    constructor(options: SkanAutoConversionValuesOptions);
+    /**
+     * Point at a workspace and refresh the schema if the cache is stale.
+     * Resolves as soon as the cache has been read; the network revalidate
+     * runs in the background and never blocks the caller.
+     */
+    initialize(endpoint: {
+        apiUrl: string;
+        workspaceKey: string;
+        mobileAppId?: string | null;
+    }): Promise<void>;
+    /** Force a network revalidation (ETag-aware). */
+    revalidate(): Promise<void>;
+    /** Wait for any in-flight revalidation (tests and debug UIs). */
+    whenReady(): Promise<void>;
+    /** The schema the plugin is acting on right now. */
+    getSchema(): SkanSchemaSnapshot;
+    /** True once the app has called `updateConversionValue` itself. */
+    get manualMode(): boolean;
+    /** Called when the app updates Apple's value by hand. Auto steps aside. */
+    noteManualUpdate(): void;
+    /**
+     * Called after every `track`. Sends the mapped value when the event has
+     * one in the current window and it moves the ladder up.
+     */
+    onTrack(eventName: string): Promise<ConversionValueUpdate | null>;
+    private readInstalledAt;
+}
+//# sourceMappingURL=skan-conversion-values.d.ts.map

package/dist/esm/skan-conversion-values.d.ts.map

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