@grainql/analytics-web 2.2.1 → 2.4.0

package/dist/index.js

@@ -4,13 +4,21 @@
  * 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.GrainAnalytics = exports.getState = exports.getCountryCodeFromTimezone = exports.getCountry = exports.parseUTMParameters = exports.categorizeReferrer = 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");
+const attribution_1 = require("./attribution");
+Object.defineProperty(exports, "categorizeReferrer", { enumerable: true, get: function () { return attribution_1.categorizeReferrer; } });
+Object.defineProperty(exports, "parseUTMParameters", { enumerable: true, get: function () { return attribution_1.parseUTMParameters; } });
+// Re-export timezone-country utilities
+var countries_1 = require("./countries");
+Object.defineProperty(exports, "getCountry", { enumerable: true, get: function () { return countries_1.getCountry; } });
+Object.defineProperty(exports, "getCountryCodeFromTimezone", { enumerable: true, get: function () { return countries_1.getCountryCodeFromTimezone; } });
+Object.defineProperty(exports, "getState", { enumerable: true, get: function () { return countries_1.getState; } });
 class GrainAnalytics {
     constructor(config) {
         this.eventQueue = [];
@@ -31,6 +39,9 @@ class GrainAnalytics {
         this.pageTrackingManager = null;
         this.ephemeralSessionId = null;
         this.eventCountSinceLastHeartbeat = 0;
+        // Session tracking
+        this.sessionStartTime = Date.now();
+        this.sessionEventCount = 0;
         this.config = {
             apiUrl: 'https://api.grainql.com',
             authStrategy: 'NONE',
@@ -83,6 +94,8 @@ class GrainAnalytics {
         // Initialize automatic tracking (browser only)
         if (typeof window !== 'undefined') {
             this.initializeAutomaticTracking();
+            // Track session start
+            this.trackSessionStart();
         }
         // Set up consent change listener to flush waiting events and handle consent upgrade
         this.consentManager.addListener((state) => {
@@ -521,6 +534,8 @@ class GrainAnalytics {
         if (typeof window === 'undefined')
             return;
         const handleBeforeUnload = () => {
+            // Track session end
+            this.trackSessionEnd();
             if (this.eventQueue.length > 0) {
                 // Use beacon API for reliable delivery during page unload
                 const eventsToSend = [...this.eventQueue];
@@ -575,6 +590,7 @@ class GrainAnalytics {
                 this.pageTrackingManager = new page_tracking_1.PageTrackingManager(this, {
                     stripQueryParams: this.config.stripQueryParams,
                     debug: this.config.debug,
+                    tenantId: this.config.tenantId,
                 });
                 this.log('Auto page view tracking initialized');
             }
@@ -583,6 +599,150 @@ class GrainAnalytics {
             }
         }
     }
+    /**
+     * Track session start event
+     */
+    trackSessionStart() {
+        if (typeof window === 'undefined')
+            return;
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        const properties = {
+            session_id: this.getSessionId(),
+            timestamp: this.sessionStartTime,
+        };
+        if (hasConsent) {
+            const referrer = document.referrer || '';
+            const currentUrl = window.location.href;
+            // Parse UTM parameters
+            const utmParams = (0, attribution_1.parseUTMParameters)(currentUrl);
+            const sessionUTMs = (0, attribution_1.getSessionUTMParameters)() || utmParams;
+            // Get first-touch attribution
+            const firstTouch = (0, attribution_1.getOrCreateFirstTouchAttribution)(this.config.tenantId, referrer, currentUrl, sessionUTMs);
+            // Landing page
+            properties.landing_page = window.location.pathname;
+            // Referrer info
+            if (referrer) {
+                properties.referrer = referrer;
+                properties.referrer_domain = new URL(referrer).hostname;
+                properties.referrer_category = (0, attribution_1.categorizeReferrer)(referrer, currentUrl);
+            }
+            else {
+                properties.referrer_category = 'direct';
+            }
+            // UTM parameters
+            if (sessionUTMs.utm_source)
+                properties.utm_source = sessionUTMs.utm_source;
+            if (sessionUTMs.utm_medium)
+                properties.utm_medium = sessionUTMs.utm_medium;
+            if (sessionUTMs.utm_campaign)
+                properties.utm_campaign = sessionUTMs.utm_campaign;
+            if (sessionUTMs.utm_term)
+                properties.utm_term = sessionUTMs.utm_term;
+            if (sessionUTMs.utm_content)
+                properties.utm_content = sessionUTMs.utm_content;
+            // First-touch attribution
+            properties.first_touch_source = firstTouch.source;
+            properties.first_touch_medium = firstTouch.medium;
+            properties.first_touch_campaign = firstTouch.campaign;
+            properties.first_touch_referrer_category = firstTouch.referrer_category;
+            // Device and browser info
+            properties.device = this.getDeviceType();
+            properties.screen_resolution = `${screen.width}x${screen.height}`;
+            properties.viewport = `${window.innerWidth}x${window.innerHeight}`;
+            properties.browser = this.getBrowser();
+            properties.os = this.getOS();
+            properties.language = navigator.language || '';
+            properties.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        }
+        this.trackSystemEvent('_grain_session_start', properties);
+        this.log('Session started:', properties);
+    }
+    /**
+     * Track session end event
+     */
+    trackSessionEnd() {
+        if (typeof window === 'undefined')
+            return;
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        const sessionDuration = Date.now() - this.sessionStartTime;
+        const properties = {
+            session_id: this.getSessionId(),
+            session_duration: Math.floor(sessionDuration / 1000), // In seconds for easier querying
+            duration: sessionDuration, // Keep for backward compatibility
+            event_count: this.sessionEventCount,
+            timestamp: Date.now(),
+        };
+        if (hasConsent && this.pageTrackingManager) {
+            const pageCount = this.pageTrackingManager.getPageViewCount();
+            properties.pages_per_session = pageCount;
+            properties.page_count = pageCount; // Keep for backward compatibility
+        }
+        this.trackSystemEvent('_grain_session_end', properties);
+        this.log('Session ended:', properties);
+    }
+    /**
+     * Detect browser name
+     */
+    getBrowser() {
+        if (typeof navigator === 'undefined')
+            return 'Unknown';
+        const ua = navigator.userAgent;
+        if (ua.includes('Firefox/'))
+            return 'Firefox';
+        if (ua.includes('Edg/'))
+            return 'Edge';
+        if (ua.includes('Chrome/'))
+            return 'Chrome';
+        if (ua.includes('Safari/') && !ua.includes('Chrome/'))
+            return 'Safari';
+        if (ua.includes('Opera/') || ua.includes('OPR/'))
+            return 'Opera';
+        return 'Unknown';
+    }
+    /**
+     * Detect operating system
+     */
+    getOS() {
+        if (typeof navigator === 'undefined')
+            return 'Unknown';
+        const ua = navigator.userAgent;
+        if (ua.includes('Win'))
+            return 'Windows';
+        if (ua.includes('Mac'))
+            return 'macOS';
+        if (ua.includes('Linux'))
+            return 'Linux';
+        if (ua.includes('Android'))
+            return 'Android';
+        if (ua.includes('iOS') || ua.includes('iPhone') || ua.includes('iPad'))
+            return 'iOS';
+        return 'Unknown';
+    }
+    /**
+     * Detect device type (Mobile, Tablet, Desktop)
+     */
+    getDeviceType() {
+        if (typeof window === 'undefined' || typeof navigator === 'undefined')
+            return 'Unknown';
+        const ua = navigator.userAgent;
+        const width = window.innerWidth;
+        // Check for tablet-specific indicators
+        if (ua.includes('iPad') || (ua.includes('Android') && !ua.includes('Mobile'))) {
+            return 'Tablet';
+        }
+        // Check for mobile indicators
+        if (ua.includes('Mobile') || ua.includes('iPhone') || ua.includes('Android')) {
+            return 'Mobile';
+        }
+        // Fallback to screen width detection
+        if (width < 768) {
+            return 'Mobile';
+        }
+        else if (width >= 768 && width < 1024) {
+            return 'Tablet';
+        }
+        return 'Desktop';
+    }
     /**
      * Handle consent granted - upgrade ephemeral session to persistent user
      */
@@ -716,6 +876,7 @@ class GrainAnalytics {
             }
             this.eventQueue.push(formattedEvent);
             this.eventCountSinceLastHeartbeat++;
+            this.sessionEventCount++;
             this.log(`Queued event: ${event.eventName}`, event.properties);
             // Check if we should flush immediately
             if (opts.flush || this.eventQueue.length >= this.config.batchSize) {

package/dist/index.mjs

@@ -7,6 +7,10 @@ import { setCookie, getCookie, areCookiesEnabled } from './cookies.js';
 import { ActivityDetector } from './activity.js';
 import { HeartbeatManager } from './heartbeat.js';
 import { PageTrackingManager } from './page-tracking.js';
+import { categorizeReferrer, parseUTMParameters, getOrCreateFirstTouchAttribution, getSessionUTMParameters, } from './attribution.js';
+export { categorizeReferrer, parseUTMParameters };
+// Re-export timezone-country utilities
+export { getCountry, getCountryCodeFromTimezone, getState } from './countries.js';
 export class GrainAnalytics {
     constructor(config) {
         this.eventQueue = [];
@@ -27,6 +31,9 @@ export class GrainAnalytics {
         this.pageTrackingManager = null;
         this.ephemeralSessionId = null;
         this.eventCountSinceLastHeartbeat = 0;
+        // Session tracking
+        this.sessionStartTime = Date.now();
+        this.sessionEventCount = 0;
         this.config = {
             apiUrl: 'https://api.grainql.com',
             authStrategy: 'NONE',
@@ -79,6 +86,8 @@ export class GrainAnalytics {
         // Initialize automatic tracking (browser only)
         if (typeof window !== 'undefined') {
             this.initializeAutomaticTracking();
+            // Track session start
+            this.trackSessionStart();
         }
         // Set up consent change listener to flush waiting events and handle consent upgrade
         this.consentManager.addListener((state) => {
@@ -517,6 +526,8 @@ export class GrainAnalytics {
         if (typeof window === 'undefined')
             return;
         const handleBeforeUnload = () => {
+            // Track session end
+            this.trackSessionEnd();
             if (this.eventQueue.length > 0) {
                 // Use beacon API for reliable delivery during page unload
                 const eventsToSend = [...this.eventQueue];
@@ -571,6 +582,7 @@ export class GrainAnalytics {
                 this.pageTrackingManager = new PageTrackingManager(this, {
                     stripQueryParams: this.config.stripQueryParams,
                     debug: this.config.debug,
+                    tenantId: this.config.tenantId,
                 });
                 this.log('Auto page view tracking initialized');
             }
@@ -579,6 +591,150 @@ export class GrainAnalytics {
             }
         }
     }
+    /**
+     * Track session start event
+     */
+    trackSessionStart() {
+        if (typeof window === 'undefined')
+            return;
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        const properties = {
+            session_id: this.getSessionId(),
+            timestamp: this.sessionStartTime,
+        };
+        if (hasConsent) {
+            const referrer = document.referrer || '';
+            const currentUrl = window.location.href;
+            // Parse UTM parameters
+            const utmParams = parseUTMParameters(currentUrl);
+            const sessionUTMs = getSessionUTMParameters() || utmParams;
+            // Get first-touch attribution
+            const firstTouch = getOrCreateFirstTouchAttribution(this.config.tenantId, referrer, currentUrl, sessionUTMs);
+            // Landing page
+            properties.landing_page = window.location.pathname;
+            // Referrer info
+            if (referrer) {
+                properties.referrer = referrer;
+                properties.referrer_domain = new URL(referrer).hostname;
+                properties.referrer_category = categorizeReferrer(referrer, currentUrl);
+            }
+            else {
+                properties.referrer_category = 'direct';
+            }
+            // UTM parameters
+            if (sessionUTMs.utm_source)
+                properties.utm_source = sessionUTMs.utm_source;
+            if (sessionUTMs.utm_medium)
+                properties.utm_medium = sessionUTMs.utm_medium;
+            if (sessionUTMs.utm_campaign)
+                properties.utm_campaign = sessionUTMs.utm_campaign;
+            if (sessionUTMs.utm_term)
+                properties.utm_term = sessionUTMs.utm_term;
+            if (sessionUTMs.utm_content)
+                properties.utm_content = sessionUTMs.utm_content;
+            // First-touch attribution
+            properties.first_touch_source = firstTouch.source;
+            properties.first_touch_medium = firstTouch.medium;
+            properties.first_touch_campaign = firstTouch.campaign;
+            properties.first_touch_referrer_category = firstTouch.referrer_category;
+            // Device and browser info
+            properties.device = this.getDeviceType();
+            properties.screen_resolution = `${screen.width}x${screen.height}`;
+            properties.viewport = `${window.innerWidth}x${window.innerHeight}`;
+            properties.browser = this.getBrowser();
+            properties.os = this.getOS();
+            properties.language = navigator.language || '';
+            properties.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        }
+        this.trackSystemEvent('_grain_session_start', properties);
+        this.log('Session started:', properties);
+    }
+    /**
+     * Track session end event
+     */
+    trackSessionEnd() {
+        if (typeof window === 'undefined')
+            return;
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        const sessionDuration = Date.now() - this.sessionStartTime;
+        const properties = {
+            session_id: this.getSessionId(),
+            session_duration: Math.floor(sessionDuration / 1000), // In seconds for easier querying
+            duration: sessionDuration, // Keep for backward compatibility
+            event_count: this.sessionEventCount,
+            timestamp: Date.now(),
+        };
+        if (hasConsent && this.pageTrackingManager) {
+            const pageCount = this.pageTrackingManager.getPageViewCount();
+            properties.pages_per_session = pageCount;
+            properties.page_count = pageCount; // Keep for backward compatibility
+        }
+        this.trackSystemEvent('_grain_session_end', properties);
+        this.log('Session ended:', properties);
+    }
+    /**
+     * Detect browser name
+     */
+    getBrowser() {
+        if (typeof navigator === 'undefined')
+            return 'Unknown';
+        const ua = navigator.userAgent;
+        if (ua.includes('Firefox/'))
+            return 'Firefox';
+        if (ua.includes('Edg/'))
+            return 'Edge';
+        if (ua.includes('Chrome/'))
+            return 'Chrome';
+        if (ua.includes('Safari/') && !ua.includes('Chrome/'))
+            return 'Safari';
+        if (ua.includes('Opera/') || ua.includes('OPR/'))
+            return 'Opera';
+        return 'Unknown';
+    }
+    /**
+     * Detect operating system
+     */
+    getOS() {
+        if (typeof navigator === 'undefined')
+            return 'Unknown';
+        const ua = navigator.userAgent;
+        if (ua.includes('Win'))
+            return 'Windows';
+        if (ua.includes('Mac'))
+            return 'macOS';
+        if (ua.includes('Linux'))
+            return 'Linux';
+        if (ua.includes('Android'))
+            return 'Android';
+        if (ua.includes('iOS') || ua.includes('iPhone') || ua.includes('iPad'))
+            return 'iOS';
+        return 'Unknown';
+    }
+    /**
+     * Detect device type (Mobile, Tablet, Desktop)
+     */
+    getDeviceType() {
+        if (typeof window === 'undefined' || typeof navigator === 'undefined')
+            return 'Unknown';
+        const ua = navigator.userAgent;
+        const width = window.innerWidth;
+        // Check for tablet-specific indicators
+        if (ua.includes('iPad') || (ua.includes('Android') && !ua.includes('Mobile'))) {
+            return 'Tablet';
+        }
+        // Check for mobile indicators
+        if (ua.includes('Mobile') || ua.includes('iPhone') || ua.includes('Android')) {
+            return 'Mobile';
+        }
+        // Fallback to screen width detection
+        if (width < 768) {
+            return 'Mobile';
+        }
+        else if (width >= 768 && width < 1024) {
+            return 'Tablet';
+        }
+        return 'Desktop';
+    }
     /**
      * Handle consent granted - upgrade ephemeral session to persistent user
      */
@@ -712,6 +868,7 @@ export class GrainAnalytics {
             }
             this.eventQueue.push(formattedEvent);
             this.eventCountSinceLastHeartbeat++;
+            this.sessionEventCount++;
             this.log(`Queued event: ${event.eventName}`, event.properties);
             // Check if we should flush immediately
             if (opts.flush || this.eventQueue.length >= this.config.batchSize) {

package/dist/page-tracking.d.ts

@@ -5,12 +5,14 @@
 export interface PageTrackingConfig {
     stripQueryParams: boolean;
     debug?: boolean;
+    tenantId: string;
 }
 export interface PageTracker {
     trackSystemEvent(eventName: string, properties: Record<string, unknown>): void;
     hasConsent(category?: string): boolean;
     getEffectiveUserId(): string;
     getEphemeralSessionId(): string;
+    getSessionId(): string;
 }
 export declare class PageTrackingManager {
     private config;
@@ -19,6 +21,9 @@ export declare class PageTrackingManager {
     private currentPath;
     private originalPushState;
     private originalReplaceState;
+    private previousPage;
+    private landingPage;
+    private pageViewCount;
     constructor(tracker: PageTracker, config: PageTrackingConfig);
     /**
      * Setup History API listeners (pushState, replaceState, popstate)
@@ -40,6 +45,22 @@ export declare class PageTrackingManager {
      * Track the current page
      */
     private trackCurrentPage;
+    /**
+     * Extract domain from URL
+     */
+    private extractDomain;
+    /**
+     * Detect browser name
+     */
+    private getBrowser;
+    /**
+     * Detect operating system
+     */
+    private getOS;
+    /**
+     * Detect device type (Mobile, Tablet, Desktop)
+     */
+    private getDeviceType;
     /**
      * Extract path from URL, optionally stripping query parameters
      */
@@ -52,6 +73,10 @@ export declare class PageTrackingManager {
      * Manually track a page view (for custom navigation)
      */
     trackPage(page: string, properties?: Record<string, unknown>): void;
+    /**
+     * Get page view count for current session
+     */
+    getPageViewCount(): number;
     /**
      * Destroy the page tracker
      */

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

@@ -1 +1 @@
-{"version":3,"file":"page-tracking.d.ts","sourceRoot":"","sources":["../src/page-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,kBAAkB,IAAI,MAAM,CAAC;IAC7B,qBAAqB,IAAI,MAAM,CAAC;CACjC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,oBAAoB,CAA4C;gBAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB;IAY5D;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAK/B;;OAEG;IACH,OAAO,CAAC,cAAc,CAGpB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAGtB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmCxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgCnE;;OAEG;IACH,OAAO,IAAI,IAAI;CAyBhB"}
+{"version":3,"file":"page-tracking.d.ts","sourceRoot":"","sources":["../src/page-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,kBAAkB,IAAI,MAAM,CAAC;IAC7B,qBAAqB,IAAI,MAAM,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;CACxB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,oBAAoB,CAA4C;IACxE,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAK;gBAEd,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB;IAY5D;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAK/B;;OAEG;IACH,OAAO,CAAC,cAAc,CAGpB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAGtB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgHxB;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACH,OAAO,CAAC,KAAK;IAUb;;OAEG;IACH,OAAO,CAAC,aAAa;IAwBrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAyCnE;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,OAAO,IAAI,IAAI;CAyBhB"}