@grainql/analytics-web 2.3.0 → 2.5.0

package/dist/section-tracking.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Section Tracking Manager for Grain Analytics
+ * Intelligent scroll tracking with viewport metrics, visible sections, and engagement analysis
+ */
+import type { SectionConfig, SectionTrackingOptions } from './types/auto-tracking';
+export interface SectionTracker {
+    trackSystemEvent(eventName: string, properties: Record<string, unknown>): void;
+    hasConsent(category: 'analytics' | 'marketing' | 'functional'): boolean;
+    log(...args: unknown[]): void;
+}
+export declare class SectionTrackingManager {
+    private tracker;
+    private sections;
+    private options;
+    private isDestroyed;
+    private sectionStates;
+    private intersectionObserver;
+    private xpathCache;
+    private lastScrollPosition;
+    private lastScrollTime;
+    private scrollVelocity;
+    private scrollDebounceTimer;
+    private pendingEvents;
+    private batchTimer;
+    constructor(tracker: SectionTracker, sections: SectionConfig[], options?: Partial<SectionTrackingOptions>);
+    /**
+     * Initialize section tracking
+     */
+    private initialize;
+    /**
+     * Setup IntersectionObserver for section visibility
+     */
+    private setupIntersectionObserver;
+    /**
+     * Setup scroll listener for velocity calculation
+     */
+    private setupScrollListener;
+    /**
+     * Initialize sections and start observing
+     */
+    private initializeSections;
+    /**
+     * Handle intersection observer entry
+     */
+    private handleIntersection;
+    /**
+     * Handle section entry (became visible)
+     */
+    private handleSectionEntry;
+    /**
+     * Handle section exit (became invisible)
+     */
+    private handleSectionExit;
+    /**
+     * Update scroll velocity
+     */
+    private updateScrollVelocity;
+    /**
+     * Calculate current scroll depth as percentage
+     */
+    private calculateScrollDepth;
+    /**
+     * Determine if section view should be tracked (sanitization)
+     */
+    private shouldTrackSection;
+    /**
+     * Queue section view for batching
+     */
+    private queueSectionView;
+    /**
+     * Flush pending section view events
+     */
+    private flushPendingEvents;
+    /**
+     * Find element by XPath selector
+     */
+    private findElementByXPath;
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Update sections configuration
+     */
+    updateSections(sections: SectionConfig[]): void;
+    /**
+     * Cleanup and destroy
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=section-tracking.d.ts.map

package/dist/section-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-tracking.d.ts","sourceRoot":"","sources":["../src/section-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmB,sBAAsB,EAAwB,MAAM,uBAAuB,CAAC;AAE1H,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/B;AAWD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,aAAa,CAAgD;IACrE,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,UAAU,CAA0C;IAG5D,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,mBAAmB,CAAuB;IAGlD,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAuB;gBAGvC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAgB/C;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAqBjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoCzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgC1B;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI;IAsB/C;;OAEG;IACH,OAAO,IAAI,IAAI;CAgChB"}

package/dist/section-tracking.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Section Tracking Manager for Grain Analytics
+ * Intelligent scroll tracking with viewport metrics, visible sections, and engagement analysis
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SectionTrackingManager = void 0;
+const DEFAULT_OPTIONS = {
+    minDwellTime: 1000, // 1 second minimum
+    scrollVelocityThreshold: 500, // 500px/s
+    intersectionThreshold: 0.1, // 10% visible
+    debounceDelay: 100,
+    batchDelay: 2000, // 2 seconds
+    debug: false,
+};
+class SectionTrackingManager {
+    constructor(tracker, sections, options = {}) {
+        this.isDestroyed = false;
+        // Tracking state
+        this.sectionStates = new Map();
+        this.intersectionObserver = null;
+        this.xpathCache = new Map();
+        // Scroll tracking
+        this.lastScrollPosition = 0;
+        this.lastScrollTime = Date.now();
+        this.scrollVelocity = 0;
+        this.scrollDebounceTimer = null;
+        // Event batching
+        this.pendingEvents = [];
+        this.batchTimer = null;
+        this.tracker = tracker;
+        this.sections = sections;
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+        if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+            // Initialize after DOM is ready
+            if (document.readyState === 'loading') {
+                document.addEventListener('DOMContentLoaded', () => this.initialize());
+            }
+            else {
+                setTimeout(() => this.initialize(), 0);
+            }
+        }
+    }
+    /**
+     * Initialize section tracking
+     */
+    initialize() {
+        if (this.isDestroyed)
+            return;
+        this.log('Initializing section tracking for', this.sections.length, 'sections');
+        // Setup intersection observer
+        this.setupIntersectionObserver();
+        // Setup scroll listener for velocity tracking
+        this.setupScrollListener();
+        // Initialize sections
+        this.initializeSections();
+    }
+    /**
+     * Setup IntersectionObserver for section visibility
+     */
+    setupIntersectionObserver() {
+        if (typeof IntersectionObserver === 'undefined') {
+            this.log('IntersectionObserver not supported');
+            return;
+        }
+        this.intersectionObserver = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                this.handleIntersection(entry);
+            });
+        }, {
+            threshold: [0, 0.1, 0.25, 0.5, 0.75, 1.0],
+            rootMargin: '0px',
+        });
+        this.log('IntersectionObserver created');
+    }
+    /**
+     * Setup scroll listener for velocity calculation
+     */
+    setupScrollListener() {
+        if (typeof window === 'undefined')
+            return;
+        const scrollHandler = () => {
+            if (this.scrollDebounceTimer !== null) {
+                clearTimeout(this.scrollDebounceTimer);
+            }
+            this.scrollDebounceTimer = window.setTimeout(() => {
+                this.updateScrollVelocity();
+                this.scrollDebounceTimer = null;
+            }, this.options.debounceDelay);
+        };
+        window.addEventListener('scroll', scrollHandler, { passive: true });
+        this.log('Scroll listener attached');
+    }
+    /**
+     * Initialize sections and start observing
+     */
+    initializeSections() {
+        for (const section of this.sections) {
+            const element = this.findElementByXPath(section.selector);
+            if (!element) {
+                this.log('Section element not found:', section.sectionName, 'selector:', section.selector);
+                continue;
+            }
+            // Initialize state
+            const state = {
+                element,
+                config: section,
+                entryTime: null,
+                exitTime: null,
+                isVisible: false,
+                lastScrollPosition: window.scrollY,
+                lastScrollTime: Date.now(),
+                entryScrollSpeed: 0,
+                exitScrollSpeed: 0,
+                maxVisibleArea: 0,
+            };
+            this.sectionStates.set(section.sectionName, state);
+            // Start observing
+            if (this.intersectionObserver) {
+                this.intersectionObserver.observe(element);
+            }
+            this.log('Section initialized and observed:', section.sectionName);
+        }
+    }
+    /**
+     * Handle intersection observer entry
+     */
+    handleIntersection(entry) {
+        if (this.isDestroyed)
+            return;
+        // Find which section this element belongs to
+        const state = Array.from(this.sectionStates.values()).find((s) => s.element === entry.target);
+        if (!state)
+            return;
+        const isVisible = entry.isIntersecting && entry.intersectionRatio >= this.options.intersectionThreshold;
+        const visibleArea = entry.intersectionRatio;
+        // Update max visible area
+        if (visibleArea > state.maxVisibleArea) {
+            state.maxVisibleArea = visibleArea;
+        }
+        // Handle visibility change
+        if (isVisible && !state.isVisible) {
+            // Section became visible
+            this.handleSectionEntry(state);
+        }
+        else if (!isVisible && state.isVisible) {
+            // Section became invisible
+            this.handleSectionExit(state);
+        }
+        state.isVisible = isVisible;
+    }
+    /**
+     * Handle section entry (became visible)
+     */
+    handleSectionEntry(state) {
+        this.log('Section entered view:', state.config.sectionName);
+        state.entryTime = Date.now();
+        state.entryScrollSpeed = this.scrollVelocity;
+        state.lastScrollPosition = window.scrollY;
+        state.lastScrollTime = Date.now();
+        state.maxVisibleArea = 0;
+    }
+    /**
+     * Handle section exit (became invisible)
+     */
+    handleSectionExit(state) {
+        this.log('Section exited view:', state.config.sectionName);
+        if (state.entryTime === null)
+            return;
+        state.exitTime = Date.now();
+        state.exitScrollSpeed = this.scrollVelocity;
+        const duration = state.exitTime - state.entryTime;
+        // Create section view data
+        const viewData = {
+            sectionName: state.config.sectionName,
+            sectionType: state.config.sectionType,
+            entryTime: state.entryTime,
+            exitTime: state.exitTime,
+            duration,
+            viewportWidth: window.innerWidth,
+            viewportHeight: window.innerHeight,
+            scrollDepth: this.calculateScrollDepth(),
+            visibleAreaPercentage: Math.round(state.maxVisibleArea * 100),
+            scrollSpeedAtEntry: state.entryScrollSpeed,
+            scrollSpeedAtExit: state.exitScrollSpeed,
+        };
+        // Apply sanitization and track if valid
+        if (this.shouldTrackSection(viewData)) {
+            this.queueSectionView(viewData);
+        }
+        else {
+            this.log('Section view filtered out:', state.config.sectionName, 'duration:', duration);
+        }
+        // Reset entry time
+        state.entryTime = null;
+    }
+    /**
+     * Update scroll velocity
+     */
+    updateScrollVelocity() {
+        const now = Date.now();
+        const currentPosition = window.scrollY;
+        const timeDelta = now - this.lastScrollTime;
+        const positionDelta = Math.abs(currentPosition - this.lastScrollPosition);
+        if (timeDelta > 0) {
+            this.scrollVelocity = (positionDelta / timeDelta) * 1000; // pixels per second
+        }
+        this.lastScrollPosition = currentPosition;
+        this.lastScrollTime = now;
+    }
+    /**
+     * Calculate current scroll depth as percentage
+     */
+    calculateScrollDepth() {
+        if (typeof window === 'undefined' || typeof document === 'undefined')
+            return 0;
+        const windowHeight = window.innerHeight;
+        const documentHeight = Math.max(document.body.scrollHeight, document.body.offsetHeight, document.documentElement.clientHeight, document.documentElement.scrollHeight, document.documentElement.offsetHeight);
+        const scrollTop = window.scrollY;
+        const scrollableHeight = documentHeight - windowHeight;
+        if (scrollableHeight <= 0)
+            return 100;
+        return Math.round((scrollTop / scrollableHeight) * 100);
+    }
+    /**
+     * Determine if section view should be tracked (sanitization)
+     */
+    shouldTrackSection(viewData) {
+        // Minimum dwell time check
+        if (viewData.duration < this.options.minDwellTime) {
+            return false;
+        }
+        // Check if user was rapidly scrolling through
+        const avgScrollSpeed = (viewData.scrollSpeedAtEntry + viewData.scrollSpeedAtExit) / 2;
+        if (avgScrollSpeed > this.options.scrollVelocityThreshold * 2) {
+            // Very fast scroll - likely not engaged
+            return false;
+        }
+        // Must have had some meaningful visible area
+        if (viewData.visibleAreaPercentage < 10) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Queue section view for batching
+     */
+    queueSectionView(viewData) {
+        this.pendingEvents.push(viewData);
+        this.log('Queued section view:', viewData.sectionName, 'duration:', viewData.duration);
+        // Setup batch timer if not already set
+        if (this.batchTimer === null) {
+            this.batchTimer = window.setTimeout(() => {
+                this.flushPendingEvents();
+            }, this.options.batchDelay);
+        }
+    }
+    /**
+     * Flush pending section view events
+     */
+    flushPendingEvents() {
+        if (this.isDestroyed || this.pendingEvents.length === 0)
+            return;
+        if (!this.tracker.hasConsent('analytics')) {
+            this.pendingEvents = [];
+            return;
+        }
+        this.log('Flushing', this.pendingEvents.length, 'section view events');
+        // Track each section view
+        for (const viewData of this.pendingEvents) {
+            this.tracker.trackSystemEvent('_grain_section_view', {
+                section_name: viewData.sectionName,
+                section_type: viewData.sectionType,
+                duration_ms: viewData.duration,
+                viewport_width: viewData.viewportWidth,
+                viewport_height: viewData.viewportHeight,
+                scroll_depth_percent: viewData.scrollDepth,
+                visible_area_percent: viewData.visibleAreaPercentage,
+                scroll_speed_entry: Math.round(viewData.scrollSpeedAtEntry || 0),
+                scroll_speed_exit: Math.round(viewData.scrollSpeedAtExit || 0),
+                entry_timestamp: viewData.entryTime,
+                exit_timestamp: viewData.exitTime,
+            });
+        }
+        // Clear pending events
+        this.pendingEvents = [];
+        this.batchTimer = null;
+    }
+    /**
+     * Find element by XPath selector
+     */
+    findElementByXPath(xpath) {
+        // Check cache first
+        if (this.xpathCache.has(xpath)) {
+            const cached = this.xpathCache.get(xpath);
+            if (cached && document.contains(cached)) {
+                return cached;
+            }
+            this.xpathCache.delete(xpath);
+        }
+        try {
+            const result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+            const element = result.singleNodeValue;
+            if (element) {
+                this.xpathCache.set(xpath, element);
+            }
+            return element;
+        }
+        catch (error) {
+            this.log('Error evaluating XPath:', xpath, error);
+            return null;
+        }
+    }
+    /**
+     * Log debug messages
+     */
+    log(...args) {
+        if (this.options.debug) {
+            console.log('[SectionTracking]', ...args);
+        }
+    }
+    /**
+     * Update sections configuration
+     */
+    updateSections(sections) {
+        if (this.isDestroyed)
+            return;
+        this.log('Updating sections configuration');
+        // Disconnect observer
+        if (this.intersectionObserver) {
+            this.intersectionObserver.disconnect();
+        }
+        // Clear state
+        this.sectionStates.clear();
+        this.xpathCache.clear();
+        // Update configuration
+        this.sections = sections;
+        // Reinitialize
+        this.setupIntersectionObserver();
+        this.initializeSections();
+    }
+    /**
+     * Cleanup and destroy
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        this.log('Destroying section tracking manager');
+        this.isDestroyed = true;
+        // Flush any pending events
+        this.flushPendingEvents();
+        // Clear timers
+        if (this.scrollDebounceTimer !== null) {
+            clearTimeout(this.scrollDebounceTimer);
+            this.scrollDebounceTimer = null;
+        }
+        if (this.batchTimer !== null) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+        // Disconnect intersection observer
+        if (this.intersectionObserver) {
+            this.intersectionObserver.disconnect();
+            this.intersectionObserver = null;
+        }
+        // Clear state
+        this.sectionStates.clear();
+        this.xpathCache.clear();
+        this.pendingEvents = [];
+    }
+}
+exports.SectionTrackingManager = SectionTrackingManager;
+//# sourceMappingURL=section-tracking.js.map

package/dist/types/auto-tracking.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Auto-tracking types for Grain Analytics SDK
+ */
+export interface InteractionConfig {
+    eventName: string;
+    description: string;
+    selector: string;
+    priority: number;
+    label: string;
+}
+export interface SectionConfig {
+    sectionName: string;
+    description: string;
+    sectionType: string;
+    selector: string;
+    importance: number;
+}
+export interface AutoTrackingConfig {
+    interactions: InteractionConfig[];
+    sections: SectionConfig[];
+}
+export interface SectionViewData {
+    sectionName: string;
+    sectionType: string;
+    entryTime: number;
+    exitTime: number;
+    duration: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    scrollDepth: number;
+    visibleAreaPercentage: number;
+    scrollSpeedAtEntry?: number;
+    scrollSpeedAtExit?: number;
+}
+export interface SectionTrackingOptions {
+    minDwellTime: number;
+    scrollVelocityThreshold: number;
+    intersectionThreshold: number;
+    debounceDelay: number;
+    batchDelay: number;
+    debug?: boolean;
+}
+export interface SectionTrackingState {
+    element: Element;
+    config: SectionConfig;
+    entryTime: number | null;
+    exitTime: number | null;
+    isVisible: boolean;
+    lastScrollPosition: number;
+    lastScrollTime: number;
+    entryScrollSpeed: number;
+    exitScrollSpeed: number;
+    maxVisibleArea: number;
+}
+//# sourceMappingURL=auto-tracking.d.ts.map

package/dist/types/auto-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-tracking.d.ts","sourceRoot":"","sources":["../../src/types/auto-tracking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,MAAM,CAAC;IAChC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainql/analytics-web",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Lightweight TypeScript SDK for sending analytics events and managing remote configurations via Grain's REST API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",