@clianta/sdk 1.6.8 → 1.7.1

package/dist/react.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * Clianta SDK v1.6.8
+ * Clianta SDK v1.7.1
  * (c) 2026 Clianta
  * Released under the MIT License.
  */
@@ -14,7 +14,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
  * @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)
@@ -40,6 +40,15 @@ const getDefaultApiEndpoint = () => {
     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 */
@@ -185,7 +194,9 @@ const logger = createLogger(false);
  */
 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
  */
@@ -204,6 +215,11 @@ class Transport {
     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);
     }
     /**
@@ -268,6 +284,15 @@ class Transport {
             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.)
@@ -302,38 +327,44 @@ class Transport {
         }
     }
     /**
-     * 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 };
@@ -682,12 +713,17 @@ class EventQueue {
         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,
@@ -696,6 +732,7 @@ class EventQueue {
             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
@@ -744,7 +781,7 @@ class EventQueue {
      * 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;
@@ -775,11 +812,14 @@ class EventQueue {
         }
     }
     /**
-     * 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);
@@ -817,17 +857,17 @@ class EventQueue {
             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);
         }
     }
     /**
@@ -842,24 +882,38 @@ class EventQueue {
         }, 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
@@ -942,6 +996,8 @@ class BasePlugin {
  * 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
  */
@@ -951,50 +1007,64 @@ class PageViewPlugin extends BasePlugin {
         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() {
@@ -1123,6 +1193,7 @@ class FormsPlugin extends BasePlugin {
         this.trackedForms = new WeakSet();
         this.formInteractions = new Set();
         this.observer = null;
+        this.observerTimer = null;
         this.listeners = [];
     }
     init(tracker) {
@@ -1131,13 +1202,21 @@ class FormsPlugin extends BasePlugin {
             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;
@@ -1259,8 +1338,13 @@ class ClicksPlugin extends BasePlugin {
         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);
@@ -1293,6 +1377,8 @@ class EngagementPlugin extends BasePlugin {
         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;
@@ -1314,8 +1400,9 @@ class EngagementPlugin extends BasePlugin {
                 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) => {
@@ -1361,6 +1448,7 @@ class EngagementPlugin extends BasePlugin {
         this.pageLoadTime = Date.now();
         this.engagementStartTime = Date.now();
         this.isEngaged = false;
+        this.unloadReported = false;
         if (this.engagementTimeout) {
             clearTimeout(this.engagementTimeout);
             this.engagementTimeout = null;
@@ -1382,6 +1470,10 @@ class EngagementPlugin extends BasePlugin {
         }, 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', {
@@ -1540,12 +1632,16 @@ class ExitIntentPlugin extends BasePlugin {
 /**
  * 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);
@@ -1568,6 +1664,9 @@ class ErrorsPlugin extends BasePlugin {
         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,
@@ -1577,9 +1676,22 @@ class ErrorsPlugin extends BasePlugin {
         });
     }
     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;
     }
 }
 
@@ -3518,28 +3630,17 @@ class Tracker {
         }
         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).
@@ -3902,13 +4003,24 @@ let globalInstance = null;
  * });
  */
 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);
@@ -3936,8 +4048,21 @@ if (typeof window !== 'undefined') {
         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;
     };
@@ -3999,15 +4124,12 @@ class CliantaErrorBoundary extends react.Component {
 function CliantaProvider({ projectId, apiEndpoint, debug, config, children, onError }) {
     const [tracker, setTracker] = react.useState(null);
     const [isReady, setIsReady] = react.useState(false);
-    const projectIdRef = react.useRef(projectId);
+    const trackerRef = react.useRef(null);
     react.useEffect(() => {
         if (!projectId) {
             console.error('[Clianta] Missing projectId prop on CliantaProvider');
             return;
         }
-        if (projectIdRef.current !== projectId) {
-            projectIdRef.current = projectId;
-        }
         try {
             const options = {
                 debug: debug ?? false,
@@ -4015,6 +4137,7 @@ function CliantaProvider({ projectId, apiEndpoint, debug, config, children, onEr
                 ...(apiEndpoint ? { apiEndpoint } : {}),
             };
             const instance = clianta(projectId, options);
+            trackerRef.current = instance;
             setTracker(instance);
             setIsReady(true);
         }
@@ -4023,7 +4146,8 @@ function CliantaProvider({ projectId, apiEndpoint, debug, config, children, onEr
             onError?.(error, { componentStack: '' });
         }
         return () => {
-            tracker?.flush();
+            // Use ref so cleanup always flushes the live instance, not the stale closure value
+            trackerRef.current?.flush();
             setIsReady(false);
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -4049,12 +4173,13 @@ function useCliantaReady() {
 }
 /**
  * useCliantaTrack — Quick tracking hook
+ * Stable function reference (useCallback) — safe to use as a dependency or pass as a prop.
  */
 function useCliantaTrack() {
     const tracker = useClianta();
-    return (eventType, eventName, properties) => {
+    return react.useCallback((eventType, eventName, properties) => {
         tracker?.track(eventType, eventName, properties);
-    };
+    }, [tracker]);
 }
 
 exports.CliantaProvider = CliantaProvider;