getu-attribution-v2-sdk 0.3.1 → 0.3.2

package/dist/core/AttributionSDK.js

@@ -0,0 +1,1034 @@
+import { EventType, Currency, defaultEndpoint, DEFAULT_FIELD_MAPPINGS, } from "../types";
+import { AttributionStorageManager } from "../storage";
+import { EventQueueManager, EventHttpClient } from "../queue";
+import { generateId, getTimestamp, extractUTMParams, getCurrentUrl, getReferrer, getUserAgent, getPageTitle, generateSessionId, isOnline, ConsoleLogger, addUTMToURL, shouldExcludeDomain, isExternalURL, filterUTMParams, cleanURL, getQueryString, getQueryParams, } from "../utils";
+export class AttributionSDK {
+    constructor(config) {
+        this.session = null;
+        this.initialized = false;
+        this.autoTrackEnabled = false;
+        this.pageViewTrackTimes = new Map();
+        this.cachedPublicIP = null;
+        this.publicIPFetchPromise = null;
+        this.initialPageViewTriggered = false;
+        // SPA tracking internals
+        this.spaTrackingEnabled = false;
+        this.lastTrackedPath = "";
+        this.originalPushState = null;
+        this.originalReplaceState = null;
+        this.popstateHandler = null;
+        this.config = {
+            apiEndpoint: defaultEndpoint,
+            batchSize: 100,
+            batchInterval: 2000,
+            maxRetries: 3,
+            retryDelay: 1000,
+            enableDebug: false,
+            autoTrack: false,
+            autoTrackPageView: false,
+            sessionTimeout: 30 * 60 * 1000, // 30 minutes
+            enableCrossDomainUTM: true,
+            crossDomainUTMParams: [
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+            ],
+            excludeDomains: [],
+            autoCleanUTM: true,
+            pageViewDebounceInterval: 5000, // 5 seconds default
+            ...config,
+        };
+        this.logger = new ConsoleLogger(this.config.enableDebug);
+        this.storage = new AttributionStorageManager(this.logger);
+        this.httpClient = new EventHttpClient(this.logger, this.config.apiKey, this.config.apiEndpoint || defaultEndpoint, this.config.maxRetries, this.config.retryDelay);
+        this.queue = new EventQueueManager(this.logger, this.config.apiKey, this.config.apiEndpoint || defaultEndpoint, this.config.batchSize, this.config.batchInterval, this.config.maxRetries, this.config.retryDelay, (events) => this.httpClient.sendEvents(events));
+    }
+    async init() {
+        if (this.initialized) {
+            this.logger.warn("SDK already initialized");
+            return;
+        }
+        try {
+            this.logger.info("Initializing GetuAI Attribution SDK");
+            // Initialize storage in background (IndexedDB failure should not block SDK initialization)
+            void this.storage.init().catch((storageError) => {
+                this.logger.warn("Storage initialization failed (IndexedDB may be unavailable), continuing with basic features:", storageError);
+            });
+            // Initialize user ID (from config or existing storage)
+            this.initializeUserId();
+            // Initialize session
+            this.initializeSession();
+            // Extract and store UTM data from current URL
+            this.extractAndStoreUTMData();
+            // Setup auto-tracking if enabled
+            if (this.config.autoTrack) {
+                this.setupAutoTracking();
+            }
+            // Setup online/offline handlers
+            this.setupNetworkHandlers();
+            // Setup page visibility handlers
+            this.setupVisibilityHandlers();
+            // Setup beforeunload handler
+            this.setupBeforeUnloadHandler();
+            // Mark initialized as early as possible so auto page view can be queued
+            this.initialized = true;
+            this.logger.info("🚀 GetuAI Attribution SDK initialized successfully");
+            this.logger.info("📄 Auto track page view = " + this.config.autoTrackPageView);
+            // Best-effort: retry pending events from last unload/redirect (do not block init)
+            void this.retryPendingEvents().catch((error) => {
+                this.logger.warn("⚠️ Pending events retry failed", error);
+            });
+            // Auto track page view if enabled (independent from autoTrack)
+            // Also enables SPA route tracking automatically
+            if (this.config.autoTrackPageView) {
+                this.logger.info("📄 Auto track page view enabled (including SPA route tracking)");
+                // Record the initial path for SPA tracking
+                this.lastTrackedPath = this.getCurrentPath();
+                // Setup SPA tracking for route changes
+                this.setupSPATracking();
+                // Fire ASAP (microtask) to survive short redirects (e.g. 50ms)
+                if (!this.initialPageViewTriggered) {
+                    this.initialPageViewTriggered = true;
+                    Promise.resolve()
+                        .then(() => this.trackPageView())
+                        .then(() => this.queue.process())
+                        .then(() => {
+                        this.logger.info("✅ Auto track page view completed");
+                    })
+                        .catch((error) => this.logger.error("❌ Auto track page view failed:", error));
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error("Failed to initialize SDK:", error);
+            throw error;
+        }
+    }
+    // Track custom event
+    async trackEvent(eventType, eventData, tracking_user_id, revenue, currency = Currency.USD) {
+        if (!this.initialized) {
+            this.logger.warn("SDK not initialized, event not tracked");
+            return;
+        }
+        try {
+            const currentUrl = getCurrentUrl();
+            // Use cached public IP (best-effort). Do not block tracking on network.
+            const ip_address = this.cachedPublicIP;
+            this.ensurePublicIPFetched();
+            const pageContext = {
+                domain: typeof window !== "undefined" ? window.location.hostname : null,
+                path: typeof window !== "undefined" ? window.location.pathname : null,
+                title: getPageTitle(),
+                referrer: getReferrer(),
+                url: currentUrl.split("?")[0],
+                querystring: getQueryString(currentUrl),
+                query_params: getQueryParams(currentUrl),
+                ip_address: ip_address,
+            };
+            const sessionContext = {
+                session_id: this.session?.sessionId,
+                start_time: this.session?.startTime,
+                last_activity: this.session?.lastActivity,
+                page_views: this.session?.pageViews,
+            };
+            // Use provided tracking_user_id or fallback to stored user ID
+            const finalUserId = tracking_user_id || this.getUserId();
+            const event = {
+                event_id: generateId(),
+                event_type: eventType,
+                tracking_user_id: finalUserId || undefined,
+                timestamp: getTimestamp(),
+                event_data: eventData,
+                context: { page: pageContext, session: sessionContext },
+                revenue: revenue,
+                currency: currency,
+                ...this.getUTMParams(),
+            };
+            this.logger.debug(`Tracking event: ${eventType}`, event);
+            // Add to queue
+            this.queue.add(event);
+        }
+        catch (error) {
+            this.logger.error(`Failed to track event ${eventType}:`, error);
+        }
+    }
+    // Track page view
+    async trackPageView(pageData, tracking_user_id) {
+        const currentUrl = getCurrentUrl();
+        // Use URL without query string as key for debouncing
+        const pageKey = currentUrl.split("?")[0];
+        const now = Date.now();
+        const debounceInterval = this.config.pageViewDebounceInterval || 5000;
+        // Check if this page was tracked recently
+        const lastTrackTime = this.pageViewTrackTimes.get(pageKey);
+        if (lastTrackTime && now - lastTrackTime < debounceInterval) {
+            this.logger.debug(`Page view debounced: ${pageKey} (last tracked ${now - lastTrackTime}ms ago)`);
+            return;
+        }
+        const pageEventData = {
+            url: currentUrl,
+            title: getPageTitle(),
+            referrer: getReferrer(),
+            user_agent: getUserAgent(),
+            ...pageData,
+        };
+        await this.trackEvent(EventType.PAGE_VIEW, pageEventData, tracking_user_id);
+        // Update last track time for this page
+        this.pageViewTrackTimes.set(pageKey, now);
+        // Clean up old entries to prevent memory leak (keep only entries from last hour)
+        this.cleanupPageViewTrackTimes();
+    }
+    // Clean up old page view track times to prevent memory leak
+    cleanupPageViewTrackTimes() {
+        const oneHourAgo = Date.now() - 60 * 60 * 1000;
+        for (const [pageKey, trackTime] of this.pageViewTrackTimes.entries()) {
+            if (trackTime < oneHourAgo) {
+                this.pageViewTrackTimes.delete(pageKey);
+            }
+        }
+    }
+    ensurePublicIPFetched() {
+        if (this.cachedPublicIP || this.publicIPFetchPromise) {
+            return;
+        }
+        this.publicIPFetchPromise = this.fetchPublicIP()
+            .then((ip) => {
+            if (ip) {
+                this.cachedPublicIP = ip;
+            }
+            return ip;
+        })
+            .catch(() => null)
+            .finally(() => {
+            this.publicIPFetchPromise = null;
+        });
+    }
+    // Best-effort fetch of public IP address
+    async fetchPublicIP() {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 2000);
+            const response = await fetch("https://api.ipify.org?format=json", {
+                signal: controller.signal,
+                headers: { Accept: "application/json" },
+            });
+            clearTimeout(timeout);
+            if (!response.ok) {
+                return null;
+            }
+            const data = await response.json();
+            const ip = typeof data?.ip === "string" ? data.ip : null;
+            return ip;
+        }
+        catch (error) {
+            this.logger.debug("Public IP fetch failed", error);
+            return null;
+        }
+    }
+    // Track purchase
+    async trackPurchase(tracking_user_id, revenue, currency = Currency.USD, purchaseData) {
+        await this.trackEvent(EventType.PURCHASE, purchaseData, tracking_user_id, revenue, currency);
+    }
+    // Track login
+    async trackLogin(tracking_user_id, loginData) {
+        await this.trackEvent(EventType.LOGIN, loginData, tracking_user_id);
+    }
+    // Track signup
+    async trackSignup(tracking_user_id, signupData) {
+        await this.trackEvent(EventType.SIGNUP, signupData, tracking_user_id);
+    }
+    // Track form submission
+    async trackFormSubmit(tracking_user_id, formData) {
+        await this.trackEvent(EventType.FORM_SUBMIT, formData, tracking_user_id);
+    }
+    // Track video play
+    async trackVideoPlay(tracking_user_id, videoData) {
+        await this.trackEvent(EventType.VIDEO_PLAY, videoData, tracking_user_id);
+    }
+    // Track email verification
+    async trackEmailVerification(tracking_user_id, verificationData) {
+        await this.trackEvent(EventType.EMAIL_VERIFICATION, verificationData, tracking_user_id);
+    }
+    // Track audit approved (conversion)
+    async trackAuditApproved(tracking_user_id, auditData) {
+        await this.trackEvent(EventType.AUDIT_APPROVED, auditData, tracking_user_id);
+    }
+    // Track purchase with auto user ID (object parameter format)
+    async trackPurchaseAuto(options) {
+        const userId = options.tracking_user_id || this.getUserId();
+        if (!userId) {
+            this.logger.error("❌ trackPurchaseAuto requires tracking_user_id. Please set user ID using setUserId() or pass it in options.tracking_user_id.");
+            return;
+        }
+        await this.trackEvent(EventType.PURCHASE, options.purchaseData, userId, options.revenue, options.currency || Currency.USD);
+    }
+    // Track login with auto user ID (object parameter format)
+    async trackLoginAuto(options) {
+        const userId = options.tracking_user_id || this.getUserId();
+        if (!userId) {
+            this.logger.error("❌ trackLoginAuto requires tracking_user_id. Please set user ID using setUserId() or pass it in options.tracking_user_id.");
+            return;
+        }
+        await this.trackEvent(EventType.LOGIN, options.loginData, userId);
+    }
+    // Track signup with auto user ID (object parameter format)
+    async trackSignupAuto(options) {
+        const userId = options.tracking_user_id || this.getUserId();
+        if (!userId) {
+            this.logger.error("❌ trackSignupAuto requires tracking_user_id. Please set user ID using setUserId() or pass it in options.tracking_user_id.");
+            return;
+        }
+        await this.trackEvent(EventType.SIGNUP, options.signupData, userId);
+    }
+    // Track email verification with auto user ID (object parameter format)
+    async trackEmailVerificationAuto(options) {
+        const userId = options.tracking_user_id || this.getUserId();
+        if (!userId) {
+            this.logger.error("❌ trackEmailVerificationAuto requires tracking_user_id. Please set user ID using setUserId() or pass it in options.tracking_user_id.");
+            return;
+        }
+        await this.trackEvent(EventType.EMAIL_VERIFICATION, options.verificationData, userId);
+    }
+    // Track product view
+    async trackProductView(tracking_user_id, productData) {
+        await this.trackEvent(EventType.PRODUCT_VIEW, productData, tracking_user_id);
+    }
+    // Track add to cart
+    async trackAddToCart(tracking_user_id, cartData) {
+        await this.trackEvent(EventType.ADD_TO_CART, cartData, tracking_user_id);
+    }
+    // Track page click for user click journey
+    async trackPageClick(tracking_user_id, clickData) {
+        await this.trackEvent(EventType.PAGE_CLICK, clickData, tracking_user_id);
+    }
+    // Track button click
+    async trackButtonClick(buttonName, tracking_user_id, clickData) {
+        await this.trackEvent(EventType.BUTTON_CLICK, { button_name: buttonName, ...clickData }, tracking_user_id);
+    }
+    // Get attribution data
+    getAttributionData() {
+        return this.storage.getUTMData();
+    }
+    // Manually add UTM parameters to a URL
+    addUTMToURL(url) {
+        if (!this.config.enableCrossDomainUTM) {
+            return url;
+        }
+        const attributionData = this.getAttributionData();
+        if (!attributionData) {
+            return url;
+        }
+        const utmParams = filterUTMParams(attributionData.lastTouch, this.config.crossDomainUTMParams);
+        return addUTMToURL(url, utmParams);
+    }
+    // Get current UTM parameters as object
+    getCurrentUTMParams() {
+        const attributionData = this.getAttributionData();
+        if (!attributionData) {
+            return {};
+        }
+        return filterUTMParams(attributionData.lastTouch, this.config.crossDomainUTMParams);
+    }
+    // Get UTM parameters for events
+    getUTMParams() {
+        const attributionData = this.getAttributionData();
+        if (!attributionData) {
+            this.logger.debug("No attribution data available for UTM params");
+            return {};
+        }
+        const utmParams = {
+            utm_source: attributionData.lastTouch.utm_source || null,
+            utm_medium: attributionData.lastTouch.utm_medium || null,
+            utm_campaign: attributionData.lastTouch.utm_campaign || null,
+            utm_term: attributionData.lastTouch.utm_term || null,
+            utm_content: attributionData.lastTouch.utm_content || null,
+        };
+        // Filter out empty values and return null for empty strings
+        const filteredParams = {};
+        if (utmParams.utm_source && utmParams.utm_source.trim() !== "") {
+            filteredParams.utm_source = utmParams.utm_source;
+        }
+        else {
+            filteredParams.utm_source = null;
+        }
+        if (utmParams.utm_medium && utmParams.utm_medium.trim() !== "") {
+            filteredParams.utm_medium = utmParams.utm_medium;
+        }
+        else {
+            filteredParams.utm_medium = null;
+        }
+        if (utmParams.utm_campaign && utmParams.utm_campaign.trim() !== "") {
+            filteredParams.utm_campaign = utmParams.utm_campaign;
+        }
+        else {
+            filteredParams.utm_campaign = null;
+        }
+        if (utmParams.utm_term && utmParams.utm_term.trim() !== "") {
+            filteredParams.utm_term = utmParams.utm_term;
+        }
+        else {
+            filteredParams.utm_term = null;
+        }
+        if (utmParams.utm_content && utmParams.utm_content.trim() !== "") {
+            filteredParams.utm_content = utmParams.utm_content;
+        }
+        else {
+            filteredParams.utm_content = null;
+        }
+        this.logger.debug("UTM params for event:", filteredParams);
+        return filteredParams;
+    }
+    // Initialize user ID
+    initializeUserId() {
+        // If userId is provided in config, set it (will override existing)
+        if (this.config.userId) {
+            this.setUserId(this.config.userId);
+            this.logger.info(`👤 User ID initialized from config: ${this.config.userId}`);
+        }
+        else {
+            // Check if user ID already exists in storage
+            const existingUserId = this.getUserId();
+            if (existingUserId) {
+                this.logger.debug(`👤 Existing user ID found: ${existingUserId}`);
+            }
+            else {
+                this.logger.debug("👤 No user ID found, will be set when user identifies");
+            }
+        }
+    }
+    // Set user ID
+    setUserId(userId) {
+        if (!userId || userId.trim() === "") {
+            this.logger.warn("Cannot set empty user ID");
+            return;
+        }
+        this.storage.setUserId(userId);
+        this.logger.info(`👤 User ID set: ${userId}`);
+    }
+    // Get user ID
+    getUserId() {
+        return this.storage.getUserId();
+    }
+    // Remove user ID
+    removeUserId() {
+        this.storage.removeUserId();
+        this.logger.info("👤 User ID removed");
+    }
+    /**
+     * Identify user and set user attributes
+     * Used to explicitly set user information, e.g., after login
+     *
+     * @param userId User unique identifier
+     * @param traits User attributes
+     *
+     * @example
+     * sdk.identify('user-123', {
+     *   email: 'user@example.com',
+     *   name: 'John Doe',
+     *   company_name: 'Acme Inc'
+     * });
+     */
+    async identify(userId, traits) {
+        if (!this.initialized) {
+            this.logger.warn("SDK not initialized, identify call queued");
+            return;
+        }
+        if (!userId || userId.trim() === "") {
+            this.logger.warn("Cannot identify with empty user ID");
+            return;
+        }
+        // Set user ID
+        this.setUserId(userId);
+        // Store user traits
+        if (traits) {
+            this.storage.setUserTraits(traits);
+            this.logger.info(`User identified: ${userId}`, traits);
+        }
+        // Send identify event to backend
+        await this.trackEvent(EventType.FORM_SUBMIT, {
+            _identify: true,
+            _user_traits: traits,
+            tracking_user_id: userId,
+        }, userId);
+    }
+    /**
+     * Get current user traits
+     */
+    getUserTraits() {
+        return this.storage.getUserTraits();
+    }
+    /**
+     * Get current session ID
+     */
+    getSessionId() {
+        return this.session?.sessionId || null;
+    }
+    // Initialize user session
+    initializeSession() {
+        const existingSession = this.storage.getSession();
+        const now = Date.now();
+        if (existingSession &&
+            now - existingSession.lastActivity < this.config.sessionTimeout) {
+            // Extend existing session
+            this.session = {
+                ...existingSession,
+                lastActivity: now,
+            };
+        }
+        else {
+            // Create new session
+            this.session = {
+                sessionId: generateSessionId(),
+                startTime: now,
+                lastActivity: now,
+                pageViews: 0,
+            };
+        }
+        this.storage.storeSession(this.session);
+        this.logger.debug("Session initialized:", this.session);
+    }
+    // Extract and store UTM data from current URL
+    extractAndStoreUTMData() {
+        const currentUrl = getCurrentUrl();
+        const utmParams = extractUTMParams(currentUrl);
+        this.logger.debug("Extracting UTM params from URL:", currentUrl);
+        this.logger.debug("Found UTM params:", utmParams);
+        if (Object.keys(utmParams).length === 0) {
+            this.logger.debug("No UTM parameters found in URL");
+            return;
+        }
+        const utmData = {
+            utm_source: utmParams.utm_source || "",
+            utm_medium: utmParams.utm_medium || "",
+            utm_campaign: utmParams.utm_campaign || "",
+            utm_term: utmParams.utm_term || "",
+            utm_content: utmParams.utm_content || "",
+            timestamp: Date.now(),
+        };
+        const existingData = this.getAttributionData();
+        const newData = {
+            firstTouch: existingData?.firstTouch || utmData,
+            lastTouch: utmData,
+            touchpoints: existingData?.touchpoints || [],
+            expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
+        };
+        // Add to touchpoints if different from last touch
+        if (!existingData ||
+            existingData.lastTouch.utm_source !== utmData.utm_source ||
+            existingData.lastTouch.utm_campaign !== utmData.utm_campaign) {
+            newData.touchpoints.push(utmData);
+        }
+        this.storage.storeUTMData(newData);
+        this.logger.info("UTM data extracted and stored successfully:", utmData);
+        // Clean URL after storing UTM data to avoid displaying parameters in plain text
+        if (this.config.autoCleanUTM) {
+            cleanURL();
+        }
+    }
+    // Setup auto-tracking
+    setupAutoTracking() {
+        this.autoTrackEnabled = true;
+        // Track form interactions
+        this.setupFormTracking();
+        // Track link clicks
+        this.setupLinkTracking();
+        this.logger.info("Auto-tracking enabled");
+    }
+    // Setup form tracking
+    setupFormTracking() {
+        document.addEventListener("submit", (event) => {
+            try {
+                const form = event.target;
+                if (!form) {
+                    return;
+                }
+                const fieldValues = this.serializeFormFields(form);
+                // Extract standardized lead fields
+                const leadFields = this.extractLeadFields(fieldValues);
+                // If email is extracted, automatically store user traits
+                if (leadFields.email) {
+                    this.storage.setUserTraits(leadFields);
+                    this.logger.debug("Lead fields extracted from form:", leadFields);
+                }
+                this.trackEvent(EventType.FORM_SUBMIT, {
+                    ...fieldValues,
+                    // Add standardized lead fields
+                    _lead_fields: leadFields,
+                    form_id: form.id || form.name,
+                    form_action: form.action,
+                    form_method: form.method,
+                });
+            }
+            catch (error) {
+                this.logger.error("Failed to auto-track form submit:", error);
+            }
+        });
+    }
+    // Serialize all fields within a form to a flat key-value map
+    serializeFormFields(form) {
+        const result = {};
+        try {
+            const formData = new FormData(form);
+            // Accumulate multiple values for the same name as arrays
+            for (const [name, value] of formData.entries()) {
+                const serializedValue = this.serializeFormValue(value);
+                if (Object.prototype.hasOwnProperty.call(result, name)) {
+                    const existing = result[name];
+                    if (Array.isArray(existing)) {
+                        existing.push(serializedValue);
+                        result[name] = existing;
+                    }
+                    else {
+                        result[name] = [existing, serializedValue];
+                    }
+                }
+                else {
+                    result[name] = serializedValue;
+                }
+            }
+            // Ensure all fields are represented, including unchecked radios/checkboxes.
+            // For fields without name attribute, use a stable fallback key (id/aria-label/placeholder/index).
+            const elements = Array.from(form.elements);
+            // Group elements by key
+            const nameToElements = new Map();
+            for (let index = 0; index < elements.length; index++) {
+                const el = elements[index];
+                if (el.disabled)
+                    continue;
+                const tagName = el.tagName.toLowerCase();
+                const inputType = el.type?.toLowerCase();
+                if (tagName === "button" ||
+                    inputType === "submit" ||
+                    inputType === "reset") {
+                    continue;
+                }
+                const fieldKey = this.getFormFieldKey(el, index);
+                if (!fieldKey) {
+                    continue;
+                }
+                if (!nameToElements.has(fieldKey))
+                    nameToElements.set(fieldKey, []);
+                nameToElements.get(fieldKey).push(el);
+            }
+            nameToElements.forEach((els, name) => {
+                // Determine the dominant type for a group (radio/checkbox take precedence)
+                const hasRadio = els.some((e) => e.type === "radio");
+                const hasCheckbox = els.some((e) => e.type === "checkbox");
+                const hasFile = els.some((e) => e.type === "file");
+                const hasSelectMultiple = els.some((e) => e.tagName === "SELECT" && e.multiple);
+                const hasPassword = els.some((e) => e.type === "password");
+                if (hasCheckbox) {
+                    const checkedValues = els
+                        .filter((e) => e.type === "checkbox")
+                        .filter((e) => e.checked)
+                        .map((e) => e.value || "on");
+                    if (!Object.prototype.hasOwnProperty.call(result, name)) {
+                        result[name] = checkedValues; // [] when none checked
+                    }
+                    else if (!Array.isArray(result[name])) {
+                        result[name] = [result[name], ...checkedValues];
+                    }
+                    return;
+                }
+                if (hasRadio) {
+                    const checked = els
+                        .filter((e) => e.type === "radio")
+                        .find((e) => e.checked);
+                    if (!Object.prototype.hasOwnProperty.call(result, name)) {
+                        result[name] = checked ? checked.value : null;
+                    }
+                    return;
+                }
+                if (hasSelectMultiple) {
+                    const select = els.find((e) => e.tagName === "SELECT" && e.multiple);
+                    if (select) {
+                        const selectedValues = Array.from(select.selectedOptions).map((opt) => opt.value);
+                        if (!Object.prototype.hasOwnProperty.call(result, name)) {
+                            result[name] = selectedValues; // [] when none selected
+                        }
+                        return;
+                    }
+                }
+                if (hasFile) {
+                    const input = els.find((e) => e.type === "file");
+                    if (input) {
+                        const files = input.files ? Array.from(input.files) : [];
+                        if (!Object.prototype.hasOwnProperty.call(result, name)) {
+                            result[name] = files.map((f) => this.serializeFormValue(f));
+                        }
+                        return;
+                    }
+                }
+                if (hasPassword) {
+                    // Mask password fields
+                    if (Object.prototype.hasOwnProperty.call(result, name)) {
+                        result[name] =
+                            typeof result[name] === "string" ? "*****" : result[name];
+                    }
+                    else {
+                        result[name] = "*****";
+                    }
+                    return;
+                }
+                // For other inputs/selects/textarea, ensure at least an entry exists
+                if (!Object.prototype.hasOwnProperty.call(result, name)) {
+                    const first = els[0];
+                    if (first.tagName === "SELECT") {
+                        const select = first;
+                        result[name] = select.multiple
+                            ? Array.from(select.selectedOptions).map((o) => o.value)
+                            : select.value;
+                    }
+                    else if (first.type) {
+                        result[name] = first.value ?? "";
+                    }
+                    else {
+                        result[name] = first.value ?? "";
+                    }
+                }
+            });
+        }
+        catch (error) {
+            this.logger.error("Failed to serialize form fields:", error);
+        }
+        return result;
+    }
+    getFormFieldKey(el, index) {
+        const name = el.name;
+        if (name) {
+            return name;
+        }
+        if (el.id) {
+            return `id_${el.id}`;
+        }
+        const ariaLabel = el.getAttribute("aria-label");
+        if (ariaLabel && ariaLabel.trim()) {
+            return `aria_${this.normalizeFormFieldKey(ariaLabel)}`;
+        }
+        const placeholder = el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement
+            ? el.placeholder
+            : "";
+        if (placeholder && placeholder.trim()) {
+            return `ph_${this.normalizeFormFieldKey(placeholder)}_${index}`;
+        }
+        return `field_${index}`;
+    }
+    normalizeFormFieldKey(raw) {
+        return raw
+            .trim()
+            .toLowerCase()
+            .replace(/\s+/g, "_")
+            .replace(/[^a-z0-9_]/g, "")
+            .slice(0, 40);
+    }
+    // Convert FormData value to a serializable value
+    serializeFormValue(value) {
+        if (value instanceof File) {
+            return {
+                file_name: value.name,
+                file_size: value.size,
+                file_type: value.type,
+            };
+        }
+        return value;
+    }
+    /**
+     * Extract standardized lead fields from form data
+     * @param formData Serialized form data
+     * @returns Extracted user traits
+     */
+    extractLeadFields(formData) {
+        const result = {};
+        // Iterate through all standard field mappings
+        for (const [standardField, aliases] of Object.entries(DEFAULT_FIELD_MAPPINGS)) {
+            if (result[standardField])
+                continue; // Already found, skip
+            // Look for matching field
+            for (const alias of aliases || []) {
+                const lowerAlias = alias.toLowerCase();
+                // Search for matching key in formData
+                for (const [key, value] of Object.entries(formData)) {
+                    if (key.toLowerCase() === lowerAlias ||
+                        key.toLowerCase().includes(lowerAlias)) {
+                        if (value && typeof value === "string" && value.trim()) {
+                            result[standardField] = value.trim();
+                            break;
+                        }
+                    }
+                }
+                if (result[standardField])
+                    break;
+            }
+        }
+        // Combine first_name and last_name into name (if name is empty)
+        if (!result.name && (result.first_name || result.last_name)) {
+            result.name = [result.first_name, result.last_name]
+                .filter(Boolean)
+                .join(" ")
+                .trim();
+        }
+        return result;
+    }
+    // Setup link tracking
+    setupLinkTracking() {
+        document.addEventListener("click", (event) => {
+            const target = event.target;
+            const link = target.closest("a");
+            if (link) {
+                const href = link.href;
+                const isExternal = isExternalURL(href);
+                if (isExternal) {
+                    // Handle cross-domain UTM passing
+                    this.handleCrossDomainUTM(link, event);
+                }
+            }
+        });
+    }
+    // Handle cross-domain UTM parameter passing
+    handleCrossDomainUTM(link, event) {
+        if (!this.config.enableCrossDomainUTM) {
+            return;
+        }
+        const href = link.href;
+        // Check if domain should be excluded
+        if (shouldExcludeDomain(href, this.config.excludeDomains)) {
+            this.logger.debug(`Domain excluded from UTM passing: ${href}`);
+            return;
+        }
+        // Get current UTM data
+        const attributionData = this.getAttributionData();
+        if (!attributionData) {
+            this.logger.debug("No UTM data available for cross-domain passing");
+            return;
+        }
+        // Filter UTM parameters based on configuration
+        const utmParams = filterUTMParams(attributionData.lastTouch, this.config.crossDomainUTMParams);
+        if (Object.keys(utmParams).length === 0) {
+            this.logger.debug("No UTM parameters to pass");
+            return;
+        }
+        // Add UTM parameters to URL
+        const enhancedURL = addUTMToURL(href, utmParams);
+        if (enhancedURL !== href) {
+            // Update the link href
+            link.href = enhancedURL;
+            this.logger.debug("UTM parameters added to external link:", {
+                original: href,
+                enhanced: enhancedURL,
+                utmParams,
+            });
+            this.logger.debug("Cross-domain UTM passed:", {
+                link_url: enhancedURL,
+                original_url: href,
+                utm_params_passed: utmParams,
+            });
+        }
+    }
+    // Setup network handlers
+    setupNetworkHandlers() {
+        window.addEventListener("online", () => {
+            this.logger.info("Network connection restored");
+            this.queue.flush();
+        });
+        window.addEventListener("offline", () => {
+            this.logger.warn("Network connection lost");
+        });
+    }
+    // Setup visibility handlers
+    setupVisibilityHandlers() {
+        document.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === "hidden") {
+                this.flushOnUnload("visibilitychange:hidden");
+                return;
+            }
+            if (document.visibilityState === "visible") {
+                this.updateSessionActivity();
+            }
+        });
+    }
+    // Setup beforeunload handler
+    setupBeforeUnloadHandler() {
+        window.addEventListener("beforeunload", () => {
+            this.flushOnUnload("beforeunload");
+        });
+        // More reliable than beforeunload for modern browsers (incl. mobile)
+        window.addEventListener("pagehide", () => {
+            this.flushOnUnload("pagehide");
+        });
+    }
+    flushOnUnload(reason) {
+        try {
+            this.updateSessionActivity();
+            const pending = this.queue.drainAll();
+            if (pending.length === 0) {
+                return;
+            }
+            // Backup first (best-effort). If keepalive succeeds, we'll remove by id.
+            this.storage.appendPendingEvents(pending);
+            this.logger.debug(`🚚 Unload flush triggered: ${reason}`, {
+                count: pending.length,
+            });
+            // Prefer beacon (avoid preflight) for redirect/unload scenarios.
+            const beaconOk = this.httpClient.sendEventsBeacon(pending);
+            if (beaconOk) {
+                // Best-effort: remove to avoid duplicates (beacon is queued by browser).
+                this.storage.removePendingEventsByIds(pending.map((e) => e.event_id));
+                return;
+            }
+            const chunkSize = 20;
+            for (let i = 0; i < pending.length; i += chunkSize) {
+                const chunk = pending.slice(i, i + chunkSize);
+                void this.httpClient
+                    .sendEventsKeepalive(chunk)
+                    .then(() => {
+                    this.storage.removePendingEventsByIds(chunk.map((e) => e.event_id));
+                })
+                    .catch((error) => {
+                    this.logger.debug("Unload keepalive send failed", error);
+                });
+            }
+        }
+        catch (error) {
+            this.logger.debug("flushOnUnload failed", error);
+        }
+    }
+    async retryPendingEvents() {
+        const pending = this.storage.getPendingEvents();
+        if (pending.length === 0) {
+            return;
+        }
+        this.logger.info(`📦 Retrying pending events: ${pending.length}`);
+        try {
+            await this.httpClient.sendEvents(pending);
+            this.storage.removePendingEventsByIds(pending.map((e) => e.event_id));
+            this.logger.info(`✅ Pending events sent: ${pending.length}`);
+        }
+        catch (error) {
+            this.logger.warn("⚠️ Pending events retry failed", error);
+        }
+    }
+    // Get current path (pathname + search) for comparison
+    getCurrentPath() {
+        if (typeof window === "undefined")
+            return "";
+        return window.location.pathname + window.location.search;
+    }
+    // Setup SPA (Single Page Application) route tracking
+    setupSPATracking() {
+        if (typeof window === "undefined" || typeof history === "undefined") {
+            this.logger.warn("⚠️ SPA tracking not available in this environment");
+            return;
+        }
+        if (this.spaTrackingEnabled) {
+            this.logger.warn("⚠️ SPA tracking already enabled");
+            return;
+        }
+        this.spaTrackingEnabled = true;
+        this.lastTrackedPath = this.getCurrentPath();
+        // Store original methods
+        this.originalPushState = history.pushState.bind(history);
+        this.originalReplaceState = history.replaceState.bind(history);
+        // Create a handler for route changes
+        const handleRouteChange = (changeType) => {
+            const newPath = this.getCurrentPath();
+            // Only track if path actually changed
+            if (newPath === this.lastTrackedPath) {
+                this.logger.debug(`🔄 [SPA] Route change detected (${changeType}) but path unchanged: ${newPath}`);
+                return;
+            }
+            this.logger.debug(`🔄 [SPA] Route change detected (${changeType}): ${this.lastTrackedPath} -> ${newPath}`);
+            this.lastTrackedPath = newPath;
+            // Delay tracking to allow page title and content to update (100ms is sufficient for most frameworks)
+            setTimeout(() => {
+                this.trackPageView()
+                    .then(() => {
+                    // If auto page view is enabled, send ASAP to survive short redirects
+                    return this.queue.process();
+                })
+                    .then(() => {
+                    this.logger.debug(`✅ [SPA] Page view tracked for: ${newPath}`);
+                })
+                    .catch((error) => {
+                    this.logger.error(`❌ [SPA] Failed to track page view:`, error);
+                });
+            }, 100);
+        };
+        // Override history.pushState
+        history.pushState = (data, unused, url) => {
+            const result = this.originalPushState(data, unused, url);
+            handleRouteChange("pushState");
+            return result;
+        };
+        // Override history.replaceState
+        history.replaceState = (data, unused, url) => {
+            const result = this.originalReplaceState(data, unused, url);
+            handleRouteChange("replaceState");
+            return result;
+        };
+        // Listen for popstate (browser back/forward)
+        this.popstateHandler = () => {
+            handleRouteChange("popstate");
+        };
+        window.addEventListener("popstate", this.popstateHandler);
+        this.logger.info("🔄 SPA tracking setup completed");
+    }
+    // Cleanup SPA tracking (restore original methods)
+    cleanupSPATracking() {
+        if (!this.spaTrackingEnabled)
+            return;
+        // Restore original history methods
+        if (this.originalPushState) {
+            history.pushState = this.originalPushState;
+            this.originalPushState = null;
+        }
+        if (this.originalReplaceState) {
+            history.replaceState = this.originalReplaceState;
+            this.originalReplaceState = null;
+        }
+        // Remove popstate listener
+        if (this.popstateHandler) {
+            window.removeEventListener("popstate", this.popstateHandler);
+            this.popstateHandler = null;
+        }
+        this.spaTrackingEnabled = false;
+        this.logger.info("🔄 SPA tracking cleaned up");
+    }
+    // Update session activity
+    updateSessionActivity() {
+        if (this.session) {
+            this.session.lastActivity = Date.now();
+            this.storage.storeSession(this.session);
+        }
+    }
+    // Flush all pending events
+    async flush() {
+        await this.queue.flush();
+    }
+    // Get SDK status
+    getStatus() {
+        return {
+            initialized: this.initialized,
+            session: this.session,
+            queueSize: this.queue.size(),
+            online: isOnline(),
+            crossDomainUTM: {
+                enabled: this.config.enableCrossDomainUTM || true,
+                currentParams: this.getCurrentUTMParams(),
+            },
+            spaTracking: {
+                enabled: this.spaTrackingEnabled,
+                currentPath: this.lastTrackedPath,
+            },
+        };
+    }
+    // Destroy SDK instance
+    destroy() {
+        this.queue.clear();
+        this.autoTrackEnabled = false;
+        this.cleanupSPATracking();
+        this.initialized = false;
+        this.logger.info("🗑️ SDK destroyed");
+    }
+}