@apex-inc/capacitor-plugin 0.3.9 → 2.1.0

package/dist/definitions.d.ts

@@ -40,6 +40,30 @@ export interface PushReceivedEvent {
 }
 /** Supported tracking platforms. */
 export type ApexPlatform = "ios" | "android" | "web";
+/**
+ * Build source the app was installed from. Detected by the SDK from
+ * `AppTransaction` / receipt URL (iOS) or installer package source +
+ * `BuildConfig.DEBUG` (Android).
+ *
+ * - `xcode-debug` — Xcode-attached debug build (iOS) or Gradle DEBUG (Android).
+ *   Also returned for iOS Simulator regardless of `sandboxReceipt` presence.
+ * - `testflight` — iOS TestFlight build (sandbox receipt, no debugger attached).
+ * - `app-store` — production App Store build (valid receipt).
+ * - `play-internal` — Play Console closed test track (currently only reachable
+ *   via explicit `Apex.initialize({ releaseChannel: "play-internal" })`
+ *   override; server-side reconciliation via Play Console API ships in MMP-069).
+ * - `play-production` — installed via Google Play Store.
+ * - `sideloaded` — installed via APK download / ADB / unknown installer.
+ * - `unknown` — fallback when no signal is available (enterprise / in-house
+ *   iOS distribution, AppTransaction `.unverified` with no receipt URL).
+ *
+ * Why this matters: the SDK auto-tags every event so dashboards, audiences,
+ * billing, and the push composer route to the right "Dev / Beta / Production"
+ * bucket without merchants flipping a flag.
+ */
+export type ReleaseChannel = "xcode-debug" | "testflight" | "app-store" | "play-internal" | "play-production" | "sideloaded" | "unknown";
+/** How {@link ReleaseChannel} was determined. */
+export type ReleaseChannelSource = "auto" | "override" | "play-api";
 /** Fallback source when the primary advertising identifier is unavailable. */
 export type AdvertisingIdFallback = "idfv" | "android_id" | null;
 /** Coarse SKAN 4.0 conversion value. */
