@clianta/sdk 1.6.8 → 1.7.1

package/dist/clianta.umd.js

@@ -1,5 +1,5 @@
 /*!
- * Clianta SDK v1.6.8
+ * Clianta SDK v1.7.1
  * (c) 2026 Clianta
  * Released under the MIT License.
  */
@@ -15,7 +15,7 @@
      * @see SDK_VERSION in core/config.ts
      */
     /** SDK Version */
-    const SDK_VERSION = '1.6.7';
+    const SDK_VERSION = '1.7.0';
     /** Default API endpoint — reads from env or falls back to localhost */
     const getDefaultApiEndpoint = () => {
         // Next.js (process.env)
@@ -41,6 +41,15 @@
         if (typeof process !== 'undefined' && process.env?.CLIANTA_API_ENDPOINT) {
             return process.env.CLIANTA_API_ENDPOINT;
         }
+        // No env var found — warn if we're not on localhost (likely a production misconfiguration)
+        const isLocalhost = typeof window !== 'undefined' &&
+            (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1');
+        if (!isLocalhost && typeof console !== 'undefined') {
+            console.warn('[Clianta] No API endpoint configured. ' +
+                'Set NEXT_PUBLIC_CLIANTA_API_ENDPOINT (Next.js), VITE_CLIANTA_API_ENDPOINT (Vite), ' +
+                'or pass apiEndpoint directly to clianta(). ' +
+                'Falling back to localhost — tracking will not work in production.');
+        }
         return 'http://localhost:5000';
     };
     /** Core plugins enabled by default — all auto-track with zero config */
@@ -186,7 +195,9 @@
      */
     const DEFAULT_TIMEOUT = 10000; // 10 seconds
     const DEFAULT_MAX_RETRIES = 3;
-    const DEFAULT_RETRY_DELAY = 1000; // 1 second
+    const DEFAULT_RETRY_DELAY = 1000; // 1 second base — doubles each attempt (exponential backoff)
+    /** fetch keepalive hard limit in browsers (64KB) */
+    const KEEPALIVE_SIZE_LIMIT = 60000; // leave 4KB margin
     /**
      * Transport class for sending data to the backend
      */
@@ -205,6 +216,11 @@
         async sendEvents(events) {
             const url = `${this.config.apiEndpoint}/api/public/track/event`;
             const payload = JSON.stringify({ events });
+            // keepalive has a 64KB hard limit — fall back to beacon if too large
+            if (payload.length > KEEPALIVE_SIZE_LIMIT) {
+                const sent = this.sendBeacon(events);
+                return sent ? { success: true } : this.send(url, payload, 1, false);
+            }
             return this.send(url, payload);
         }
         /**
@@ -269,6 +285,15 @@
                 return false;
             }
         }
+        /**
+         * Send an arbitrary POST request through the transport (with timeout + retry).
+         * Used for one-off calls like alias() that don't fit the event-batch or identify shapes.
+         */
+        async sendPost(path, body) {
+            const url = `${this.config.apiEndpoint}${path}`;
+            const payload = JSON.stringify(body);
+            return this.send(url, payload);
+        }
         /**
          * Fetch data from the tracking API (GET request)
          * Used for read-back APIs (visitor profile, activity, etc.)
@@ -303,38 +328,44 @@
             }
         }
         /**
-         * Internal send with retry logic
+         * Internal send with exponential backoff retry logic
          */
-        async send(url, payload, attempt = 1) {
+        async send(url, payload, attempt = 1, useKeepalive = true) {
+            // Don't bother sending when offline — caller should re-queue
+            if (typeof navigator !== 'undefined' && !navigator.onLine) {
+                logger.warn('Device offline, skipping send');
+                return { success: false, error: new Error('offline') };
+            }
             try {
                 const response = await this.fetchWithTimeout(url, {
                     method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                    },
+                    headers: { 'Content-Type': 'application/json' },
                     body: payload,
-                    keepalive: true,
+                    keepalive: useKeepalive,
                 });
                 if (response.ok) {
                     logger.debug('Request successful:', url);
                     return { success: true, status: response.status };
                 }
-                // Server error - may retry
+                // Server error — retry with exponential backoff
                 if (response.status >= 500 && attempt < this.config.maxRetries) {
-                    logger.warn(`Server error (${response.status}), retrying...`);
-                    await this.delay(this.config.retryDelay * attempt);
-                    return this.send(url, payload, attempt + 1);
+                    const backoff = this.config.retryDelay * Math.pow(2, attempt - 1);
+                    logger.warn(`Server error (${response.status}), retrying in ${backoff}ms...`);
+                    await this.delay(backoff);
+                    return this.send(url, payload, attempt + 1, useKeepalive);
                 }
-                // Client error - don't retry
+                // 4xx — don't retry (bad payload, auth failure, etc.)
                 logger.error(`Request failed with status ${response.status}`);
                 return { success: false, status: response.status };
             }
             catch (error) {
-                // Network error - retry if possible
-                if (attempt < this.config.maxRetries) {
-                    logger.warn(`Network error, retrying (${attempt}/${this.config.maxRetries})...`);
-                    await this.delay(this.config.retryDelay * attempt);
-                    return this.send(url, payload, attempt + 1);
+                // Network error — retry with exponential backoff if still online
+                const isOnline = typeof navigator === 'undefined' || navigator.onLine;
+                if (isOnline && attempt < this.config.maxRetries) {
+                    const backoff = this.config.retryDelay * Math.pow(2, attempt - 1);
+                    logger.warn(`Network error, retrying in ${backoff}ms (${attempt}/${this.config.maxRetries})...`);
+                    await this.delay(backoff);
+                    return this.send(url, payload, attempt + 1, useKeepalive);
                 }
                 logger.error('Request failed after retries:', error);
                 return { success: false, error: error };
@@ -683,12 +714,17 @@
             this.queue = [];
             this.flushTimer = null;
             this.isFlushing = false;
+            this.isOnline = true;
             /** Rate limiting: timestamps of recent events */
             this.eventTimestamps = [];
             /** Unload handler references for cleanup */
             this.boundBeforeUnload = null;
             this.boundVisibilityChange = null;
             this.boundPageHide = null;
+            this.boundOnline = null;
+            this.boundOffline = null;
+            /** Guards against double-flush on unload (beforeunload + pagehide + visibilitychange all fire) */
+            this.unloadFlushed = false;
             this.transport = transport;
             this.config = {
                 batchSize: config.batchSize ?? 10,
@@ -697,6 +733,7 @@
                 storageKey: config.storageKey ?? STORAGE_KEYS.EVENT_QUEUE,
             };
             this.persistMode = config.persistMode || 'session';
+            this.isOnline = typeof navigator === 'undefined' || navigator.onLine;
             // Restore persisted queue
             this.restoreQueue();
             // Start auto-flush timer
@@ -745,7 +782,7 @@
          * Flush the queue (send all events)
          */
         async flush() {
-            if (this.isFlushing || this.queue.length === 0) {
+            if (this.isFlushing || this.queue.length === 0 || !this.isOnline) {
                 return;
             }
             this.isFlushing = true;
@@ -776,11 +813,14 @@
             }
         }
         /**
-         * Flush synchronously using sendBeacon (for page unload)
+         * Flush synchronously using sendBeacon (for page unload).
+         * Guarded: no-ops after the first call per navigation to prevent
+         * triple-flush from beforeunload + visibilitychange + pagehide.
          */
         flushSync() {
-            if (this.queue.length === 0)
+            if (this.unloadFlushed || this.queue.length === 0)
                 return;
+            this.unloadFlushed = true;
             const events = this.queue.splice(0, this.queue.length);
             logger.debug(`Sync flushing ${events.length} events via beacon`);
             const success = this.transport.sendBeacon(events);
@@ -818,17 +858,17 @@
                 clearInterval(this.flushTimer);
                 this.flushTimer = null;
             }
-            // Remove unload handlers
             if (typeof window !== 'undefined') {
-                if (this.boundBeforeUnload) {
+                if (this.boundBeforeUnload)
                     window.removeEventListener('beforeunload', this.boundBeforeUnload);
-                }
-                if (this.boundVisibilityChange) {
+                if (this.boundVisibilityChange)
                     window.removeEventListener('visibilitychange', this.boundVisibilityChange);
-                }
-                if (this.boundPageHide) {
+                if (this.boundPageHide)
                     window.removeEventListener('pagehide', this.boundPageHide);
-                }
+                if (this.boundOnline)
+                    window.removeEventListener('online', this.boundOnline);
+                if (this.boundOffline)
+                    window.removeEventListener('offline', this.boundOffline);
             }
         }
         /**
@@ -843,24 +883,38 @@
             }, this.config.flushInterval);
         }
         /**
-         * Setup page unload handlers
+         * Setup page unload handlers and online/offline listeners
          */
         setupUnloadHandlers() {
             if (typeof window === 'undefined')
                 return;
-            // Flush on page unload
+            // All three unload events share the same guarded flushSync()
             this.boundBeforeUnload = () => this.flushSync();
             window.addEventListener('beforeunload', this.boundBeforeUnload);
-            // Flush when page becomes hidden
             this.boundVisibilityChange = () => {
                 if (document.visibilityState === 'hidden') {
                     this.flushSync();
                 }
+                else {
+                    // Page became visible again (e.g. tab switch back) — reset guard
+                    this.unloadFlushed = false;
+                }
             };
             window.addEventListener('visibilitychange', this.boundVisibilityChange);
-            // Flush on page hide (iOS Safari)
             this.boundPageHide = () => this.flushSync();
             window.addEventListener('pagehide', this.boundPageHide);
+            // Pause queue when offline, resume + flush when back online
+            this.boundOnline = () => {
+                logger.info('Connection restored — flushing queued events');
+                this.isOnline = true;
+                this.flush();
+            };
+            this.boundOffline = () => {
+                logger.warn('Connection lost — pausing event queue');
+                this.isOnline = false;
+            };
+            window.addEventListener('online', this.boundOnline);
+            window.addEventListener('offline', this.boundOffline);
         }
         /**
          * Persist queue to storage based on persistMode
@@ -943,6 +997,8 @@
      * Clianta SDK - Page View Plugin
      * @see SDK_VERSION in core/config.ts
      */
+    /** Sentinel flag to prevent double-wrapping history methods across multiple SDK instances */
+    const WRAPPED_FLAG = '__clianta_pv_wrapped__';
     /**
      * Page View Plugin - Tracks page views
      */
@@ -952,50 +1008,64 @@
             this.name = 'pageView';
             this.originalPushState = null;
             this.originalReplaceState = null;
+            this.navHandler = null;
             this.popstateHandler = null;
         }
         init(tracker) {
             super.init(tracker);
             // Track initial page view
             this.trackPageView();
-            // Track SPA navigation (History API)
-            if (typeof window !== 'undefined') {
-                // Store originals for cleanup
+            if (typeof window === 'undefined')
+                return;
+            // Only wrap history methods once — guard against multiple SDK instances (e.g. microfrontends)
+            // wrapping them repeatedly, which would cause duplicate navigation events and broken cleanup.
+            if (!history.pushState[WRAPPED_FLAG]) {
                 this.originalPushState = history.pushState;
                 this.originalReplaceState = history.replaceState;
-                // Intercept pushState and replaceState
-                const self = this;
+                const originalPush = this.originalPushState;
+                const originalReplace = this.originalReplaceState;
                 history.pushState = function (...args) {
-                    self.originalPushState.apply(history, args);
-                    self.trackPageView();
-                    // Notify other plugins (e.g. ScrollPlugin) about navigation
+                    originalPush.apply(history, args);
+                    // Dispatch event so all listening instances track the navigation
                     window.dispatchEvent(new Event('clianta:navigation'));
                 };
+                history.pushState[WRAPPED_FLAG] = true;
                 history.replaceState = function (...args) {
-                    self.originalReplaceState.apply(history, args);
-                    self.trackPageView();
+                    originalReplace.apply(history, args);
                     window.dispatchEvent(new Event('clianta:navigation'));
                 };
-                // Handle back/forward navigation
-                this.popstateHandler = () => this.trackPageView();
-                window.addEventListener('popstate', this.popstateHandler);
+                history.replaceState[WRAPPED_FLAG] = true;
             }
+            // Each instance listens to the shared navigation event rather than embedding
+            // tracking directly in the pushState wrapper — decouples tracking from wrapping.
+            this.navHandler = () => this.trackPageView();
+            window.addEventListener('clianta:navigation', this.navHandler);
+            // Handle back/forward navigation
+            this.popstateHandler = () => this.trackPageView();
+            window.addEventListener('popstate', this.popstateHandler);
         }
         destroy() {
-            // Restore original history methods
+            if (typeof window !== 'undefined') {
+                if (this.navHandler) {
+                    window.removeEventListener('clianta:navigation', this.navHandler);
+                    this.navHandler = null;
+                }
+                if (this.popstateHandler) {
+                    window.removeEventListener('popstate', this.popstateHandler);
+                    this.popstateHandler = null;
+                }
+            }
+            // Restore original history methods only if this instance was the one that wrapped them
             if (this.originalPushState) {
                 history.pushState = this.originalPushState;
+                delete history.pushState[WRAPPED_FLAG];
                 this.originalPushState = null;
             }
             if (this.originalReplaceState) {
                 history.replaceState = this.originalReplaceState;
+                delete history.replaceState[WRAPPED_FLAG];
                 this.originalReplaceState = null;
             }
-            // Remove popstate listener
-            if (this.popstateHandler && typeof window !== 'undefined') {
-                window.removeEventListener('popstate', this.popstateHandler);
-                this.popstateHandler = null;
-            }
             super.destroy();
         }
         trackPageView() {
@@ -1124,6 +1194,7 @@
             this.trackedForms = new WeakSet();
             this.formInteractions = new Set();
             this.observer = null;
+            this.observerTimer = null;
             this.listeners = [];
         }
         init(tracker) {
@@ -1132,13 +1203,21 @@
                 return;
             // Track existing forms
             this.trackAllForms();
-            // Watch for dynamically added forms
+            // Watch for dynamically added forms — debounced to avoid O(DOM) cost on every mutation
             if (typeof MutationObserver !== 'undefined') {
-                this.observer = new MutationObserver(() => this.trackAllForms());
+                this.observer = new MutationObserver(() => {
+                    if (this.observerTimer)
+                        clearTimeout(this.observerTimer);
+                    this.observerTimer = setTimeout(() => this.trackAllForms(), 100);
+                });
                 this.observer.observe(document.body, { childList: true, subtree: true });
             }
         }
         destroy() {
+            if (this.observerTimer) {
+                clearTimeout(this.observerTimer);
+                this.observerTimer = null;
+            }
             if (this.observer) {
                 this.observer.disconnect();
                 this.observer = null;
@@ -1260,8 +1339,13 @@
             super.destroy();
         }
         handleClick(e) {
-            const target = e.target;
-            if (!target || !isTrackableClickElement(target))
+            // Walk up the DOM to find the nearest trackable ancestor.
+            // Without this, clicks on <span> or <img> inside a <button> are silently dropped.
+            let target = e.target;
+            while (target && !isTrackableClickElement(target)) {
+                target = target.parentElement;
+            }
+            if (!target)
                 return;
             const buttonText = getElementText(target, 100);
             const elementInfo = getElementInfo(target);
@@ -1294,6 +1378,8 @@
             this.engagementStartTime = 0;
             this.isEngaged = false;
             this.engagementTimeout = null;
+            /** Guard: beforeunload + visibilitychange:hidden both fire on tab close — only report once */
+            this.unloadReported = false;
             this.boundMarkEngaged = null;
             this.boundTrackTimeOnPage = null;
             this.boundVisibilityHandler = null;
@@ -1315,8 +1401,9 @@
                     this.trackTimeOnPage();
                 }
                 else {
-                    // Reset engagement timer when page becomes visible again
+                    // Page is visible again — reset both the time counter and the unload guard
                     this.engagementStartTime = Date.now();
+                    this.unloadReported = false;
                 }
             };
             ['mousemove', 'keydown', 'touchstart', 'scroll'].forEach((event) => {
@@ -1362,6 +1449,7 @@
             this.pageLoadTime = Date.now();
             this.engagementStartTime = Date.now();
             this.isEngaged = false;
+            this.unloadReported = false;
             if (this.engagementTimeout) {
                 clearTimeout(this.engagementTimeout);
                 this.engagementTimeout = null;
@@ -1383,6 +1471,10 @@
             }, 30000); // 30 seconds of inactivity
         }
         trackTimeOnPage() {
+            // Guard: beforeunload and visibilitychange:hidden both fire on tab close — only report once
+            if (this.unloadReported)
+                return;
+            this.unloadReported = true;
             const timeSpent = Math.floor((Date.now() - this.engagementStartTime) / 1000);
             if (timeSpent > 0) {
                 this.track('time_on_page', 'Time Spent', {
@@ -1541,12 +1633,16 @@
     /**
      * Error Tracking Plugin - Tracks JavaScript errors
      */
+    /** Max unique errors to track per page (prevents queue flooding from error loops) */
+    const MAX_UNIQUE_ERRORS = 20;
     class ErrorsPlugin extends BasePlugin {
         constructor() {
             super(...arguments);
             this.name = 'errors';
             this.boundErrorHandler = null;
             this.boundRejectionHandler = null;
+            /** Seen error fingerprints — deduplicates repeated identical errors */
+            this.seenErrors = new Set();
         }
         init(tracker) {
             super.init(tracker);
@@ -1569,6 +1665,9 @@
             super.destroy();
         }
         handleError(e) {
+            const fingerprint = `${e.message}:${e.filename}:${e.lineno}`;
+            if (!this.dedup(fingerprint))
+                return;
             this.track('error', 'JavaScript Error', {
                 message: e.message,
                 filename: e.filename,
@@ -1578,9 +1677,22 @@
             });
         }
         handleRejection(e) {
-            this.track('error', 'Unhandled Promise Rejection', {
-                reason: String(e.reason).substring(0, 200),
-            });
+            const reason = String(e.reason).substring(0, 200);
+            if (!this.dedup(reason))
+                return;
+            this.track('error', 'Unhandled Promise Rejection', { reason });
+        }
+        /**
+         * Returns true if this error fingerprint is new (should be tracked).
+         * Caps at MAX_UNIQUE_ERRORS to prevent queue flooding from error loops.
+         */
+        dedup(fingerprint) {
+            if (this.seenErrors.has(fingerprint))
+                return false;
+            if (this.seenErrors.size >= MAX_UNIQUE_ERRORS)
+                return false;
+            this.seenErrors.add(fingerprint);
+            return true;
         }
     }
 
@@ -3519,28 +3631,17 @@
             }
             const prevId = previousId || this.visitorId;
             logger.info('Aliasing visitor:', { from: prevId, to: newId });
-            try {
-                const url = `${this.config.apiEndpoint}/api/public/track/alias`;
-                const response = await fetch(url, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({
-                        workspaceId: this.workspaceId,
-                        previousId: prevId,
-                        newId,
-                    }),
-                });
-                if (response.ok) {
-                    logger.info('Alias successful');
-                    return true;
-                }
-                logger.error('Alias failed:', response.status);
-                return false;
-            }
-            catch (error) {
-                logger.error('Alias request failed:', error);
-                return false;
+            const result = await this.transport.sendPost('/api/public/track/alias', {
+                workspaceId: this.workspaceId,
+                previousId: prevId,
+                newId,
+            });
+            if (result.success) {
+                logger.info('Alias successful');
+                return true;
             }
+            logger.error('Alias failed:', result.error ?? result.status);
+            return false;
         }
         /**
          * Track a screen view (for mobile-first PWAs and SPAs).
@@ -3903,13 +4004,24 @@
      * });
      */
     function clianta(workspaceId, config) {
-        // Return existing instance if same workspace
+        // Return existing instance if same workspace and no config change
         if (globalInstance && globalInstance.getWorkspaceId() === workspaceId) {
+            if (config && Object.keys(config).length > 0) {
+                // Config was passed to an already-initialized instance — warn the developer
+                // because the new config is ignored. They must call destroy() first to reconfigure.
+                if (typeof console !== 'undefined') {
+                    console.warn('[Clianta] clianta() called with config on an already-initialized instance ' +
+                        'for workspace "' + workspaceId + '". The new config was ignored. ' +
+                        'Call tracker.destroy() first if you need to reconfigure.');
+                }
+            }
             return globalInstance;
         }
-        // Destroy existing instance if workspace changed
+        // Destroy existing instance if workspace changed (fire-and-forget flush, then destroy)
         if (globalInstance) {
-            globalInstance.destroy();
+            // Kick off async flush+destroy without blocking the new instance creation.
+            // Using void to make the intentional fire-and-forget explicit.
+            void globalInstance.destroy();
         }
         // Create new instance
         globalInstance = new Tracker(workspaceId, config);
@@ -3937,8 +4049,21 @@
             const projectId = script.getAttribute('data-project-id');
             if (!projectId)
                 return;
-            const debug = script.hasAttribute('data-debug');
-            const instance = clianta(projectId, { debug });
+            const initConfig = {
+                debug: script.hasAttribute('data-debug'),
+            };
+            // Support additional config via script tag attributes:
+            //   data-api-endpoint="https://api.yourhost.com"
+            //   data-cookieless  (boolean flag)
+            //   data-use-cookies (boolean flag)
+            const apiEndpoint = script.getAttribute('data-api-endpoint');
+            if (apiEndpoint)
+                initConfig.apiEndpoint = apiEndpoint;
+            if (script.hasAttribute('data-cookieless'))
+                initConfig.cookielessMode = true;
+            if (script.hasAttribute('data-use-cookies'))
+                initConfig.useCookies = true;
+            const instance = clianta(projectId, initConfig);
             // Expose the auto-initialized instance globally
             window.__clianta = instance;
         };