@cxpinsight/react-native 0.2.0

package/lib/CXPinsight.js

@@ -0,0 +1,831 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CXPinsight = void 0;
+const types_1 = require("./types");
+const storage = __importStar(require("./core/storage"));
+const network_1 = require("./core/network");
+const deviceInfo_1 = require("./core/deviceInfo");
+const session_1 = require("./core/session");
+const eventQueue_1 = require("./core/eventQueue");
+const frequencyCap_1 = require("./survey/frequencyCap");
+const variablesResolver_1 = require("./survey/variablesResolver");
+const triggerEngine_1 = require("./core/triggerEngine");
+const SetupController_1 = require("./setup/SetupController");
+const recorder = __importStar(require("./core/mobileRecorder"));
+const interactionObserver_1 = require("./instrumented/interactionObserver");
+const lifecycle_1 = require("./core/lifecycle");
+const networkCapture_1 = require("./core/networkCapture");
+const scrollCapture_1 = require("./core/scrollCapture");
+// Canonical eventType per event name — keeps mobile events aligned with the shared
+// engagement taxonomy (docs/engagement-vocabulary-v1.md) instead of everything being
+// 'user_action'. Unknown names fall back to 'user_action'.
+const EVENT_TYPE_BY_NAME = {
+    screen_view: 'page_view', page_view: 'page_view',
+    click: 'click', button_click: 'click', link_click: 'click', element_click: 'click',
+    scroll: 'engagement', swipe: 'engagement', engagement: 'engagement',
+    form_start: 'form', form_submit: 'form', form_field: 'form', form_abandon: 'form',
+    app_opened: 'navigation', app_foregrounded: 'navigation', app_backgrounded: 'navigation',
+    app_installed: 'navigation', app_updated: 'navigation', session_start: 'navigation', first_open: 'navigation',
+    error: 'error', crash: 'error',
+    search: 'search', file_download: 'file', purchase: 'ecommerce', add_to_cart: 'ecommerce',
+};
+class CXPinsightSDK {
+    constructor() {
+        this.initialized = false;
+        this.config = null;
+        this.callbacks = {};
+        this.userId = '';
+        // In-memory mirror of the last identify() call. Storage layer is
+        // AsyncStorage (async I/O) so a synchronous accessor is needed for
+        // the variables resolver — which runs on every render tick.
+        // Rehydrated from storage on init() below.
+        this.userIdentity = null;
+        this.surveyPresenter = null;
+        this.setupPresenter = null;
+        // Unsubscribe for the auto-event interaction listener (taps/scroll/focus → events).
+        this.autoEventUnsub = null;
+        // Current + previous screen, so click/scroll/screen_view events carry screenName.
+        this.currentScreen = null;
+        this.previousScreen = null;
+        // Engagement clock — active foreground time this session (paused while backgrounded),
+        // attached to every event as engagementTimeMs (parity with web's time-on-page).
+        this.engagementStartTs = 0;
+        this.engagementAccumMs = 0;
+        this.engagementActive = false;
+    }
+    startEngagementClock() { this.engagementStartTs = Date.now(); this.engagementAccumMs = 0; this.engagementActive = true; }
+    pauseEngagementClock() { if (this.engagementActive) {
+        this.engagementAccumMs += Date.now() - this.engagementStartTs;
+        this.engagementActive = false;
+    } }
+    resumeEngagementClock() { if (!this.engagementActive) {
+        this.engagementStartTs = Date.now();
+        this.engagementActive = true;
+    } }
+    getEngagementMs() { return this.engagementAccumMs + (this.engagementActive ? Date.now() - this.engagementStartTs : 0); }
+    /** Initialize the SDK. Call once at app startup. */
+    async init(config, callbacks) {
+        if (this.initialized) {
+            this.log('Already initialized');
+            return;
+        }
+        if (!config.applicationId) {
+            throw new Error('[CXPinsight] init requires config.applicationId');
+        }
+        this.config = config;
+        (0, deviceInfo_1.setDeviceTheme)(config.theme); // host user's theme preference → deviceInfo.theme → device.theme
+        (0, deviceInfo_1.setDeviceBrandingPalette)(config.brandingPalette, config.primaryColor); // app palette + accent → deviceInfo.themePalette → reported-themes panel
+        this.callbacks = callbacks ?? {};
+        // Configure network layer
+        (0, network_1.configureNetwork)(config);
+        // P1 — server-driven SDK behavior. Fetch the Site's SdkConfig and fill any
+        // capture/session/batching setting the app didn't explicitly pass to init(),
+        // so behavior can change from the dashboard without an app redeploy. Client
+        // init() flags always win (only undefined fields are filled). Bounded + fail-
+        // safe: a slow/failed fetch leaves config untouched so init never blocks.
+        // Must run BEFORE initSession/startQueue/recording below consume `config`.
+        await this.applyServerSdkConfig(config);
+        // Restore or generate userId
+        const savedUserId = await storage.get(types_1.STORAGE_KEYS.USER_ID);
+        if (savedUserId) {
+            this.userId = savedUserId;
+        }
+        else {
+            this.userId = `cxp_user_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+            await storage.set(types_1.STORAGE_KEYS.USER_ID, this.userId);
+        }
+        // Rehydrate the identity blob so {{variable}} refs sourced from
+        // SDK identify() work on the first survey after a cold start —
+        // otherwise the user has to call identify() every launch for
+        // personalization to hold.
+        const savedIdentity = await storage.get(types_1.STORAGE_KEYS.USER_IDENTITY);
+        if (savedIdentity)
+            this.userIdentity = savedIdentity;
+        // Start session
+        await (0, session_1.initSession)(config.sessionTimeout);
+        // Start event queue
+        await (0, eventQueue_1.startQueue)({
+            flushInterval: config.flushInterval,
+            flushThreshold: config.flushThreshold,
+            debug: config.debug,
+        });
+        this.initialized = true;
+        this.log('Initialized', { applicationId: config.applicationId, userId: this.userId });
+        // Non-blocking connectivity self-check — surfaces a precise message on a bad apiBase
+        // (wrong port, a service instead of the gateway, or localhost on a physical device)
+        // instead of a generic "could not connect to server" later.
+        void this.verifyConnectivity(config.apiBase);
+        // Start mobile session (timeline) recording when opted in via config. Hosts
+        // that gate on their own consent UI should omit `record` and call
+        // CXPinsight.startRecording() after consent instead.
+        if (config.record) {
+            recorder.startRecording({
+                sessionId: (0, session_1.getSessionId)(),
+                userId: this.userId,
+                applicationId: config.applicationId,
+                sampleRate: config.recordingSampleRate,
+                maskInputs: config.recordMaskInputs,
+                captureScreen: config.captureScreen,
+            }).catch(err => this.log('Failed to start recording:', err));
+        }
+        // Load remote trigger configs (non-blocking).
+        (0, triggerEngine_1.loadTriggerConfigs)(config.applicationId, config.debug).catch(err => {
+            this.log('Failed to load trigger configs:', err);
+        });
+        // Restore setup mode if it was active when app was killed (non-blocking)
+        (0, SetupController_1.restoreSetupState)(config.debug).catch(err => {
+            this.log('Failed to restore setup state:', err);
+        });
+        // Auto-emit typed engagement events from native signals so a mobile session
+        // produces the same event vocabulary as web (docs/engagement-vocabulary-v1.md).
+        // No app code beyond the instrumented components + provider screenName.
+        this.startAutoEvents();
+        // Start the engagement clock and emit session_start for a genuinely new session
+        // (navigation, parity with web) — not on a restored/continued session.
+        this.startEngagementClock();
+        if ((0, session_1.wasSessionNew)()) {
+            // Cross-platform parity — first_visit (mobile equivalent of the web SDK's
+            // one). Absence of RETURNING_USER = brand-new install; emit first_visit
+            // BEFORE session_start (so downstream reads see the first-visit marker
+            // as part of the same session's initial event stream, matching web).
+            let isFirstVisit = false;
+            try {
+                const flag = await storage.get(types_1.STORAGE_KEYS.RETURNING_USER);
+                isFirstVisit = !flag;
+                if (isFirstVisit) {
+                    this.track('first_visit', {}, 'navigation', false);
+                    await storage.set(types_1.STORAGE_KEYS.RETURNING_USER, '1');
+                }
+            }
+            catch (e) { /* AsyncStorage failure — non-fatal, skip first_visit */ }
+            this.track('session_start', {
+                sessionId: (0, session_1.getSessionId)(),
+                is_first_visit: isFirstVisit,
+            }, 'navigation', false);
+        }
+        // When an inactive session rolls over to a new one, start a fresh recording so a
+        // session maps to one recording (prevents an ever-growing single recording).
+        (0, session_1.setRolloverHandler)((newSessionId, prevSessionId) => {
+            void this.onSessionRollover(newSessionId, prevSessionId);
+        });
+    }
+    /**
+     * P1 — merge the server's canonical SdkConfig into `config`, filling only the
+     * flat init() fields the app left undefined (client always wins). Bounded to a
+     * short timeout so a slow network never stalls init; any failure is swallowed
+     * and the app's config/defaults stand. Runs before the capture/session/queue
+     * consumers in init().
+     */
+    async applyServerSdkConfig(config) {
+        if (!config.applicationId)
+            return;
+        const scopeQs = `applicationId=${encodeURIComponent(config.applicationId)}`;
+        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), 2500));
+        try {
+            const res = await Promise.race([
+                (0, network_1.sdkFetch)('GET', `/api/engagement/setup/sdk-config?${scopeQs}`),
+                timeout,
+            ]);
+            // sdkFetch already unwraps the HTTP layer into { success, data: <body> }, and
+            // the body is itself the API envelope { success, data: SrvCfg } — so the config
+            // sits one level deeper than `res.data`. Reading `res.data` directly (the prior
+            // behaviour) always yielded the envelope, so every field below resolved to
+            // undefined and no dashboard setting ever reached a mobile app.
+            // Accept either shape: prefer the nested envelope, fall back to a flat body so a
+            // future unwrapped endpoint keeps working.
+            const body = res && res.success ? res.data : null;
+            if (!body || typeof body !== 'object')
+                return;
+            const s = (body.data && typeof body.data === 'object')
+                ? body.data
+                : body;
+            if (!s || typeof s !== 'object')
+                return;
+            // Only fill fields the app didn't set — init() flags take precedence.
+            if (config.record === undefined && typeof s.recording?.enabled === 'boolean')
+                config.record = s.recording.enabled;
+            if (config.recordMaskInputs === undefined && typeof s.recording?.maskInputs === 'boolean')
+                config.recordMaskInputs = s.recording.maskInputs;
+            // Recording sample rate — always take the server's value if present. Unlike
+            // enabled/maskInputs there's no init() equivalent (sampling is a dashboard-side
+            // control), so this is the only source. Stashed on `config` so both the initial
+            // startRecording and the rollover path can read it without another fetch.
+            if (typeof s.recording?.sampleRate === 'number')
+                config.recordingSampleRate = s.recording.sampleRate;
+            if (config.captureNetwork === undefined && typeof s.capture?.network === 'boolean')
+                config.captureNetwork = s.capture.network;
+            if (config.sessionTimeout === undefined && typeof s.session?.timeoutMs === 'number')
+                config.sessionTimeout = s.session.timeoutMs;
+            if (config.flushInterval === undefined && typeof s.batching?.flushIntervalMs === 'number')
+                config.flushInterval = s.batching.flushIntervalMs;
+            if (config.flushThreshold === undefined && typeof s.batching?.flushThreshold === 'number')
+                config.flushThreshold = s.batching.flushThreshold;
+            this.log('Applied server SdkConfig');
+        }
+        catch (err) {
+            this.log('Server SdkConfig fetch failed — using init/defaults:', err);
+        }
+    }
+    /** Roll the recording + engagement clock onto a freshly-started session. */
+    async onSessionRollover(newSessionId, prevSessionId) {
+        this.log('Session rolled over (inactivity):', prevSessionId, '->', newSessionId);
+        if (this.config?.record) {
+            try {
+                await recorder.stopRecording(); // finalize the previous recording
+                await recorder.startRecording({
+                    sessionId: newSessionId,
+                    userId: this.userId,
+                    applicationId: this.config.applicationId,
+                    sampleRate: this.config.recordingSampleRate,
+                    maskInputs: this.config.recordMaskInputs,
+                    captureScreen: this.config.captureScreen,
+                });
+            }
+            catch (e) {
+                this.log('recording rollover failed', e);
+            }
+        }
+        this.startEngagementClock(); // reset engagement time for the new session
+        this.track('session_start', { sessionId: newSessionId }, 'navigation', false);
+    }
+    /** Wire native signals → typed analytics events (shared taxonomy). */
+    startAutoEvents() {
+        // Scroll depth from the app's ORGANIC <ScrollView>s (and FlatList /
+        // SectionList, which are built on one). Previously this required the app to
+        // import the SDK's instrumented ScrollView instead of React Native's —
+        // app-code restructuring the install snippet shouldn't demand. Without it
+        // `percent_scrolled` was always 0, so scroll-depth definitions never fired.
+        // Returns false if RN internals have moved; capture is simply off then.
+        if (!(0, scrollCapture_1.installScrollCapture)()) {
+            this.log('Scroll capture unavailable on this React Native version');
+        }
+        // Interactions → click / engagement / form events. tee=false: these are already
+        // in the recording as interaction frames, so don't duplicate them there.
+        this.autoEventUnsub = (0, interactionObserver_1.setInteractionListener)((e) => {
+            if ((0, SetupController_1.isSetupActive)())
+                return; // don't emit during element-mapping/setup
+            const r = e;
+            // Prefer the human-readable label for `element_text`; fall back to testID/
+            // text so at least SOMETHING is bindable even without an accessibilityLabel.
+            const label = (r.label ?? r.accessibilityLabel ?? r.text);
+            // Cross-platform normalization: emit the SAME wire shape the web SDK uses so
+            // one signature collapses web + mobile fires of the same interaction into a
+            // single observed-event row. Field naming matches services/unified-sdk/src/
+            // engagement.js:973-984 (element_text / element_tag / element_role / etc.).
+            const page = this.currentScreen ?? undefined;
+            switch (e.interactionType) {
+                case 'tap':
+                case 'long_press':
+                    // Web click carries: element_text, element_tag, element_role,
+                    // element_testid, element_id, element_selector, element_classes, link_url,
+                    // link_domain, is_outbound. Mobile has direct analogues for the first
+                    // five — populate them so a "element_testid = 'signup_btn'" condition
+                    // matches on either channel.
+                    this.track('click', {
+                        element_text: label,
+                        element_tag: r.elementType, // 'button' | 'text_input' | …
+                        element_role: r.accessibilityRole, // 'button' | 'link' | …
+                        element_testid: r.testID, // stable dev-assigned id
+                        element_id: r.nativeID, // native id fallback
+                        element_selector: r.hierarchyPath, // last-resort path (mobile analogue of CSS selector)
+                        interaction_type: e.interactionType, // 'tap' | 'long_press' — internal detail
+                        page,
+                    }, 'click', false);
+                    break;
+                case 'scroll':
+                case 'swipe': {
+                    // ScrollView emits "<pct>%" in text. Field name matches web's
+                    // `percent_scrolled` (engagement.js:1030) so a scroll-threshold
+                    // condition works on either channel.
+                    const pct = parseInt(String(r.text ?? '0'), 10);
+                    this.track(e.interactionType, {
+                        percent_scrolled: Number.isFinite(pct) ? pct : 0,
+                        page,
+                    }, 'engagement', false);
+                    break;
+                }
+                case 'focus':
+                    // Web's `form_start` fires only inside a real <form> element. Mobile
+                    // has no <form> concept — any input focus was firing this event, which
+                    // was semantically wrong and collided with web on the signature. Rename
+                    // to `input_focus` (eventType `engagement`) so the two don't false-match.
+                    this.track('input_focus', {
+                        element_text: label,
+                        element_testid: r.testID,
+                        element_role: r.accessibilityRole,
+                        page,
+                    }, 'engagement', false);
+                    break;
+                // value_change / blur → captured in the recording only, no analytics event
+            }
+        });
+        // App lifecycle → navigation events (app_opened / foregrounded / backgrounded).
+        // Also pause/resume the engagement clock so time-on-app excludes backgrounded time.
+        (0, lifecycle_1.startLifecycleTracking)((evt) => {
+            if (evt.type === 'app_backgrounded')
+                this.pauseEngagementClock();
+            else if (evt.type === 'app_foregrounded')
+                this.resumeEngagementClock();
+            this.track(evt.type, evt.data, 'navigation', false);
+        });
+        // Network capture → sanitized api_call events (method/host/path/status/duration).
+        // On by default; set captureNetwork:false to disable.
+        if (this.config?.captureNetwork !== false) {
+            this.log('Network capture enabled');
+            (0, networkCapture_1.startNetworkCapture)(this.config.apiBase, (call) => {
+                this.log('api_call captured:', call.method, call.path, call.status);
+                // Static eventName `api_call` (was `"${METHOD} ${PATH}"` — dynamic per URL,
+                // which exploded the observed-events catalog into thousands of unique
+                // rows). Method/host/path stay in eventData so conditions like
+                // `method = POST AND path contains /checkout` still work.
+                this.track('api_call', {
+                    method: call.method, host: call.host, path: call.path,
+                    status: call.status, durationMs: call.durationMs, success: call.success,
+                }, 'api_call', false);
+            });
+        }
+        // Uncaught JS errors → error events. Install once; chain the previous handler.
+        if (!CXPinsightSDK.errorHandlerInstalled) {
+            try {
+                const EU = globalThis.ErrorUtils;
+                if (EU?.setGlobalHandler) {
+                    const prev = EU.getGlobalHandler?.();
+                    EU.setGlobalHandler((error, isFatal) => {
+                        try {
+                            const err = error;
+                            this.track('error', { message: String(err?.message ?? error), fatal: !!isFatal, stack: String(err?.stack ?? '').slice(0, 800) }, 'error', false);
+                        }
+                        catch { /* never let telemetry mask the real error */ }
+                        prev?.(error, isFatal);
+                    });
+                    CXPinsightSDK.errorHandlerInstalled = true;
+                }
+            }
+            catch { /* ErrorUtils not available on this platform */ }
+        }
+    }
+    /** Track a custom event */
+    /**
+     * One-shot reachability check of `apiBase` at init. Logs a precise, actionable
+     * warning for the common misconfigurations (frontend port, a service instead of the
+     * gateway, or localhost on a physical device). Never throws or blocks init.
+     */
+    async verifyConnectivity(apiBase) {
+        const base = (apiBase || '').replace(/\/+$/, '');
+        if (!base) {
+            console.warn('[CXPinsight] apiBase is not set — point it at your CXPinsight gateway URL (e.g. http://<your-LAN-IP>:3000). No data will be sent.');
+            return;
+        }
+        if (/\/\/(localhost|127\.0\.0\.1)([:/]|$)/.test(base)) {
+            console.warn(`[CXPinsight] apiBase is "${base}". In a native app "localhost" is the device itself — on a physical device use your machine's LAN IP instead (e.g. http://192.168.x.x:3000).`);
+        }
+        try {
+            const controller = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
+            const timer = controller ? setTimeout(() => controller.abort(), 5000) : undefined;
+            const res = await fetch(`${base}/health`, { method: 'GET', signal: controller?.signal });
+            if (timer)
+                clearTimeout(timer);
+            const type = res.headers.get('content-type') || '';
+            if (!type.includes('application/json')) {
+                console.warn(`[CXPinsight] apiBase "${base}" returned ${type || 'a non-JSON response'} from /health — this looks like a frontend/dev server, not the CXPinsight gateway. Point apiBase at the gateway (usually :3000).`);
+                return;
+            }
+            const body = await res.json().catch(() => null);
+            if (body && body.service && body.service !== 'gateway') {
+                console.warn(`[CXPinsight] apiBase "${base}" points at the "${body.service}" service, not the gateway. Point apiBase at your CXPinsight gateway (usually :3000) so /api/engagement routes resolve.`);
+                return;
+            }
+            this.log('Connectivity OK →', base);
+        }
+        catch (err) {
+            const msg = err?.message || String(err);
+            console.warn(`[CXPinsight] Could not reach apiBase "${base}" (${msg}). It must be your CXPinsight gateway (usually :3000), reachable from the device — on a physical device use your machine's LAN IP, not localhost.`);
+        }
+    }
+    track(eventName, data, eventType, teeToRecording = true) {
+        if (!this.initialized || !this.config) {
+            console.warn('[CXPinsight] track() called but SDK not initialized — call ignored. Event:', eventName);
+            return;
+        }
+        (0, session_1.touchSession)();
+        const device = (0, deviceInfo_1.getDeviceInfo)();
+        const now = new Date().toISOString();
+        // Explicit type wins; otherwise derive from the shared taxonomy by name.
+        const resolvedType = eventType || EVENT_TYPE_BY_NAME[eventName] || 'user_action';
+        // Identified user traits (from identify()) to stamp on EVERY event — including the
+        // auto-captured taps/scrolls from the instrumented setup, which route through track().
+        // Excludes `id` (that's the userId). Omitted entirely until identify() is called.
+        let userProperties;
+        if (this.userIdentity) {
+            const { id: _id, ...traits } = this.userIdentity;
+            if (Object.keys(traits).length)
+                userProperties = traits;
+        }
+        const event = {
+            userId: this.userId,
+            sessionId: (0, session_1.getSessionId)(),
+            applicationId: this.config.applicationId,
+            eventType: resolvedType,
+            eventName,
+            // No redundant `context` blob — device/os/screen/etc. are on `deviceInfo`
+            // (canonical shape), so eventData carries only event-specific attributes.
+            eventData: {
+                source: 'cxpinsight_mobile_sdk',
+                ...data,
+            },
+            deviceInfo: device,
+            timestamp: now,
+            // Active foreground time this session (parity with web's engagementTimeMs).
+            engagementTimeMs: this.getEngagementMs(),
+            ...(userProperties ? { userProperties } : {}),
+        };
+        (0, eventQueue_1.enqueue)(event);
+        this.callbacks.onEventTracked?.(eventName);
+        // Tee into the session recording timeline as an 'event' frame — but only for
+        // custom business events. Auto-events (click/scroll/screen_view) are already in
+        // the recording as interaction/screen frames, so teeing them would duplicate.
+        if (teeToRecording && recorder.isRecording() && eventName !== 'screen_view') {
+            recorder.recordFrame('event', { name: eventName });
+        }
+        // P2c — evaluate targeting conditions against the full ATTRIBUTE CONTEXT, not
+        // just event data: bare event keys (legacy conditions like scrollPercent) PLUS
+        // the namespaced bag (event.* / device.* / user.* / session.*) so a rule can
+        // target `user.plan == 'pro'` or `device.os == 'iOS'`. geo.* is server-only and
+        // absent here — the trigger engine skips those (finalized server-side in P3).
+        const targetingContext = {
+            ...event.eventData,
+            ...(0, variablesResolver_1.buildAttributeContext)({
+                event: event.eventData,
+                // Canonical device.* keys (type/model/brand, lowercased) so the client-side
+                // targeting context matches the server's eventAttributes() vocabulary — a
+                // rule authored as `device.type == 'mobile'` then resolves in both tiers.
+                device: (0, deviceInfo_1.canonicalDeviceContext)(device),
+                user: userProperties,
+                session: { engagementMs: event.engagementTimeMs, id: event.sessionId },
+            }),
+        };
+        (0, triggerEngine_1.onEventTracked)(eventName, targetingContext);
+    }
+    /** Track a screen view (triggers remote page_view rules) */
+    trackScreen(screenName, data) {
+        // Roll current → previous so page_view (and downstream click/scroll) carry both.
+        this.previousScreen = this.currentScreen;
+        this.currentScreen = screenName;
+        if (recorder.isRecording())
+            recorder.recordScreen(screenName, this.previousScreen);
+        // Cross-platform normalization: emit as `page_view` (web's canonical navigation
+        // event name) so the eventSignature (eventType|page|elementKey) collapses web
+        // and mobile navigations to the same key when they share a page identifier.
+        // `page` is the canonical field the backend's eventPage() reads for the
+        // signature; screen_name is preserved as a mobile-side alias.
+        this.track('page_view', {
+            page: screenName,
+            screen_name: screenName,
+            previous_page: this.previousScreen ?? undefined,
+            ...data,
+        }, 'page_view', false);
+        (0, triggerEngine_1.onScreenView)(screenName).catch(err => {
+            console.error('[CXPinsight] onScreenView error:', err);
+        });
+    }
+    /** Identify the current user */
+    async identify(user) {
+        const prevId = this.userId;
+        // If we were anonymous, merge the pre-login activity into this user. Without this,
+        // events sent before identify() (session_start, first screen views, etc.) stay under
+        // the anonymous id and the visitor shows up as TWO customers with split event counts.
+        if (prevId && prevId !== user.id && prevId.startsWith('cxp_user_')) {
+            try {
+                // Flush queued anonymous events first so the backend has them to re-attribute.
+                await (0, eventQueue_1.flush)();
+                await (0, network_1.sdkFetch)('POST', '/api/engagement/events/alias', {
+                    anonymousId: prevId,
+                    userId: user.id,
+                });
+                this.log('Aliased anonymous id -> user', prevId, user.id);
+            }
+            catch (e) {
+                this.log('alias failed', e);
+            }
+        }
+        this.userId = user.id;
+        this.userIdentity = user;
+        await storage.set(types_1.STORAGE_KEYS.USER_ID, user.id);
+        await storage.set(types_1.STORAGE_KEYS.USER_IDENTITY, user);
+        this.log('User identified', user.id);
+    }
+    /** Track a funnel step */
+    trackFunnelStep(funnelId, stepNumber, stepName, options) {
+        if (!this.initialized || !this.config) {
+            console.warn('[CXPinsight] trackFunnelStep() called but SDK not initialized');
+            return;
+        }
+        (0, session_1.touchSession)();
+        const device = (0, deviceInfo_1.getDeviceInfo)();
+        const now = new Date().toISOString();
+        const opts = options ?? {};
+        const event = {
+            userId: this.userId,
+            sessionId: (0, session_1.getSessionId)(),
+            applicationId: this.config.applicationId,
+            eventType: 'conversion',
+            eventName: 'funnel_step',
+            eventData: {
+                source: 'cxpinsight_mobile_sdk',
+            },
+            deviceInfo: device,
+            timestamp: now,
+            eventTemplate: 'funnel_step',
+            funnel: {
+                funnel_id: funnelId,
+                funnel_name: opts.funnelName ?? funnelId,
+                step_number: stepNumber,
+                step_name: stepName ?? `Step ${stepNumber}`,
+                is_conversion: opts.isConversion,
+            },
+            value: opts.value,
+            currency: opts.currency,
+        };
+        (0, eventQueue_1.enqueue)(event);
+        this.callbacks.onEventTracked?.('funnel_step');
+        this.log('Funnel step tracked:', funnelId, stepNumber);
+    }
+    /** Track an experiment impression */
+    trackExperiment(experimentId, variantId, options) {
+        if (!this.initialized || !this.config) {
+            console.warn('[CXPinsight] trackExperiment() called but SDK not initialized');
+            return;
+        }
+        (0, session_1.touchSession)();
+        const device = (0, deviceInfo_1.getDeviceInfo)();
+        const now = new Date().toISOString();
+        const opts = options ?? {};
+        const event = {
+            userId: this.userId,
+            sessionId: (0, session_1.getSessionId)(),
+            applicationId: this.config.applicationId,
+            eventType: 'experiment',
+            eventName: 'experiment_impression',
+            eventData: {
+                source: 'cxpinsight_mobile_sdk',
+            },
+            deviceInfo: device,
+            timestamp: now,
+            eventTemplate: 'experiment_impression',
+            experiment: {
+                experiment_id: experimentId,
+                experiment_name: opts.experimentName ?? experimentId,
+                variant_id: variantId,
+                variant_name: opts.variantName ?? variantId,
+                assignment_method: opts.assignmentMethod ?? 'random',
+            },
+        };
+        (0, eventQueue_1.enqueue)(event);
+        this.callbacks.onEventTracked?.('experiment_impression');
+        this.log('Experiment tracked:', experimentId, variantId);
+    }
+    /** Track a conversion event */
+    trackConversion(eventName, options) {
+        if (!this.initialized || !this.config) {
+            console.warn('[CXPinsight] trackConversion() called but SDK not initialized');
+            return;
+        }
+        (0, session_1.touchSession)();
+        const device = (0, deviceInfo_1.getDeviceInfo)();
+        const now = new Date().toISOString();
+        const opts = options ?? {};
+        const event = {
+            userId: this.userId,
+            sessionId: (0, session_1.getSessionId)(),
+            applicationId: this.config.applicationId,
+            eventType: 'conversion',
+            eventName,
+            eventData: {
+                source: 'cxpinsight_mobile_sdk',
+            },
+            deviceInfo: device,
+            timestamp: now,
+            value: opts.value,
+            currency: opts.currency,
+        };
+        // Attach experiment context if provided
+        if (opts.experimentId) {
+            event.experiment = {
+                experiment_id: opts.experimentId,
+                experiment_name: opts.experimentName ?? opts.experimentId,
+                variant_id: opts.variantId ?? '',
+                variant_name: opts.variantName ?? '',
+            };
+        }
+        // Attach funnel context if provided
+        if (opts.funnelId) {
+            event.funnel = {
+                funnel_id: opts.funnelId,
+                funnel_name: opts.funnelName ?? opts.funnelId,
+                step_number: opts.stepNumber ?? 1,
+                step_name: opts.stepName ?? 'Conversion',
+                is_conversion: true,
+            };
+        }
+        (0, eventQueue_1.enqueue)(event);
+        this.callbacks.onEventTracked?.(eventName);
+        this.log('Conversion tracked:', eventName, opts);
+    }
+    // ── Setup Mode API ──
+    /** Enter setup mode. Shows the setup code entry UI. */
+    enterSetupMode() {
+        if (!this.initialized || !this.config) {
+            console.warn('[CXPinsight] enterSetupMode() called but SDK not initialized');
+            return;
+        }
+        if (this.setupPresenter) {
+            this.setupPresenter(true);
+        }
+        else {
+            this.log('No setup presenter registered. Wrap your app with <CXPinsightProvider>.');
+        }
+    }
+    /** Exit setup mode and clean up. */
+    async exitSetupMode() {
+        await (0, SetupController_1.endSetup)();
+        if (this.setupPresenter) {
+            this.setupPresenter(false);
+        }
+    }
+    /** Check if setup mode is currently active. */
+    isInSetupMode() {
+        return (0, SetupController_1.isSetupActive)();
+    }
+    /** Get the current setup session state. */
+    getSetupState() {
+        return (0, SetupController_1.getSetupState)();
+    }
+    /** Get the stable device ID (generates one if first time). */
+    async getDeviceId() {
+        return (0, SetupController_1.getDeviceId)();
+    }
+    /** Programmatically show a survey */
+    showSurvey(surveyId) {
+        if (!this.surveyPresenter) {
+            this.log('No survey presenter registered. Wrap your app with <CXPinsightProvider>.');
+            return;
+        }
+        this.surveyPresenter(surveyId);
+    }
+    /**
+     * Start mobile session (timeline) recording. Use this when gating on your own
+     * consent UI: show your banner, then call after the user accepts. No-op if
+     * already recording or the SDK isn't initialized.
+     */
+    async startRecording() {
+        if (!this.initialized || !this.config) {
+            console.warn('[CXPinsight] startRecording() called but SDK not initialized — ignored');
+            return;
+        }
+        await recorder.startRecording({
+            sessionId: (0, session_1.getSessionId)(),
+            userId: this.userId,
+            applicationId: this.config.applicationId,
+            sampleRate: this.config.recordingSampleRate,
+            maskInputs: this.config.recordMaskInputs,
+            captureScreen: this.config.captureScreen,
+        });
+    }
+    /** Stop mobile session recording and flush the final chunk. */
+    async stopRecording() {
+        await recorder.stopRecording();
+    }
+    /** Reset all SDK state (call on logout) */
+    async reset() {
+        this.log('Resetting SDK state');
+        if (this.autoEventUnsub) {
+            this.autoEventUnsub();
+            this.autoEventUnsub = null;
+        }
+        (0, session_1.setRolloverHandler)(null);
+        (0, lifecycle_1.stopLifecycleTracking)();
+        (0, networkCapture_1.stopNetworkCapture)();
+        this.engagementActive = false;
+        this.engagementAccumMs = 0;
+        this.currentScreen = null;
+        this.previousScreen = null;
+        await recorder.stopRecording();
+        await (0, eventQueue_1.flush)();
+        await (0, eventQueue_1.stopQueue)();
+        await (0, session_1.destroySession)();
+        await (0, frequencyCap_1.clearAllCaps)();
+        await (0, triggerEngine_1.clearTriggerState)();
+        await (0, SetupController_1.clearSetupState)();
+        await storage.multiRemove([
+            types_1.STORAGE_KEYS.USER_ID,
+            types_1.STORAGE_KEYS.USER_IDENTITY,
+            types_1.STORAGE_KEYS.SESSION,
+            types_1.STORAGE_KEYS.EVENT_QUEUE,
+        ]);
+        (0, deviceInfo_1.clearDeviceInfoCache)();
+        (0, network_1.resetNetwork)();
+        this.userId = '';
+        this.initialized = false;
+        this.config = null;
+        this.callbacks = {};
+    }
+    /** Manual flush for testing */
+    async flush() {
+        await (0, eventQueue_1.flush)();
+    }
+    /** @internal Register the survey presenter from CXPinsightProvider */
+    _registerSurveyPresenter(presenter) {
+        this.surveyPresenter = presenter;
+    }
+    /** @internal Unregister the survey presenter */
+    _unregisterSurveyPresenter() {
+        this.surveyPresenter = null;
+    }
+    /** @internal Register the setup presenter from CXPinsightProvider */
+    _registerSetupPresenter(presenter) {
+        this.setupPresenter = presenter;
+    }
+    /** @internal Unregister the setup presenter */
+    _unregisterSetupPresenter() {
+        this.setupPresenter = null;
+    }
+    /** @internal Get callbacks */
+    _getCallbacks() {
+        return this.callbacks;
+    }
+    /** @internal Get userId */
+    _getUserId() {
+        return this.userId;
+    }
+    /** @internal Get the full identity blob (or null if identify() was
+     *  never called). Consumed by the variables resolver so
+     *  {source: 'sdk'} v1.1 variables interpolate to identify()-supplied
+     *  values. Return type kept broad ({[k]:unknown}) because the caller
+     *  looks up variable-name keys against it, not typed properties. */
+    _getUserIdentity() {
+        return this.userIdentity;
+    }
+    /** @internal Get config */
+    _getConfig() {
+        return this.config;
+    }
+    /** @internal Host-supplied palette override from CXPinsight.init({ brandingPalette }).
+     *  Read by SurveyModal to layer over survey.branding.palette + defaults.
+     *  Returns null when the app didn't pass one — palette resolver falls back. */
+    _getInitBrandingPalette() {
+        const bp = this.config?.brandingPalette;
+        if (!bp || typeof bp !== 'object')
+            return null;
+        // Cast: types.ts declares this loosely (Partial<Record<string,string>>),
+        // but SurveyModal expects a concrete object shape. Runtime values are
+        // string-keyed maps of hex/rgba color strings.
+        return bp;
+    }
+    /** @internal Check initialization */
+    _isInitialized() {
+        return this.initialized;
+    }
+    log(...args) {
+        if (this.config?.debug) {
+            console.log('[CXPinsight]', ...args);
+        }
+    }
+}
+// The global JS error handler is installed once for the process lifetime.
+CXPinsightSDK.errorHandlerInstalled = false;
+/** Singleton SDK instance */
+exports.CXPinsight = new CXPinsightSDK();
+//# sourceMappingURL=CXPinsight.js.map