@@ -81,6 +105,22 @@ export interface ApexEvent {
      * differ.
      */
     platform?: ApexPlatform;
+    /**
+     * MMP-080/081 — runtime context. Stamped automatically by the SDK
+     * based on which plugin variant emitted the event:
+     *
+     *  - Native iOS plugin → `native-ios`
+     *  - Native Android plugin → `native-android`
+     *  - Web fallback (no native plugin) → `capacitor-webview`
+     *
+     * Server-side ingest validates these values; callers almost never
+     * set this directly. The dashboard groups events by `clientType` to
+     * distinguish "Capacitor app running natively" from "Capacitor app
+     * running in a browser fallback" — the latter loses IDFA, store
+     * receipts, install referrer, and deep links, which usually means
+     * the merchant forgot to wire the native plugin.
+     */
+    clientType?: "capacitor-webview" | "native-ios" | "native-android" | "browser-tab" | "installed-pwa" | "server";
     /**
      * When true, the event is routed to the test-event store and is
      * excluded from production analytics. The SDK stamps this from
@@ -117,6 +157,26 @@ export interface InitializeOptions {
     projectKey: string;
     /** API base URL. Defaults to `https://api.apex.inc`. */
     apiUrl?: string;
+    /**
+     * Optional workspace-bound API key (`apex_uk_*` or `apex_sk_*`).
+     *
+     * When set, the plugin attaches it as `x-apex-api-key` on every
+     * outbound request to `/api/events` and `/api/identity/stitch`. The
+     * server uses this to authorize quarantine-mode auto-stitch
+     * (Phase 2-quarantine) and explicit `identify()` calls
+     * (Phase 2-prep `stitchIdentity` verified mode).
+     *
+     * Without an API key, events still flow but auto-stitch is
+     * suppressed and `identify()` calls are accepted only for projects
+     * whose visitor->Contact link can be derived from the request
+     * project key alone.
+     *
+     * IMPORTANT: only embed API keys in mobile apps when the workspace
+     * is dedicated to that app. Treat the value like a publishable key,
+     * not a secret — assume it will leak via reverse-engineering. Apex
+     * rate-limits per key + per visitor to make leaked keys low-yield.
+     */
+    apiKey?: string;
     /** Tag subsequent events as test mode (excluded from production analytics). */
     testMode?: boolean;
     /** Session timeout in minutes. Default 30. */
@@ -125,6 +185,57 @@ export interface InitializeOptions {
     offlineQueueMaxSize?: number;
     /** Enable verbose console logging. Default false. */
     debug?: boolean;
+    /**
+     * MMP-061 — manual override for {@link ReleaseChannel}.
+     *
+     * On Android this is the canonical way to flag closed-test builds
+     * (Play does NOT expose internal/closed/open tracks at the device
+     * level). Wire it through your `BuildConfig.RELEASE_CHANNEL` per
+     * build flavor so each flavor reports the right channel without
+     * thinking about it. Once a merchant connects their Play Console via
+     * MMP-069, server-side reconciliation takes over and the override
+     * becomes optional.
+     *
+     * On iOS this is **ignored** — `AppTransaction` / receipt URL are
+     * authoritative. We log a console warning when an override is passed
+     * on iOS so the discrepancy is visible during development; the
+     * server stamps `releaseChannelSource: "auto"` regardless.
+     */
+    releaseChannel?: ReleaseChannel;
+}
+/**
+ * Options for {@link ApexCapacitorPlugin.identify}.
+ *
+ * Phase 2-SDK (council-revised mobile dashboard plan). Identify is the
+ * explicit, first-class call merchants use to bind a known user to the
+ * current visitor session. The server resolves the email (and optional
+ * userId) to an Apex Contact and stamps `verifiedAt = now`, promoting
+ * any previously-quarantined Contact for this visitor + lighting up
+ * affiliate stamping, scoring, and journey dispatch.
+ *
+ * This is intentionally distinct from `track({ type: "user_signed_up",
+ * data: { email } })`. Track is a fire-and-forget event; identify is
+ * the durable identity gesture. The two interact: a server-side
+ * auto-stitch on `user_signed_up` lands the Contact in quarantine; an
+ * `identify()` call promotes it to verified.
+ */
+export interface IdentifyOptions {
+    /**
+     * Email address — the canonical identifier Apex uses to merge
+     * anonymous visitor sessions into a known Contact. Required.
+     */
+    email: string;
+    /**
+     * Optional merchant-side stable user id (e.g. a row id from the
+     * merchant's user table). When provided, Apex stores it on the
+     * Contact so cross-platform stitching can use both email + userId.
+     */
+    userId?: string;
+    /**
+     * Optional metadata to attach to the identify event (e.g. signup
+     * source, plan tier, locale). Merged into the Contact's traits.
+     */
+    traits?: Record<string, unknown>;
 }
 /** Return value of {@link ApexCapacitorPlugin.getAdvertisingId}. */
 export interface AdvertisingIdResult {
@@ -142,6 +253,14 @@ export interface DeviceInfo {
     bundleId: string;
     timezone: string;
     locale: string;
+    /**
+     * MMP-061 — the detected build source (or override). Surfaced so
+     * sample apps + developer-facing UIs can show a "Running: TestFlight"
+     * badge without round-tripping to the server.
+     */
+    releaseChannel?: ReleaseChannel;
+    /** How {@link DeviceInfo.releaseChannel} was determined. */
+    releaseChannelSource?: ReleaseChannelSource;
 }
 /** Summary of offline-queue state. */
 export interface QueueStatus {
@@ -211,8 +330,12 @@ export interface ApexCapacitorPlugin {
      * listener AND is auto-registered with Apex via `POST /api/mobile/push-token`
      * so the dashboard sees it immediately.
      *
-     * On Android (FCM) and on web this is currently a no-op returning
-     * `permission: "denied"`. Android FCM ships in a follow-up.
+     * On Android this fetches the FCM registration token via
+     * `FirebaseMessaging`, auto-registers it with Apex via
+     * `POST /api/mobile/push-token`, and fires `pushTokenReceived`. (The
+     * app must include a `google-services.json` and the host must be a
+     * Firebase project.) On web this remains a no-op returning
+     * `permission: "denied"`.
      */
     registerForPushNotifications(): Promise<PushRegistrationResult>;
     /**
@@ -243,6 +366,23 @@ export interface ApexCapacitorPlugin {
     setVisitorId(options: {
         visitorId: string;
     }): Promise<void>;
+    /**
+     * Identifies the current visitor as a known user. Resolves the email
+     * to an Apex Contact (creating it if needed) and stamps the
+     * resulting Contact as `verified` so downstream pipelines (affiliate
+     * stamping, scoring, journey dispatch) can run.
+     *
+     * Typical placement:
+     *   - Right after a user submits a signup form
+     *   - Right after a user signs in
+     *   - On app start when a known authenticated user is hydrated from
+     *     your auth provider
+     *
+     * Idempotent — calling identify with the same email + visitor is
+     * safe. The server rate-limits per visitor (1 req/sec) to prevent
+     * identity-flip-flop attacks.
+     */
+    identify(options: IdentifyOptions): Promise<void>;
     /**
      * Updates the SKAdNetwork 4.0 postback conversion value. No-op on Android.
      * `fineValue` is 0-63 (fine conversion value); `coarseValue` is optional

package/dist/definitions.d.ts.map

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

package/dist/esm/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/esm/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/esm/batch-sender.js

@@ -18,6 +18,7 @@ export 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;
@@ -34,11 +35,28 @@ export 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)
@@ -105,6 +123,13 @@ export 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/esm/batch-sender.js.map

@@ -1 +1 @@
-{"version":3,"file":"batch-sender.js","sourceRoot":"","sources":["../../src/batch-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAgCH,MAAM,OAAO,WAAW;IAItB,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,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;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,KAAmB;QAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,gBAAgB,GAAG,CAAC,CAAC;QACzB,IAAI,SAA6B,CAAC;QAElC,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;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"}
+{"version":3,"file":"batch-sender.js","sourceRoot":"","sources":["../../src/batch-sender.ts"],"names":[],"mappings":"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"}

package/dist/esm/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/esm/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/esm/cart-helpers.js

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+import { Apex } from "./index";
+import { ApexEvents } from "./events";
+/** Add an item to the cart. */
+export async function trackCartAdd(line) {
+    await Apex.track({ type: ApexEvents.AddToCart, data: { ...line } });
+}
+/** Remove an item from the cart. */
+export async function trackCartRemove(opts) {
+    await Apex.track({ type: 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.
+ */
+export 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 Apex.track({ type: "cart_snapshot", data: { ...opts } });
+}
+/** Clear the cart on successful checkout. */
+export async function trackCheckoutCompleted(opts) {
+    await Apex.track({ type: "checkout_completed", data: { ...opts } });
+}
+//# sourceMappingURL=cart-helpers.js.map

package/dist/esm/cart-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart-helpers.js","sourceRoot":"","sources":["../../src/cart-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAuBtC,+BAA+B;AAC/B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAMrC;IACC,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAGvC;IACC,mEAAmE;IACnE,+DAA+D;IAC/D,kEAAkE;IAClE,gCAAgC;IAChC,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAI5C;IACC,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/esm/definitions.d.ts

@@ -40,6 +40,30 @@ export interface PushReceivedEvent {
 }
 /** Supported tracking platforms. */
 export type ApexPlatform = "ios" | "android" | "web";
+/**
+ * Build source the app was installed from. Detected by the SDK from
+ * `AppTransaction` / receipt URL (iOS) or installer package source +
+ * `BuildConfig.DEBUG` (Android).
+ *
+ * - `xcode-debug` — Xcode-attached debug build (iOS) or Gradle DEBUG (Android).
+ *   Also returned for iOS Simulator regardless of `sandboxReceipt` presence.
+ * - `testflight` — iOS TestFlight build (sandbox receipt, no debugger attached).
+ * - `app-store` — production App Store build (valid receipt).
+ * - `play-internal` — Play Console closed test track (currently only reachable
+ *   via explicit `Apex.initialize({ releaseChannel: "play-internal" })`
+ *   override; server-side reconciliation via Play Console API ships in MMP-069).
+ * - `play-production` — installed via Google Play Store.
+ * - `sideloaded` — installed via APK download / ADB / unknown installer.
+ * - `unknown` — fallback when no signal is available (enterprise / in-house
+ *   iOS distribution, AppTransaction `.unverified` with no receipt URL).
+ *
+ * Why this matters: the SDK auto-tags every event so dashboards, audiences,
+ * billing, and the push composer route to the right "Dev / Beta / Production"
+ * bucket without merchants flipping a flag.
+ */
+export type ReleaseChannel = "xcode-debug" | "testflight" | "app-store" | "play-internal" | "play-production" | "sideloaded" | "unknown";
+/** How {@link ReleaseChannel} was determined. */
+export type ReleaseChannelSource = "auto" | "override" | "play-api";
 /** Fallback source when the primary advertising identifier is unavailable. */
 export type AdvertisingIdFallback = "idfv" | "android_id" | null;
 /** Coarse SKAN 4.0 conversion value. */
@@ -81,6 +105,22 @@ export interface ApexEvent {
      * differ.
      */
     platform?: ApexPlatform;
+    /**
+     * MMP-080/081 — runtime context. Stamped automatically by the SDK
+     * based on which plugin variant emitted the event:
+     *
+     *  - Native iOS plugin → `native-ios`
+     *  - Native Android plugin → `native-android`
+     *  - Web fallback (no native plugin) → `capacitor-webview`
+     *
+     * Server-side ingest validates these values; callers almost never
+     * set this directly. The dashboard groups events by `clientType` to
+     * distinguish "Capacitor app running natively" from "Capacitor app
+     * running in a browser fallback" — the latter loses IDFA, store
+     * receipts, install referrer, and deep links, which usually means
+     * the merchant forgot to wire the native plugin.
+     */
+    clientType?: "capacitor-webview" | "native-ios" | "native-android" | "browser-tab" | "installed-pwa" | "server";
     /**
      * When true, the event is routed to the test-event store and is
      * excluded from production analytics. The SDK stamps this from
@@ -117,6 +157,26 @@ export interface InitializeOptions {
     projectKey: string;
     /** API base URL. Defaults to `https://api.apex.inc`. */
     apiUrl?: string;
+    /**
+     * Optional workspace-bound API key (`apex_uk_*` or `apex_sk_*`).
+     *
+     * When set, the plugin attaches it as `x-apex-api-key` on every
+     * outbound request to `/api/events` and `/api/identity/stitch`. The
+     * server uses this to authorize quarantine-mode auto-stitch
+     * (Phase 2-quarantine) and explicit `identify()` calls
+     * (Phase 2-prep `stitchIdentity` verified mode).
+     *
+     * Without an API key, events still flow but auto-stitch is
+     * suppressed and `identify()` calls are accepted only for projects
+     * whose visitor->Contact link can be derived from the request
+     * project key alone.
+     *
+     * IMPORTANT: only embed API keys in mobile apps when the workspace
+     * is dedicated to that app. Treat the value like a publishable key,
+     * not a secret — assume it will leak via reverse-engineering. Apex
+     * rate-limits per key + per visitor to make leaked keys low-yield.
+     */
+    apiKey?: string;
     /** Tag subsequent events as test mode (excluded from production analytics). */
     testMode?: boolean;
     /** Session timeout in minutes. Default 30. */
@@ -125,6 +185,57 @@ export interface InitializeOptions {
     offlineQueueMaxSize?: number;
     /** Enable verbose console logging. Default false. */
     debug?: boolean;
+    /**
+     * MMP-061 — manual override for {@link ReleaseChannel}.
+     *
+     * On Android this is the canonical way to flag closed-test builds
+     * (Play does NOT expose internal/closed/open tracks at the device
+     * level). Wire it through your `BuildConfig.RELEASE_CHANNEL` per
+     * build flavor so each flavor reports the right channel without
+     * thinking about it. Once a merchant connects their Play Console via
+     * MMP-069, server-side reconciliation takes over and the override
+     * becomes optional.
+     *
+     * On iOS this is **ignored** — `AppTransaction` / receipt URL are
+     * authoritative. We log a console warning when an override is passed
+     * on iOS so the discrepancy is visible during development; the
+     * server stamps `releaseChannelSource: "auto"` regardless.
+     */
+    releaseChannel?: ReleaseChannel;
+}
+/**
+ * Options for {@link ApexCapacitorPlugin.identify}.
+ *
+ * Phase 2-SDK (council-revised mobile dashboard plan). Identify is the
+ * explicit, first-class call merchants use to bind a known user to the
+ * current visitor session. The server resolves the email (and optional
+ * userId) to an Apex Contact and stamps `verifiedAt = now`, promoting
+ * any previously-quarantined Contact for this visitor + lighting up
+ * affiliate stamping, scoring, and journey dispatch.
+ *
+ * This is intentionally distinct from `track({ type: "user_signed_up",
+ * data: { email } })`. Track is a fire-and-forget event; identify is
+ * the durable identity gesture. The two interact: a server-side
+ * auto-stitch on `user_signed_up` lands the Contact in quarantine; an
+ * `identify()` call promotes it to verified.
+ */
+export interface IdentifyOptions {
+    /**
+     * Email address — the canonical identifier Apex uses to merge
+     * anonymous visitor sessions into a known Contact. Required.
+     */
+    email: string;
+    /**
+     * Optional merchant-side stable user id (e.g. a row id from the
+     * merchant's user table). When provided, Apex stores it on the
+     * Contact so cross-platform stitching can use both email + userId.
+     */
+    userId?: string;
+    /**
+     * Optional metadata to attach to the identify event (e.g. signup
+     * source, plan tier, locale). Merged into the Contact's traits.
+     */
+    traits?: Record<string, unknown>;
 }
 /** Return value of {@link ApexCapacitorPlugin.getAdvertisingId}. */
 export interface AdvertisingIdResult {
@@ -142,6 +253,14 @@ export interface DeviceInfo {
     bundleId: string;
     timezone: string;
     locale: string;
+    /**
+     * MMP-061 — the detected build source (or override). Surfaced so
+     * sample apps + developer-facing UIs can show a "Running: TestFlight"
+     * badge without round-tripping to the server.
+     */
+    releaseChannel?: ReleaseChannel;
+    /** How {@link DeviceInfo.releaseChannel} was determined. */
+    releaseChannelSource?: ReleaseChannelSource;
 }
 /** Summary of offline-queue state. */
 export interface QueueStatus {
@@ -211,8 +330,12 @@ export interface ApexCapacitorPlugin {
      * listener AND is auto-registered with Apex via `POST /api/mobile/push-token`
      * so the dashboard sees it immediately.
      *
-     * On Android (FCM) and on web this is currently a no-op returning
-     * `permission: "denied"`. Android FCM ships in a follow-up.
+     * On Android this fetches the FCM registration token via
+     * `FirebaseMessaging`, auto-registers it with Apex via
+     * `POST /api/mobile/push-token`, and fires `pushTokenReceived`. (The
+     * app must include a `google-services.json` and the host must be a
+     * Firebase project.) On web this remains a no-op returning
+     * `permission: "denied"`.
      */
     registerForPushNotifications(): Promise<PushRegistrationResult>;
     /**
@@ -243,6 +366,23 @@ export interface ApexCapacitorPlugin {
     setVisitorId(options: {
         visitorId: string;
     }): Promise<void>;
+    /**
+     * Identifies the current visitor as a known user. Resolves the email
+     * to an Apex Contact (creating it if needed) and stamps the
+     * resulting Contact as `verified` so downstream pipelines (affiliate
+     * stamping, scoring, journey dispatch) can run.
+     *
+     * Typical placement:
+     *   - Right after a user submits a signup form
+     *   - Right after a user signs in
+     *   - On app start when a known authenticated user is hydrated from
+     *     your auth provider
+     *
+     * Idempotent — calling identify with the same email + visitor is
+     * safe. The server rate-limits per visitor (1 req/sec) to prevent
+     * identity-flip-flop attacks.
+     */
+    identify(options: IdentifyOptions): Promise<void>;
     /**
      * Updates the SKAdNetwork 4.0 postback conversion value. No-op on Android.
      * `fineValue` is 0-63 (fine conversion value); `coarseValue` is optional