@grainql/analytics-web 2.0.0 → 2.1.1

package/dist/page-tracking.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Page Tracking for Grain Analytics
+ * Automatically tracks page views with consent-aware behavior
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageTrackingManager = void 0;
+class PageTrackingManager {
+    constructor(tracker, config) {
+        this.isDestroyed = false;
+        this.currentPath = null;
+        this.originalPushState = null;
+        this.originalReplaceState = null;
+        /**
+         * Handle popstate event (back/forward navigation)
+         */
+        this.handlePopState = () => {
+            if (this.isDestroyed)
+                return;
+            this.trackCurrentPage();
+        };
+        /**
+         * Handle hash change event
+         */
+        this.handleHashChange = () => {
+            if (this.isDestroyed)
+                return;
+            this.trackCurrentPage();
+        };
+        this.tracker = tracker;
+        this.config = config;
+        // Track initial page load
+        this.trackCurrentPage();
+        // Setup listeners
+        this.setupHistoryListeners();
+        this.setupHashChangeListener();
+    }
+    /**
+     * Setup History API listeners (pushState, replaceState, popstate)
+     */
+    setupHistoryListeners() {
+        if (typeof window === 'undefined' || typeof history === 'undefined')
+            return;
+        // Wrap pushState
+        this.originalPushState = history.pushState;
+        history.pushState = (state, title, url) => {
+            this.originalPushState?.call(history, state, title, url);
+            this.trackCurrentPage();
+        };
+        // Wrap replaceState
+        this.originalReplaceState = history.replaceState;
+        history.replaceState = (state, title, url) => {
+            this.originalReplaceState?.call(history, state, title, url);
+            this.trackCurrentPage();
+        };
+        // Listen to popstate (back/forward buttons)
+        window.addEventListener('popstate', this.handlePopState);
+    }
+    /**
+     * Setup hash change listener
+     */
+    setupHashChangeListener() {
+        if (typeof window === 'undefined')
+            return;
+        window.addEventListener('hashchange', this.handleHashChange);
+    }
+    /**
+     * Track the current page
+     */
+    trackCurrentPage() {
+        if (this.isDestroyed || typeof window === 'undefined')
+            return;
+        const page = this.extractPath(window.location.href);
+        // Don't track if it's the same page
+        if (page === this.currentPath) {
+            return;
+        }
+        this.currentPath = page;
+        const hasConsent = this.tracker.hasConsent('analytics');
+        // Base properties (always included)
+        const properties = {
+            page,
+            timestamp: Date.now(),
+        };
+        // Enhanced properties when consent is granted
+        if (hasConsent) {
+            properties.referrer = document.referrer || '';
+            properties.title = document.title || '';
+            properties.full_url = window.location.href;
+        }
+        // Track the page view event
+        this.tracker.trackSystemEvent('page_view', properties);
+        if (this.config.debug) {
+            console.log('[Page Tracking] Tracked page view:', properties);
+        }
+    }
+    /**
+     * Extract path from URL, optionally stripping query parameters
+     */
+    extractPath(url) {
+        try {
+            const urlObj = new URL(url);
+            let path = urlObj.pathname + urlObj.hash;
+            if (!this.config.stripQueryParams && urlObj.search) {
+                path += urlObj.search;
+            }
+            return path;
+        }
+        catch (error) {
+            // If URL parsing fails, return the raw string
+            if (this.config.debug) {
+                console.warn('[Page Tracking] Failed to parse URL:', url, error);
+            }
+            return url;
+        }
+    }
+    /**
+     * Get the current page path
+     */
+    getCurrentPage() {
+        return this.currentPath;
+    }
+    /**
+     * Manually track a page view (for custom navigation)
+     */
+    trackPage(page, properties) {
+        if (this.isDestroyed)
+            return;
+        const hasConsent = this.tracker.hasConsent('analytics');
+        // Base properties
+        const baseProperties = {
+            page,
+            timestamp: Date.now(),
+            ...properties,
+        };
+        // Enhanced properties when consent is granted
+        if (hasConsent && typeof document !== 'undefined') {
+            if (!baseProperties.referrer) {
+                baseProperties.referrer = document.referrer || '';
+            }
+            if (!baseProperties.title) {
+                baseProperties.title = document.title || '';
+            }
+            if (!baseProperties.full_url && typeof window !== 'undefined') {
+                baseProperties.full_url = window.location.href;
+            }
+        }
+        this.tracker.trackSystemEvent('page_view', baseProperties);
+        if (this.config.debug) {
+            console.log('[Page Tracking] Manually tracked page:', baseProperties);
+        }
+    }
+    /**
+     * Destroy the page tracker
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        // Restore original history methods
+        if (typeof history !== 'undefined') {
+            if (this.originalPushState) {
+                history.pushState = this.originalPushState;
+            }
+            if (this.originalReplaceState) {
+                history.replaceState = this.originalReplaceState;
+            }
+        }
+        // Remove event listeners
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('popstate', this.handlePopState);
+            window.removeEventListener('hashchange', this.handleHashChange);
+        }
+        this.isDestroyed = true;
+        if (this.config.debug) {
+            console.log('[Page Tracking] Destroyed');
+        }
+    }
+}
+exports.PageTrackingManager = PageTrackingManager;
+//# sourceMappingURL=page-tracking.js.map

package/dist/react/activity.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Activity Detection for Grain Analytics
+ * Tracks user activity (mouse, keyboard, touch, scroll) to determine if user is active
+ */
+export declare class ActivityDetector {
+    private lastActivityTime;
+    private activityThreshold;
+    private listeners;
+    private boundActivityHandler;
+    private isDestroyed;
+    private readonly activityEvents;
+    constructor();
+    /**
+     * Setup event listeners for activity detection
+     */
+    private setupListeners;
+    /**
+     * Handle activity event
+     */
+    private handleActivity;
+    /**
+     * Debounce function to limit how often activity handler is called
+     */
+    private debounce;
+    /**
+     * Check if user is currently active
+     * @param threshold Time in ms to consider user inactive (default: 30s)
+     */
+    isActive(threshold?: number): boolean;
+    /**
+     * Get time since last activity in milliseconds
+     */
+    getTimeSinceLastActivity(): number;
+    /**
+     * Get last activity timestamp
+     */
+    getLastActivityTime(): number;
+    /**
+     * Set activity threshold
+     */
+    setActivityThreshold(threshold: number): void;
+    /**
+     * Add listener for activity changes
+     */
+    addListener(listener: () => void): void;
+    /**
+     * Remove listener
+     */
+    removeListener(listener: () => void): void;
+    /**
+     * Notify all listeners
+     */
+    private notifyListeners;
+    /**
+     * Cleanup and remove listeners
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=activity.d.ts.map

package/dist/react/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/activity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAOpB;;IAQX;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAehB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO;IAMrC;;OAEG;IACH,wBAAwB,IAAI,MAAM;IAIlC;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAI7B;;OAEG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI7C;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAIvC;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAO1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,IAAI,IAAI;CAYhB"}

package/dist/react/activity.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Activity Detection for Grain Analytics
+ * Tracks user activity (mouse, keyboard, touch, scroll) to determine if user is active
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityDetector = void 0;
+class ActivityDetector {
+    constructor() {
+        this.activityThreshold = 30000; // 30 seconds
+        this.listeners = [];
+        this.isDestroyed = false;
+        // Events that indicate user activity
+        this.activityEvents = [
+            'mousemove',
+            'mousedown',
+            'keydown',
+            'scroll',
+            'touchstart',
+            'click',
+        ];
+        this.lastActivityTime = Date.now();
+        this.boundActivityHandler = this.debounce(this.handleActivity.bind(this), 500);
+        this.setupListeners();
+    }
+    /**
+     * Setup event listeners for activity detection
+     */
+    setupListeners() {
+        if (typeof window === 'undefined')
+            return;
+        for (const event of this.activityEvents) {
+            window.addEventListener(event, this.boundActivityHandler, { passive: true });
+        }
+    }
+    /**
+     * Handle activity event
+     */
+    handleActivity() {
+        if (this.isDestroyed)
+            return;
+        this.lastActivityTime = Date.now();
+        this.notifyListeners();
+    }
+    /**
+     * Debounce function to limit how often activity handler is called
+     */
+    debounce(func, wait) {
+        let timeout = null;
+        return () => {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+            }
+            timeout = window.setTimeout(() => {
+                func();
+                timeout = null;
+            }, wait);
+        };
+    }
+    /**
+     * Check if user is currently active
+     * @param threshold Time in ms to consider user inactive (default: 30s)
+     */
+    isActive(threshold) {
+        const thresholdToUse = threshold ?? this.activityThreshold;
+        const now = Date.now();
+        return (now - this.lastActivityTime) < thresholdToUse;
+    }
+    /**
+     * Get time since last activity in milliseconds
+     */
+    getTimeSinceLastActivity() {
+        return Date.now() - this.lastActivityTime;
+    }
+    /**
+     * Get last activity timestamp
+     */
+    getLastActivityTime() {
+        return this.lastActivityTime;
+    }
+    /**
+     * Set activity threshold
+     */
+    setActivityThreshold(threshold) {
+        this.activityThreshold = threshold;
+    }
+    /**
+     * Add listener for activity changes
+     */
+    addListener(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Remove listener
+     */
+    removeListener(listener) {
+        const index = this.listeners.indexOf(listener);
+        if (index > -1) {
+            this.listeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notify all listeners
+     */
+    notifyListeners() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error('[Activity Detector] Listener error:', error);
+            }
+        }
+    }
+    /**
+     * Cleanup and remove listeners
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        if (typeof window !== 'undefined') {
+            for (const event of this.activityEvents) {
+                window.removeEventListener(event, this.boundActivityHandler);
+            }
+        }
+        this.listeners = [];
+        this.isDestroyed = true;
+    }
+}
+exports.ActivityDetector = ActivityDetector;

package/dist/react/activity.mjs

@@ -0,0 +1,126 @@
+/**
+ * Activity Detection for Grain Analytics
+ * Tracks user activity (mouse, keyboard, touch, scroll) to determine if user is active
+ */
+export class ActivityDetector {
+    constructor() {
+        this.activityThreshold = 30000; // 30 seconds
+        this.listeners = [];
+        this.isDestroyed = false;
+        // Events that indicate user activity
+        this.activityEvents = [
+            'mousemove',
+            'mousedown',
+            'keydown',
+            'scroll',
+            'touchstart',
+            'click',
+        ];
+        this.lastActivityTime = Date.now();
+        this.boundActivityHandler = this.debounce(this.handleActivity.bind(this), 500);
+        this.setupListeners();
+    }
+    /**
+     * Setup event listeners for activity detection
+     */
+    setupListeners() {
+        if (typeof window === 'undefined')
+            return;
+        for (const event of this.activityEvents) {
+            window.addEventListener(event, this.boundActivityHandler, { passive: true });
+        }
+    }
+    /**
+     * Handle activity event
+     */
+    handleActivity() {
+        if (this.isDestroyed)
+            return;
+        this.lastActivityTime = Date.now();
+        this.notifyListeners();
+    }
+    /**
+     * Debounce function to limit how often activity handler is called
+     */
+    debounce(func, wait) {
+        let timeout = null;
+        return () => {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+            }
+            timeout = window.setTimeout(() => {
+                func();
+                timeout = null;
+            }, wait);
+        };
+    }
+    /**
+     * Check if user is currently active
+     * @param threshold Time in ms to consider user inactive (default: 30s)
+     */
+    isActive(threshold) {
+        const thresholdToUse = threshold ?? this.activityThreshold;
+        const now = Date.now();
+        return (now - this.lastActivityTime) < thresholdToUse;
+    }
+    /**
+     * Get time since last activity in milliseconds
+     */
+    getTimeSinceLastActivity() {
+        return Date.now() - this.lastActivityTime;
+    }
+    /**
+     * Get last activity timestamp
+     */
+    getLastActivityTime() {
+        return this.lastActivityTime;
+    }
+    /**
+     * Set activity threshold
+     */
+    setActivityThreshold(threshold) {
+        this.activityThreshold = threshold;
+    }
+    /**
+     * Add listener for activity changes
+     */
+    addListener(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Remove listener
+     */
+    removeListener(listener) {
+        const index = this.listeners.indexOf(listener);
+        if (index > -1) {
+            this.listeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notify all listeners
+     */
+    notifyListeners() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error('[Activity Detector] Listener error:', error);
+            }
+        }
+    }
+    /**
+     * Cleanup and remove listeners
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        if (typeof window !== 'undefined') {
+            for (const event of this.activityEvents) {
+                window.removeEventListener(event, this.boundActivityHandler);
+            }
+        }
+        this.listeners = [];
+        this.isDestroyed = true;
+    }
+}

package/dist/react/consent.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Consent management for Grain Analytics
+ * Handles GDPR-compliant consent tracking and state management
+ */
+export type ConsentMode = 'opt-in' | 'opt-out' | 'disabled';
+export interface ConsentState {
+    granted: boolean;
+    categories: string[];
+    timestamp: Date;
+    version: string;
+}
+export declare const DEFAULT_CONSENT_CATEGORIES: string[];
+export declare const CONSENT_VERSION = "1.0.0";
+/**
+ * Consent manager for handling user consent state
+ */
+export declare class ConsentManager {
+    private consentState;
+    private consentMode;
+    private storageKey;
+    private listeners;
+    constructor(tenantId: string, consentMode?: ConsentMode);
+    /**
+     * Load consent state from localStorage
+     */
+    private loadConsentState;
+    /**
+     * Save consent state to localStorage
+     */
+    private saveConsentState;
+    /**
+     * Grant consent with optional categories
+     */
+    grantConsent(categories?: string[]): void;
+    /**
+     * Revoke consent (opt-out)
+     */
+    revokeConsent(categories?: string[]): void;
+    /**
+     * Get current consent state
+     */
+    getConsentState(): ConsentState | null;
+    /**
+     * Check if user has granted consent
+     */
+    hasConsent(category?: string): boolean;
+    /**
+     * Check if we should wait for consent before tracking
+     */
+    shouldWaitForConsent(): boolean;
+    /**
+     * Add consent change listener
+     */
+    addListener(listener: (state: ConsentState) => void): void;
+    /**
+     * Remove consent change listener
+     */
+    removeListener(listener: (state: ConsentState) => void): void;
+    /**
+     * Notify all listeners of consent state change
+     */
+    private notifyListeners;
+    /**
+     * Clear all consent data
+     */
+    clearConsent(): void;
+}
+//# sourceMappingURL=consent.d.ts.map

package/dist/react/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/consent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,0BAA0B,UAA2C,CAAC;AACnF,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAA4C;gBAEjD,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,WAAuB;IAMlE;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACH,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IAczC;;OAEG;IACH,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IA8B1C;;OAEG;IACH,eAAe,IAAI,YAAY,GAAG,IAAI;IAItC;;OAEG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAwBtC;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAI1D;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAO7D;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,YAAY,IAAI,IAAI;CAUrB"}