@grainql/analytics-web 1.7.4 → 2.1.0

package/dist/react/index.js

@@ -0,0 +1,1491 @@
+"use strict";
+/**
+ * Grain Analytics Web SDK
+ * A lightweight, dependency-free TypeScript SDK for sending analytics events to Grain's REST API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrainAnalytics = void 0;
+exports.createGrainAnalytics = createGrainAnalytics;
+const consent_1 = require("./consent");
+const cookies_1 = require("./cookies");
+const activity_1 = require("./activity");
+const heartbeat_1 = require("./heartbeat");
+const page_tracking_1 = require("./page-tracking");
+class GrainAnalytics {
+    constructor(config) {
+        this.eventQueue = [];
+        this.waitingForConsentQueue = [];
+        this.flushTimer = null;
+        this.isDestroyed = false;
+        this.globalUserId = null;
+        this.persistentAnonymousUserId = null;
+        // Remote Config properties
+        this.configCache = null;
+        this.configRefreshTimer = null;
+        this.configChangeListeners = [];
+        this.configFetchPromise = null;
+        this.cookiesEnabled = false;
+        // Automatic Tracking properties
+        this.activityDetector = null;
+        this.heartbeatManager = null;
+        this.pageTrackingManager = null;
+        this.ephemeralSessionId = null;
+        this.eventCountSinceLastHeartbeat = 0;
+        this.config = {
+            apiUrl: 'https://api.grainql.com',
+            authStrategy: 'NONE',
+            batchSize: 50,
+            flushInterval: 5000, // 5 seconds
+            retryAttempts: 3,
+            retryDelay: 1000, // 1 second
+            maxEventsPerRequest: 160, // Maximum events per API request
+            debug: false,
+            // Remote Config defaults
+            defaultConfigurations: {},
+            configCacheKey: 'grain_config',
+            configRefreshInterval: 300000, // 5 minutes
+            enableConfigCache: true,
+            // Privacy defaults
+            consentMode: 'opt-out',
+            waitForConsent: false,
+            enableCookies: false,
+            anonymizeIP: false,
+            disableAutoProperties: false,
+            // Automatic Tracking defaults
+            enableHeartbeat: true,
+            heartbeatActiveInterval: 120000, // 2 minutes
+            heartbeatInactiveInterval: 300000, // 5 minutes
+            enableAutoPageView: true,
+            stripQueryParams: true,
+            ...config,
+            tenantId: config.tenantId,
+        };
+        // Initialize consent manager
+        this.consentManager = new consent_1.ConsentManager(this.config.tenantId, this.config.consentMode);
+        // Check if cookies are enabled
+        if (this.config.enableCookies) {
+            this.cookiesEnabled = (0, cookies_1.areCookiesEnabled)();
+            if (!this.cookiesEnabled && this.config.debug) {
+                console.warn('[Grain Analytics] Cookies are not available, falling back to localStorage');
+            }
+        }
+        // Set global userId if provided in config
+        if (config.userId) {
+            this.globalUserId = config.userId;
+        }
+        this.validateConfig();
+        this.initializePersistentAnonymousUserId();
+        this.setupBeforeUnload();
+        this.startFlushTimer();
+        this.initializeConfigCache();
+        // Initialize ephemeral session ID (memory-only, not persisted)
+        this.ephemeralSessionId = this.generateUUID();
+        // Initialize automatic tracking (browser only)
+        if (typeof window !== 'undefined') {
+            this.initializeAutomaticTracking();
+        }
+        // Set up consent change listener to flush waiting events and handle consent upgrade
+        this.consentManager.addListener((state) => {
+            if (state.granted) {
+                this.handleConsentGranted();
+            }
+        });
+    }
+    validateConfig() {
+        if (!this.config.tenantId) {
+            throw new Error('Grain Analytics: tenantId is required');
+        }
+        if (this.config.authStrategy === 'SERVER_SIDE' && !this.config.secretKey) {
+            throw new Error('Grain Analytics: secretKey is required for SERVER_SIDE auth strategy');
+        }
+        if (this.config.authStrategy === 'JWT' && !this.config.authProvider) {
+            throw new Error('Grain Analytics: authProvider is required for JWT auth strategy');
+        }
+    }
+    /**
+     * Generate a UUID v4 string
+     */
+    generateUUID() {
+        if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        // Fallback for environments without crypto.randomUUID
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+    /**
+     * Generate a proper UUIDv4 identifier for anonymous user ID
+     */
+    generateAnonymousUserId() {
+        return this.generateUUID();
+    }
+    /**
+     * Initialize persistent anonymous user ID from cookies or localStorage
+     * Priority: Cookie → localStorage → generate new
+     */
+    initializePersistentAnonymousUserId() {
+        if (typeof window === 'undefined')
+            return;
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        const cookieName = '_grain_uid';
+        try {
+            // Try to load from cookie first if enabled
+            if (this.cookiesEnabled) {
+                const cookieValue = (0, cookies_1.getCookie)(cookieName);
+                if (cookieValue) {
+                    this.persistentAnonymousUserId = cookieValue;
+                    this.log('Loaded persistent anonymous user ID from cookie:', this.persistentAnonymousUserId);
+                    return;
+                }
+            }
+            // Fallback to localStorage
+            const stored = localStorage.getItem(storageKey);
+            if (stored) {
+                this.persistentAnonymousUserId = stored;
+                this.log('Loaded persistent anonymous user ID from localStorage:', this.persistentAnonymousUserId);
+                // Migrate to cookie if enabled
+                if (this.cookiesEnabled) {
+                    this.savePersistentAnonymousUserId(stored);
+                }
+            }
+            else {
+                // Generate new UUIDv4 anonymous user ID
+                this.persistentAnonymousUserId = this.generateAnonymousUserId();
+                this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
+                this.log('Generated new persistent anonymous user ID:', this.persistentAnonymousUserId);
+            }
+        }
+        catch (error) {
+            this.log('Failed to initialize persistent anonymous user ID:', error);
+            // Fallback: generate temporary ID without persistence
+            this.persistentAnonymousUserId = this.generateAnonymousUserId();
+        }
+    }
+    /**
+     * Save persistent anonymous user ID to cookie and/or localStorage
+     */
+    savePersistentAnonymousUserId(userId) {
+        if (typeof window === 'undefined')
+            return;
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        const cookieName = '_grain_uid';
+        try {
+            // Save to cookie if enabled
+            if (this.cookiesEnabled) {
+                const cookieOptions = {
+                    maxAge: 365 * 24 * 60 * 60, // 365 days
+                    sameSite: 'lax',
+                    secure: window.location.protocol === 'https:',
+                    ...this.config.cookieOptions,
+                };
+                (0, cookies_1.setCookie)(cookieName, userId, cookieOptions);
+            }
+            // Always save to localStorage as fallback
+            localStorage.setItem(storageKey, userId);
+        }
+        catch (error) {
+            this.log('Failed to save persistent anonymous user ID:', error);
+        }
+    }
+    /**
+     * Get the effective user ID (global userId or persistent anonymous ID)
+     */
+    getEffectiveUserIdInternal() {
+        if (this.globalUserId) {
+            return this.globalUserId;
+        }
+        if (this.persistentAnonymousUserId) {
+            return this.persistentAnonymousUserId;
+        }
+        // Generate a new UUIDv4 identifier as fallback
+        this.persistentAnonymousUserId = this.generateAnonymousUserId();
+        // Try to persist it
+        if (typeof window !== 'undefined') {
+            try {
+                const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+                localStorage.setItem(storageKey, this.persistentAnonymousUserId);
+            }
+            catch (error) {
+                this.log('Failed to persist generated anonymous user ID:', error);
+            }
+        }
+        return this.persistentAnonymousUserId;
+    }
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[Grain Analytics]', ...args);
+        }
+    }
+    /**
+     * Create error digest from events
+     */
+    createErrorDigest(events) {
+        const eventNames = [...new Set(events.map(e => e.eventName))];
+        const userIds = [...new Set(events.map(e => e.userId))];
+        let totalProperties = 0;
+        let totalSize = 0;
+        events.forEach(event => {
+            const properties = event.properties || {};
+            totalProperties += Object.keys(properties).length;
+            totalSize += JSON.stringify(event).length;
+        });
+        return {
+            eventCount: events.length,
+            totalProperties,
+            totalSize,
+            eventNames,
+            userIds,
+        };
+    }
+    /**
+     * Format error with beautiful structure
+     */
+    formatError(error, context, events) {
+        const digest = events ? this.createErrorDigest(events) : {
+            eventCount: 0,
+            totalProperties: 0,
+            totalSize: 0,
+            eventNames: [],
+            userIds: [],
+        };
+        let code = 'UNKNOWN_ERROR';
+        let message = 'An unknown error occurred';
+        if (error instanceof Error) {
+            message = error.message;
+            // Determine error code based on error type and message
+            if (message.includes('fetch failed') || message.includes('network error')) {
+                code = 'NETWORK_ERROR';
+            }
+            else if (message.includes('timeout')) {
+                code = 'TIMEOUT_ERROR';
+            }
+            else if (message.includes('HTTP 4')) {
+                code = 'CLIENT_ERROR';
+            }
+            else if (message.includes('HTTP 5')) {
+                code = 'SERVER_ERROR';
+            }
+            else if (message.includes('JSON')) {
+                code = 'PARSE_ERROR';
+            }
+            else if (message.includes('auth') || message.includes('unauthorized')) {
+                code = 'AUTH_ERROR';
+            }
+            else if (message.includes('rate limit') || message.includes('429')) {
+                code = 'RATE_LIMIT_ERROR';
+            }
+            else {
+                code = 'GENERAL_ERROR';
+            }
+        }
+        else if (typeof error === 'string') {
+            message = error;
+            code = 'STRING_ERROR';
+        }
+        else if (error && typeof error === 'object' && 'status' in error) {
+            const status = error.status;
+            code = `HTTP_${status}`;
+            message = `HTTP ${status} error`;
+        }
+        return {
+            code,
+            message,
+            digest,
+            timestamp: new Date().toISOString(),
+            context,
+            originalError: error,
+        };
+    }
+    /**
+     * Log formatted error gracefully
+     */
+    logError(formattedError) {
+        const { code, message, digest, timestamp, context } = formattedError;
+        const errorOutput = {
+            '🚨 Grain Analytics Error': {
+                'Error Code': code,
+                'Message': message,
+                'Context': context,
+                'Timestamp': timestamp,
+                'Event Digest': {
+                    'Events': digest.eventCount,
+                    'Properties': digest.totalProperties,
+                    'Size (bytes)': digest.totalSize,
+                    'Event Names': digest.eventNames.length > 0 ? digest.eventNames.join(', ') : 'None',
+                    'User IDs': digest.userIds.length > 0 ? digest.userIds.slice(0, 3).join(', ') + (digest.userIds.length > 3 ? '...' : '') : 'None',
+                }
+            }
+        };
+        console.error('🚨 Grain Analytics Error:', errorOutput);
+        // Also log in a more compact format for debugging
+        if (this.config.debug) {
+            console.error(`[Grain Analytics] ${code}: ${message} (${context}) - Events: ${digest.eventCount}, Props: ${digest.totalProperties}, Size: ${digest.totalSize}B`);
+        }
+    }
+    /**
+     * Safely execute a function with error handling
+     */
+    async safeExecute(fn, context, events) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, context, events);
+            this.logError(formattedError);
+            return null;
+        }
+    }
+    formatEvent(event) {
+        return {
+            eventName: event.eventName,
+            userId: event.userId || this.getEffectiveUserIdInternal(),
+            properties: event.properties || {},
+        };
+    }
+    async getAuthHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        switch (this.config.authStrategy) {
+            case 'NONE':
+                break;
+            case 'SERVER_SIDE':
+                headers['Authorization'] = `Chase ${this.config.secretKey}`;
+                break;
+            case 'JWT':
+                if (this.config.authProvider) {
+                    const token = await this.config.authProvider.getToken();
+                    headers['Authorization'] = `Bearer ${token}`;
+                }
+                break;
+        }
+        return headers;
+    }
+    async delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    isRetriableError(error) {
+        if (error instanceof Error) {
+            // Check for specific network or fetch errors
+            const message = error.message.toLowerCase();
+            if (message.includes('fetch failed'))
+                return true;
+            if (message === 'network error')
+                return true; // Exact match to avoid "Non-network error"
+            if (message.includes('timeout'))
+                return true;
+            if (message.includes('connection'))
+                return true;
+        }
+        // Check for HTTP status codes that are retriable
+        if (typeof error === 'object' && error !== null && 'status' in error) {
+            const status = error.status;
+            return status >= 500 || status === 429; // Server errors or rate limiting
+        }
+        return false;
+    }
+    async sendEvents(events) {
+        if (events.length === 0)
+            return;
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const headers = await this.getAuthHeaders();
+                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
+                this.log(`Sending ${events.length} events to ${url} (attempt ${attempt + 1})`);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(events),
+                });
+                if (!response.ok) {
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorBody = await response.json();
+                        if (errorBody?.message) {
+                            errorMessage = errorBody.message;
+                        }
+                    }
+                    catch {
+                        const errorText = await response.text();
+                        if (errorText) {
+                            errorMessage = errorText;
+                        }
+                    }
+                    const error = new Error(`Failed to send events: ${errorMessage}`);
+                    error.status = response.status;
+                    throw error;
+                }
+                this.log(`Successfully sent ${events.length} events`);
+                return; // Success, exit retry loop
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.config.retryAttempts) {
+                    // Last attempt, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, `sendEvents (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`, events);
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
+                }
+                if (!this.isRetriableError(error)) {
+                    // Non-retriable error, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, `sendEvents (non-retriable error)`, events);
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
+                }
+                const delayMs = this.config.retryDelay * Math.pow(2, attempt); // Exponential backoff
+                this.log(`Retrying in ${delayMs}ms after error:`, error);
+                await this.delay(delayMs);
+            }
+        }
+    }
+    async sendEventsWithBeacon(events) {
+        if (events.length === 0)
+            return;
+        try {
+            const headers = await this.getAuthHeaders();
+            const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
+            const body = JSON.stringify({ events });
+            // Try beacon API first (more reliable for page unload)
+            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+                const blob = new Blob([body], { type: 'application/json' });
+                const success = navigator.sendBeacon(url, blob);
+                if (success) {
+                    this.log(`Successfully sent ${events.length} events via beacon`);
+                    return;
+                }
+            }
+            // Fallback to fetch with keepalive
+            await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+                keepalive: true,
+            });
+            this.log(`Successfully sent ${events.length} events via fetch (keepalive)`);
+        }
+        catch (error) {
+            // Log error gracefully for beacon failures (page unload scenarios)
+            const formattedError = this.formatError(error, 'sendEventsWithBeacon', events);
+            this.logError(formattedError);
+        }
+    }
+    startFlushTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flushTimer = window.setInterval(() => {
+            if (this.eventQueue.length > 0) {
+                this.flush().catch((error) => {
+                    const formattedError = this.formatError(error, 'auto-flush');
+                    this.logError(formattedError);
+                });
+            }
+        }, this.config.flushInterval);
+    }
+    setupBeforeUnload() {
+        if (typeof window === 'undefined')
+            return;
+        const handleBeforeUnload = () => {
+            if (this.eventQueue.length > 0) {
+                // Use beacon API for reliable delivery during page unload
+                const eventsToSend = [...this.eventQueue];
+                this.eventQueue = [];
+                const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
+                // Send first chunk with beacon (most important for page unload)
+                if (chunks.length > 0) {
+                    this.sendEventsWithBeacon(chunks[0]).catch(() => {
+                        // Silently fail - page is unloading
+                    });
+                }
+            }
+        };
+        // Handle page unload
+        window.addEventListener('beforeunload', handleBeforeUnload);
+        window.addEventListener('pagehide', handleBeforeUnload);
+        // Handle visibility change (page hidden)
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden' && this.eventQueue.length > 0) {
+                const eventsToSend = [...this.eventQueue];
+                this.eventQueue = [];
+                const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
+                // Send first chunk with beacon (most important for page hidden)
+                if (chunks.length > 0) {
+                    this.sendEventsWithBeacon(chunks[0]).catch(() => {
+                        // Silently fail
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Initialize automatic tracking (heartbeat and page views)
+     */
+    initializeAutomaticTracking() {
+        if (this.config.enableHeartbeat) {
+            try {
+                this.activityDetector = new activity_1.ActivityDetector();
+                this.heartbeatManager = new heartbeat_1.HeartbeatManager(this, this.activityDetector, {
+                    activeInterval: this.config.heartbeatActiveInterval,
+                    inactiveInterval: this.config.heartbeatInactiveInterval,
+                    debug: this.config.debug,
+                });
+                this.log('Heartbeat tracking initialized');
+            }
+            catch (error) {
+                this.log('Failed to initialize heartbeat tracking:', error);
+            }
+        }
+        if (this.config.enableAutoPageView) {
+            try {
+                this.pageTrackingManager = new page_tracking_1.PageTrackingManager(this, {
+                    stripQueryParams: this.config.stripQueryParams,
+                    debug: this.config.debug,
+                });
+                this.log('Auto page view tracking initialized');
+            }
+            catch (error) {
+                this.log('Failed to initialize page view tracking:', error);
+            }
+        }
+    }
+    /**
+     * Handle consent granted - upgrade ephemeral session to persistent user
+     */
+    handleConsentGranted() {
+        this.flushWaitingForConsentQueue();
+        // Track consent granted event with mapping
+        if (this.ephemeralSessionId) {
+            this.trackSystemEvent('_grain_consent_granted', {
+                previous_session_id: this.ephemeralSessionId,
+                new_user_id: this.getEffectiveUserId(),
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /**
+     * Track system events that bypass consent checks (for necessary/functional tracking)
+     */
+    trackSystemEvent(eventName, properties) {
+        if (this.isDestroyed)
+            return;
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        // Create event with appropriate user ID
+        const event = {
+            eventName,
+            userId: hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId(),
+            properties: {
+                ...properties,
+                _minimal: !hasConsent, // Flag to indicate minimal tracking
+                _consent_status: hasConsent ? 'granted' : 'pending',
+            },
+        };
+        // Bypass consent check for necessary system events
+        this.eventQueue.push(event);
+        this.eventCountSinceLastHeartbeat++;
+        this.log(`Queued system event: ${eventName}`, properties);
+        // Consider flushing
+        if (this.eventQueue.length >= this.config.batchSize) {
+            this.flush().catch((error) => {
+                const formattedError = this.formatError(error, 'flush system event');
+                this.logError(formattedError);
+            });
+        }
+    }
+    /**
+     * Get ephemeral session ID (memory-only, not persisted)
+     */
+    getEphemeralSessionId() {
+        if (!this.ephemeralSessionId) {
+            this.ephemeralSessionId = this.generateUUID();
+        }
+        return this.ephemeralSessionId;
+    }
+    /**
+     * Get the current page path from page tracker
+     */
+    getCurrentPage() {
+        return this.pageTrackingManager?.getCurrentPage() || null;
+    }
+    /**
+     * Get event count since last heartbeat
+     */
+    getEventCountSinceLastHeartbeat() {
+        return this.eventCountSinceLastHeartbeat;
+    }
+    /**
+     * Reset event count since last heartbeat
+     */
+    resetEventCountSinceLastHeartbeat() {
+        this.eventCountSinceLastHeartbeat = 0;
+    }
+    /**
+     * Get the effective user ID (public method)
+     */
+    getEffectiveUserId() {
+        return this.getEffectiveUserIdInternal();
+    }
+    /**
+     * Get the session ID (ephemeral or persistent based on consent)
+     */
+    getSessionId() {
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        return hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId();
+    }
+    async track(eventOrName, propertiesOrOptions, options) {
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'track (client destroyed)');
+                this.logError(formattedError);
+                return;
+            }
+            let event;
+            let opts = {};
+            if (typeof eventOrName === 'string') {
+                event = {
+                    eventName: eventOrName,
+                    properties: propertiesOrOptions,
+                };
+                opts = options || {};
+            }
+            else {
+                event = eventOrName;
+                opts = propertiesOrOptions || {};
+            }
+            // Filter properties if whitelist is enabled
+            if (this.config.allowedProperties && event.properties) {
+                const filtered = {};
+                for (const key of this.config.allowedProperties) {
+                    if (key in event.properties) {
+                        filtered[key] = event.properties[key];
+                    }
+                }
+                event.properties = filtered;
+            }
+            const formattedEvent = this.formatEvent(event);
+            // Check consent before tracking
+            if (this.consentManager.shouldWaitForConsent() && this.config.waitForConsent) {
+                // Queue event until consent is granted
+                this.waitingForConsentQueue.push(formattedEvent);
+                this.log(`Event waiting for consent: ${event.eventName}`, event.properties);
+                return;
+            }
+            if (!this.consentManager.hasConsent('analytics')) {
+                this.log(`Event blocked by consent: ${event.eventName}`);
+                return;
+            }
+            this.eventQueue.push(formattedEvent);
+            this.eventCountSinceLastHeartbeat++;
+            this.log(`Queued event: ${event.eventName}`, event.properties);
+            // Check if we should flush immediately
+            if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
+                await this.flush();
+            }
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'track');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Flush events that were waiting for consent
+     */
+    flushWaitingForConsentQueue() {
+        if (this.waitingForConsentQueue.length === 0)
+            return;
+        this.log(`Flushing ${this.waitingForConsentQueue.length} events waiting for consent`);
+        // Move waiting events to main queue
+        this.eventQueue.push(...this.waitingForConsentQueue);
+        this.waitingForConsentQueue = [];
+        // Flush immediately
+        this.flush().catch((error) => {
+            const formattedError = this.formatError(error, 'flush waiting for consent queue');
+            this.logError(formattedError);
+        });
+    }
+    /**
+     * Identify a user (sets userId for subsequent events)
+     */
+    identify(userId) {
+        this.log(`Identified user: ${userId}`);
+        this.globalUserId = userId;
+        // Clear persistent anonymous user ID since we now have a real user ID
+        this.persistentAnonymousUserId = null;
+    }
+    /**
+     * Set global user ID for all subsequent events
+     */
+    setUserId(userId) {
+        this.log(`Set global user ID: ${userId}`);
+        this.globalUserId = userId;
+        if (userId) {
+            // Clear persistent anonymous user ID if setting a real user ID
+            this.persistentAnonymousUserId = null;
+        }
+        else {
+            // If clearing user ID, ensure we have a UUIDv4 identifier
+            if (!this.persistentAnonymousUserId) {
+                this.persistentAnonymousUserId = this.generateAnonymousUserId();
+                // Try to persist the new anonymous ID
+                if (typeof window !== 'undefined') {
+                    try {
+                        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+                        localStorage.setItem(storageKey, this.persistentAnonymousUserId);
+                    }
+                    catch (error) {
+                        this.log('Failed to persist new anonymous user ID:', error);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Get current global user ID
+     */
+    getUserId() {
+        return this.globalUserId;
+    }
+    /**
+     * Get current effective user ID (global userId or persistent anonymous ID)
+     */
+    getEffectiveUserIdPublic() {
+        return this.getEffectiveUserIdInternal();
+    }
+    /**
+     * Login with auth token or userId on the fly
+     *
+     * @example
+     * // Login with userId only
+     * client.login({ userId: 'user123' });
+     *
+     * // Login with auth token (automatically sets authStrategy to JWT)
+     * client.login({ authToken: 'jwt-token-here' });
+     *
+     * // Login with both userId and auth token
+     * client.login({ userId: 'user123', authToken: 'jwt-token-here' });
+     *
+     * // Override auth strategy
+     * client.login({ userId: 'user123', authStrategy: 'SERVER_SIDE' });
+     */
+    login(options) {
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'login (client destroyed)');
+                this.logError(formattedError);
+                return;
+            }
+            // Set userId if provided
+            if (options.userId) {
+                this.log(`Login: Setting user ID to ${options.userId}`);
+                this.globalUserId = options.userId;
+                // Clear persistent anonymous user ID since we now have a real user ID
+                this.persistentAnonymousUserId = null;
+            }
+            // Handle auth token if provided
+            if (options.authToken) {
+                this.log('Login: Setting auth token');
+                // Update auth strategy to JWT if not already set
+                if (this.config.authStrategy === 'NONE') {
+                    this.config.authStrategy = 'JWT';
+                }
+                // Create a simple auth provider that returns the provided token
+                this.config.authProvider = {
+                    getToken: () => options.authToken
+                };
+            }
+            // Override auth strategy if provided
+            if (options.authStrategy) {
+                this.log(`Login: Setting auth strategy to ${options.authStrategy}`);
+                this.config.authStrategy = options.authStrategy;
+            }
+            this.log(`Login successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'login');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Logout and clear user session, fall back to UUIDv4 identifier
+     *
+     * @example
+     * // Logout user and return to anonymous mode
+     * client.logout();
+     *
+     * // After logout, events will use the persistent UUIDv4 identifier
+     * client.track('page_view', { page: 'home' });
+     */
+    logout() {
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'logout (client destroyed)');
+                this.logError(formattedError);
+                return;
+            }
+            this.log('Logout: Clearing user session');
+            // Clear global user ID
+            this.globalUserId = null;
+            // Reset auth strategy to NONE
+            this.config.authStrategy = 'NONE';
+            this.config.authProvider = undefined;
+            // Generate new UUIDv4 identifier if we don't have one
+            if (!this.persistentAnonymousUserId) {
+                this.persistentAnonymousUserId = this.generateAnonymousUserId();
+                // Try to persist the new anonymous ID
+                if (typeof window !== 'undefined') {
+                    try {
+                        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+                        localStorage.setItem(storageKey, this.persistentAnonymousUserId);
+                    }
+                    catch (error) {
+                        this.log('Failed to persist new anonymous user ID after logout:', error);
+                    }
+                }
+            }
+            this.log(`Logout successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'logout');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Set user properties
+     */
+    async setProperty(properties, options) {
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'setProperty (client destroyed)');
+                this.logError(formattedError);
+                return;
+            }
+            const userId = options?.userId || this.getEffectiveUserIdInternal();
+            // Validate property count (max 4 properties)
+            const propertyKeys = Object.keys(properties);
+            if (propertyKeys.length > 4) {
+                const error = new Error('Grain Analytics: Maximum 4 properties allowed per request');
+                const formattedError = this.formatError(error, 'setProperty (validation)');
+                this.logError(formattedError);
+                return;
+            }
+            if (propertyKeys.length === 0) {
+                const error = new Error('Grain Analytics: At least one property is required');
+                const formattedError = this.formatError(error, 'setProperty (validation)');
+                this.logError(formattedError);
+                return;
+            }
+            // Serialize all values to strings
+            const serializedProperties = {};
+            for (const [key, value] of Object.entries(properties)) {
+                if (value === null || value === undefined) {
+                    serializedProperties[key] = '';
+                }
+                else if (typeof value === 'string') {
+                    serializedProperties[key] = value;
+                }
+                else {
+                    serializedProperties[key] = JSON.stringify(value);
+                }
+            }
+            const payload = {
+                userId,
+                ...serializedProperties,
+            };
+            await this.sendProperties(payload);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'setProperty');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Send properties to the API
+     */
+    async sendProperties(payload) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const headers = await this.getAuthHeaders();
+                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/properties`;
+                this.log(`Setting properties for user ${payload.userId} (attempt ${attempt + 1})`);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                if (!response.ok) {
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorBody = await response.json();
+                        if (errorBody?.message) {
+                            errorMessage = errorBody.message;
+                        }
+                    }
+                    catch {
+                        const errorText = await response.text();
+                        if (errorText) {
+                            errorMessage = errorText;
+                        }
+                    }
+                    const error = new Error(`Failed to set properties: ${errorMessage}`);
+                    error.status = response.status;
+                    throw error;
+                }
+                this.log(`Successfully set properties for user ${payload.userId}`);
+                return; // Success, exit retry loop
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.config.retryAttempts) {
+                    // Last attempt, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, `sendProperties (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`);
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
+                }
+                if (!this.isRetriableError(error)) {
+                    // Non-retriable error, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, 'sendProperties (non-retriable error)');
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
+                }
+                const delayMs = this.config.retryDelay * Math.pow(2, attempt); // Exponential backoff
+                this.log(`Retrying in ${delayMs}ms after error:`, error);
+                await this.delay(delayMs);
+            }
+        }
+    }
+    // Template event methods
+    /**
+     * Track user login event
+     */
+    async trackLogin(properties, options) {
+        try {
+            return await this.track('login', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackLogin');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track user signup event
+     */
+    async trackSignup(properties, options) {
+        try {
+            return await this.track('signup', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackSignup');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track checkout event
+     */
+    async trackCheckout(properties, options) {
+        try {
+            return await this.track('checkout', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackCheckout');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track page view event
+     */
+    async trackPageView(properties, options) {
+        try {
+            return await this.track('page_view', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackPageView');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track purchase event
+     */
+    async trackPurchase(properties, options) {
+        try {
+            return await this.track('purchase', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackPurchase');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track search event
+     */
+    async trackSearch(properties, options) {
+        try {
+            return await this.track('search', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackSearch');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track add to cart event
+     */
+    async trackAddToCart(properties, options) {
+        try {
+            return await this.track('add_to_cart', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackAddToCart');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Track remove from cart event
+     */
+    async trackRemoveFromCart(properties, options) {
+        try {
+            return await this.track('remove_from_cart', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackRemoveFromCart');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Manually flush all queued events
+     */
+    async flush() {
+        try {
+            if (this.eventQueue.length === 0)
+                return;
+            const eventsToSend = [...this.eventQueue];
+            this.eventQueue = [];
+            // Split events into chunks to respect maxEventsPerRequest limit
+            const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
+            // Send all chunks sequentially to maintain order
+            for (const chunk of chunks) {
+                await this.sendEvents(chunk);
+            }
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'flush');
+            this.logError(formattedError);
+        }
+    }
+    // Remote Config Methods
+    /**
+     * Initialize configuration cache from localStorage
+     */
+    initializeConfigCache() {
+        if (!this.config.enableConfigCache || typeof window === 'undefined')
+            return;
+        try {
+            const cached = localStorage.getItem(this.config.configCacheKey);
+            if (cached) {
+                this.configCache = JSON.parse(cached);
+                this.log('Loaded configuration from cache:', this.configCache);
+            }
+        }
+        catch (error) {
+            this.log('Failed to load configuration cache:', error);
+        }
+    }
+    /**
+     * Save configuration cache to localStorage
+     */
+    saveConfigCache(cache) {
+        if (!this.config.enableConfigCache || typeof window === 'undefined')
+            return;
+        try {
+            localStorage.setItem(this.config.configCacheKey, JSON.stringify(cache));
+            this.log('Saved configuration to cache:', cache);
+        }
+        catch (error) {
+            this.log('Failed to save configuration cache:', error);
+        }
+    }
+    /**
+     * Get configuration value with fallback to defaults
+     */
+    getConfig(key) {
+        // First check cache
+        if (this.configCache?.configurations?.[key]) {
+            return this.configCache.configurations[key];
+        }
+        // Then check defaults
+        if (this.config.defaultConfigurations?.[key]) {
+            return this.config.defaultConfigurations[key];
+        }
+        return undefined;
+    }
+    /**
+     * Get all configurations with fallback to defaults
+     */
+    getAllConfigs() {
+        const configs = { ...this.config.defaultConfigurations };
+        if (this.configCache?.configurations) {
+            Object.assign(configs, this.configCache.configurations);
+        }
+        return configs;
+    }
+    /**
+     * Fetch configurations from API
+     */
+    async fetchConfig(options = {}) {
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'fetchConfig (client destroyed)');
+                this.logError(formattedError);
+                return null;
+            }
+            const userId = options.userId || this.getEffectiveUserIdInternal();
+            const immediateKeys = options.immediateKeys || [];
+            const properties = options.properties || {};
+            const request = {
+                userId,
+                immediateKeys,
+                properties,
+            };
+            let lastError;
+            for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+                try {
+                    const headers = await this.getAuthHeaders();
+                    const url = `${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/config/configurations`;
+                    this.log(`Fetching configurations for user ${userId} (attempt ${attempt + 1})`);
+                    const response = await fetch(url, {
+                        method: 'POST',
+                        headers,
+                        body: JSON.stringify(request),
+                    });
+                    if (!response.ok) {
+                        let errorMessage = `HTTP ${response.status}`;
+                        try {
+                            const errorBody = await response.json();
+                            if (errorBody?.message) {
+                                errorMessage = errorBody.message;
+                            }
+                        }
+                        catch {
+                            const errorText = await response.text();
+                            if (errorText) {
+                                errorMessage = errorText;
+                            }
+                        }
+                        const error = new Error(`Failed to fetch configurations: ${errorMessage}`);
+                        error.status = response.status;
+                        throw error;
+                    }
+                    const configResponse = await response.json();
+                    // Update cache if successful
+                    if (configResponse.configurations) {
+                        this.updateConfigCache(configResponse, userId);
+                    }
+                    this.log(`Successfully fetched configurations for user ${userId}:`, configResponse);
+                    return configResponse;
+                }
+                catch (error) {
+                    lastError = error;
+                    if (attempt === this.config.retryAttempts) {
+                        // Last attempt, don't retry - log error gracefully
+                        const formattedError = this.formatError(error, `fetchConfig (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`);
+                        this.logError(formattedError);
+                        return null;
+                    }
+                    if (!this.isRetriableError(error)) {
+                        // Non-retriable error, don't retry - log error gracefully
+                        const formattedError = this.formatError(error, 'fetchConfig (non-retriable error)');
+                        this.logError(formattedError);
+                        return null;
+                    }
+                    const delayMs = this.config.retryDelay * Math.pow(2, attempt);
+                    this.log(`Retrying config fetch in ${delayMs}ms after error:`, error);
+                    await this.delay(delayMs);
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'fetchConfig');
+            this.logError(formattedError);
+            return null;
+        }
+    }
+    /**
+     * Get configuration asynchronously (cache-first with fallback to API)
+     */
+    async getConfigAsync(key, options = {}) {
+        try {
+            // Return immediately if we have it in cache and not forcing refresh
+            if (!options.forceRefresh && this.configCache?.configurations?.[key]) {
+                return this.configCache.configurations[key];
+            }
+            // Return default if available and not forcing refresh
+            if (!options.forceRefresh && this.config.defaultConfigurations?.[key]) {
+                return this.config.defaultConfigurations[key];
+            }
+            // Fetch from API
+            const response = await this.fetchConfig(options);
+            if (response) {
+                return response.configurations[key];
+            }
+            // Return default as fallback
+            return this.config.defaultConfigurations?.[key];
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'getConfigAsync');
+            this.logError(formattedError);
+            // Return default as fallback
+            return this.config.defaultConfigurations?.[key];
+        }
+    }
+    /**
+     * Get all configurations asynchronously (cache-first with fallback to API)
+     */
+    async getAllConfigsAsync(options = {}) {
+        try {
+            // Return cache if available and not forcing refresh
+            if (!options.forceRefresh && this.configCache?.configurations) {
+                return { ...this.config.defaultConfigurations, ...this.configCache.configurations };
+            }
+            // Fetch from API
+            const response = await this.fetchConfig(options);
+            if (response) {
+                return { ...this.config.defaultConfigurations, ...response.configurations };
+            }
+            // Return defaults as fallback
+            return { ...this.config.defaultConfigurations };
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'getAllConfigsAsync');
+            this.logError(formattedError);
+            // Return defaults as fallback
+            return { ...this.config.defaultConfigurations };
+        }
+    }
+    /**
+     * Update configuration cache and notify listeners
+     */
+    updateConfigCache(response, userId) {
+        const newCache = {
+            configurations: response.configurations,
+            snapshotId: response.snapshotId,
+            timestamp: response.timestamp,
+            userId,
+        };
+        const oldConfigs = this.configCache?.configurations || {};
+        this.configCache = newCache;
+        this.saveConfigCache(newCache);
+        // Notify listeners if configurations changed
+        if (JSON.stringify(oldConfigs) !== JSON.stringify(response.configurations)) {
+            this.notifyConfigChangeListeners(response.configurations);
+        }
+    }
+    /**
+     * Add configuration change listener
+     */
+    addConfigChangeListener(listener) {
+        this.configChangeListeners.push(listener);
+    }
+    /**
+     * Remove configuration change listener
+     */
+    removeConfigChangeListener(listener) {
+        const index = this.configChangeListeners.indexOf(listener);
+        if (index > -1) {
+            this.configChangeListeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notify all configuration change listeners
+     */
+    notifyConfigChangeListeners(configurations) {
+        this.configChangeListeners.forEach(listener => {
+            try {
+                listener(configurations);
+            }
+            catch (error) {
+                console.error('[Grain Analytics] Config change listener error:', error);
+            }
+        });
+    }
+    /**
+     * Start automatic configuration refresh timer
+     */
+    startConfigRefreshTimer() {
+        if (this.configRefreshTimer) {
+            clearInterval(this.configRefreshTimer);
+        }
+        this.configRefreshTimer = window.setInterval(() => {
+            if (!this.isDestroyed) {
+                // Use effective userId (will be generated if not set)
+                this.fetchConfig().catch((error) => {
+                    const formattedError = this.formatError(error, 'auto-config refresh');
+                    this.logError(formattedError);
+                });
+            }
+        }, this.config.configRefreshInterval);
+    }
+    /**
+     * Stop automatic configuration refresh timer
+     */
+    stopConfigRefreshTimer() {
+        if (this.configRefreshTimer) {
+            clearInterval(this.configRefreshTimer);
+            this.configRefreshTimer = null;
+        }
+    }
+    /**
+     * Preload configurations for immediate access
+     */
+    async preloadConfig(immediateKeys = [], properties) {
+        try {
+            // Use effective userId (will be generated if not set)
+            const effectiveUserId = this.getEffectiveUserIdInternal();
+            this.log(`Preloading config for user: ${effectiveUserId}`);
+            const response = await this.fetchConfig({ immediateKeys, properties });
+            if (response) {
+                this.startConfigRefreshTimer();
+            }
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'preloadConfig');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Split events array into chunks of specified size
+     */
+    chunkEvents(events, chunkSize) {
+        const chunks = [];
+        for (let i = 0; i < events.length; i += chunkSize) {
+            chunks.push(events.slice(i, i + chunkSize));
+        }
+        return chunks;
+    }
+    // Privacy & Consent Methods
+    /**
+     * Grant consent for tracking
+     * @param categories - Optional array of consent categories (e.g., ['analytics', 'functional'])
+     */
+    grantConsent(categories) {
+        try {
+            this.consentManager.grantConsent(categories);
+            this.log('Consent granted', categories);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'grantConsent');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Revoke consent for tracking (opt-out)
+     * @param categories - Optional array of categories to revoke (if not provided, revokes all)
+     */
+    revokeConsent(categories) {
+        try {
+            this.consentManager.revokeConsent(categories);
+            this.log('Consent revoked', categories);
+            // Clear queued events when consent is revoked
+            this.eventQueue = [];
+            this.waitingForConsentQueue = [];
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'revokeConsent');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Get current consent state
+     */
+    getConsentState() {
+        return this.consentManager.getConsentState();
+    }
+    /**
+     * Check if user has granted consent
+     * @param category - Optional category to check (if not provided, checks general consent)
+     */
+    hasConsent(category) {
+        return this.consentManager.hasConsent(category);
+    }
+    /**
+     * Add listener for consent state changes
+     */
+    onConsentChange(listener) {
+        this.consentManager.addListener(listener);
+    }
+    /**
+     * Remove consent change listener
+     */
+    offConsentChange(listener) {
+        this.consentManager.removeListener(listener);
+    }
+    /**
+     * Destroy the client and clean up resources
+     */
+    destroy() {
+        this.isDestroyed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Stop config refresh timer
+        this.stopConfigRefreshTimer();
+        // Clear config change listeners
+        this.configChangeListeners = [];
+        // Destroy automatic tracking managers
+        if (this.heartbeatManager) {
+            this.heartbeatManager.destroy();
+            this.heartbeatManager = null;
+        }
+        if (this.pageTrackingManager) {
+            this.pageTrackingManager.destroy();
+            this.pageTrackingManager = null;
+        }
+        if (this.activityDetector) {
+            this.activityDetector.destroy();
+            this.activityDetector = null;
+        }
+        // Send any remaining events (in chunks if necessary)
+        if (this.eventQueue.length > 0) {
+            const eventsToSend = [...this.eventQueue];
+            this.eventQueue = [];
+            const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
+            // Send first chunk with beacon (most important for page unload)
+            if (chunks.length > 0) {
+                this.sendEventsWithBeacon(chunks[0]).catch(() => {
+                    // Silently fail during cleanup
+                });
+                // If there are more chunks, try to send them with regular fetch
+                for (let i = 1; i < chunks.length; i++) {
+                    this.sendEventsWithBeacon(chunks[i]).catch(() => {
+                        // Silently fail during cleanup
+                    });
+                }
+            }
+        }
+    }
+}
+exports.GrainAnalytics = GrainAnalytics;
+/**
+ * Create a new Grain Analytics client
+ */
+function createGrainAnalytics(config) {
+    return new GrainAnalytics(config);
+}
+// Default export for convenience
+exports.default = GrainAnalytics;
+// Auto-setup for IIFE build
+if (typeof window !== 'undefined') {
+    window.Grain = {
+        GrainAnalytics,
+        createGrainAnalytics,
+    };
+}