@grainql/analytics-web 2.8.0 → 3.0.0

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v2.8.0 | MIT License | Development Build */
+/* Grain Analytics Web SDK v3.0.0 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;
@@ -2700,7 +2700,7 @@ var Grain = (() => {
   var DEFAULT_CONSENT_CATEGORIES = ["necessary", "analytics", "functional"];
   var CONSENT_VERSION = "1.0.0";
   var ConsentManager = class {
-    constructor(tenantId, consentMode = "opt-out") {
+    constructor(tenantId, consentMode = "cookieless") {
       this.consentState = null;
       this.listeners = [];
       this.consentMode = consentMode;
@@ -2710,9 +2710,8 @@ var Grain = (() => {
     /**
      * Load consent state from localStorage
      * 
-     * GDPR Compliance: In opt-in mode, we can use localStorage for consent preferences
-     * since storing consent choices is a legitimate interest and necessary for compliance.
-     * The consent preference itself is not tracking data.
+     * GDPR Compliance: localStorage only used for storing consent preferences
+     * (not for tracking), which is a legitimate interest for compliance.
      */
     loadConsentState() {
       if (typeof window === "undefined")
@@ -2725,7 +2724,7 @@ var Grain = (() => {
             ...parsed,
             timestamp: new Date(parsed.timestamp)
           };
-        } else if (this.consentMode === "opt-out" || this.consentMode === "disabled") {
+        } else if (this.consentMode === "gdpr-opt-out") {
           this.consentState = {
             granted: true,
             categories: DEFAULT_CONSENT_CATEGORIES,
@@ -2798,28 +2797,67 @@ var Grain = (() => {
       return this.consentState ? { ...this.consentState } : null;
     }
     /**
-     * Check if user has granted consent
+     * Check if user has granted consent for permanent IDs
      */
     hasConsent(category) {
-      if (this.consentMode === "disabled") {
-        return true;
-      }
-      if (this.consentMode === "opt-in" && !this.consentState) {
+      if (this.consentMode === "cookieless") {
         return false;
       }
-      if (!this.consentState?.granted) {
-        return false;
+      if (this.consentMode === "gdpr-strict") {
+        if (!this.consentState?.granted) {
+          return false;
+        }
       }
-      if (category) {
+      if (this.consentMode === "gdpr-opt-out") {
+        if (!this.consentState) {
+          return true;
+        }
+        if (!this.consentState.granted) {
+          return false;
+        }
+      }
+      if (category && this.consentState) {
         return this.consentState.categories.includes(category);
       }
+      return this.consentState?.granted ?? this.consentMode === "gdpr-opt-out";
+    }
+    /**
+     * Check if permanent IDs are allowed
+     */
+    shouldUsePermanentId() {
+      return this.hasConsent();
+    }
+    /**
+     * Check if we should strip query parameters from URLs
+     * Query params stripped unless:
+     * - Mode is gdpr-opt-out, OR
+     * - Mode is gdpr-strict AND consent given
+     */
+    shouldStripQueryParams() {
+      if (this.consentMode === "cookieless") {
+        return true;
+      }
+      if (this.consentMode === "gdpr-strict") {
+        return !this.hasConsent();
+      }
+      if (this.consentMode === "gdpr-opt-out") {
+        return false;
+      }
+      return true;
+    }
+    /**
+     * Check if we can track events (always true in v2.0)
+     * Even cookieless mode allows basic analytics with daily IDs
+     */
+    canTrack() {
       return true;
     }
     /**
      * Check if we should wait for consent before tracking
+     * Only relevant for GDPR Strict mode
      */
     shouldWaitForConsent() {
-      return this.consentMode === "opt-in" && !this.consentState?.granted;
+      return this.consentMode === "gdpr-strict" && !this.consentState?.granted;
     }
     /**
      * Add consent change listener
@@ -2861,6 +2899,19 @@ var Grain = (() => {
       } catch (error) {
       }
     }
+    /**
+     * Get current consent mode
+     */
+    getConsentMode() {
+      return this.consentMode;
+    }
+    /**
+     * Get ID mode based on consent state
+     * Returns 'cookieless' or 'permanent'
+     */
+    getIdMode() {
+      return this.shouldUsePermanentId() ? "permanent" : "cookieless";
+    }
   };
 
   // src/cookies.ts
@@ -2903,36 +2954,6 @@ var Grain = (() => {
     }
     return null;
   }
-  function deleteCookie(name, config) {
-    if (typeof document === "undefined")
-      return;
-    const parts = [
-      `${encodeURIComponent(name)}=`,
-      "max-age=0"
-    ];
-    if (config?.domain) {
-      parts.push(`domain=${config.domain}`);
-    }
-    if (config?.path) {
-      parts.push(`path=${config.path}`);
-    } else {
-      parts.push("path=/");
-    }
-    document.cookie = parts.join("; ");
-  }
-  function areCookiesEnabled() {
-    if (typeof document === "undefined")
-      return false;
-    try {
-      const testCookie = "_grain_cookie_test";
-      setCookie(testCookie, "test", { maxAge: 1 });
-      const result = getCookie(testCookie) === "test";
-      deleteCookie(testCookie);
-      return result;
-    } catch {
-      return false;
-    }
-  }
 
   // src/activity.ts
   var ActivityDetector = class {
@@ -6312,7 +6333,7 @@ var Grain = (() => {
       };
       if (hasConsent) {
         properties.title = document.title || "";
-        properties.full_url = currentUrl;
+        properties.full_url = this.cleanUrl(currentUrl);
         properties.session_id = this.tracker.getSessionId();
         if (referrer) {
           properties.referrer = referrer;
@@ -6417,14 +6438,18 @@ var Grain = (() => {
     }
     /**
      * Extract path from URL, optionally stripping query parameters
+     * Privacy-first: strips query params by default
      */
     extractPath(url) {
       try {
         const urlObj = new URL(url);
-        let path = urlObj.pathname + urlObj.hash;
+        let path = urlObj.pathname;
         if (!this.config.stripQueryParams && urlObj.search) {
           path += urlObj.search;
         }
+        if (!this.config.stripHash && urlObj.hash) {
+          path += urlObj.hash;
+        }
         return path;
       } catch (error) {
         if (this.config.debug) {
@@ -6433,6 +6458,20 @@ var Grain = (() => {
         return url;
       }
     }
+    /**
+     * Clean URL for privacy (strip query params based on config)
+     */
+    cleanUrl(url) {
+      if (!this.config.stripQueryParams) {
+        return url;
+      }
+      try {
+        const urlObj = new URL(url);
+        return `${urlObj.origin}${urlObj.pathname}${this.config.stripHash ? "" : urlObj.hash}`;
+      } catch (error) {
+        return url;
+      }
+    }
     /**
      * Get the current page path
      */
@@ -6501,6 +6540,172 @@ var Grain = (() => {
     }
   };
 
+  // src/id-manager.ts
+  function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash).toString(36);
+  }
+  function generateUUID() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : r & 3 | 8;
+      return v.toString(16);
+    });
+  }
+  function getBrowserFingerprint() {
+    if (typeof window === "undefined")
+      return "server";
+    const components = [
+      screen.width?.toString() || "",
+      screen.height?.toString() || "",
+      navigator.language || "",
+      Intl.DateTimeFormat().resolvedOptions().timeZone || ""
+    ];
+    return simpleHash(components.join("|"));
+  }
+  function getLocalDateString() {
+    const now = /* @__PURE__ */ new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+  }
+  var IdManager = class {
+    constructor(config) {
+      this.cachedDailyId = null;
+      this.dailyIdDate = null;
+      this.permanentId = null;
+      this.config = config;
+      if (config.mode === "permanent" && config.useLocalStorage) {
+        this.loadPermanentId();
+      }
+    }
+    /**
+     * Generate a daily rotating ID
+     * Rotates at midnight in user's local timezone
+     * Provides same-day continuity without persistent tracking
+     */
+    generateDailyRotatingId() {
+      const currentDate = getLocalDateString();
+      if (this.cachedDailyId && this.dailyIdDate === currentDate) {
+        return this.cachedDailyId;
+      }
+      const fingerprint = getBrowserFingerprint();
+      const seed = `${this.config.tenantId}|${currentDate}|${fingerprint}`;
+      const dailyId = `daily_${simpleHash(seed)}_${simpleHash(Date.now().toString())}`;
+      this.cachedDailyId = dailyId;
+      this.dailyIdDate = currentDate;
+      return dailyId;
+    }
+    /**
+     * Generate or retrieve permanent user ID
+     * Only used when consent is given
+     */
+    generatePermanentId() {
+      if (this.permanentId) {
+        return this.permanentId;
+      }
+      if (this.config.useLocalStorage) {
+        const stored = this.loadPermanentId();
+        if (stored) {
+          return stored;
+        }
+      }
+      const newId = generateUUID();
+      this.permanentId = newId;
+      if (this.config.useLocalStorage) {
+        this.savePermanentId(newId);
+      }
+      return newId;
+    }
+    /**
+     * Get the current user ID based on mode
+     */
+    getCurrentUserId() {
+      if (this.config.mode === "cookieless") {
+        return this.generateDailyRotatingId();
+      } else {
+        return this.generatePermanentId();
+      }
+    }
+    /**
+     * Switch ID mode (e.g., when consent is granted/revoked)
+     */
+    setMode(mode) {
+      this.config.mode = mode;
+      if (mode === "permanent") {
+        this.cachedDailyId = null;
+        this.dailyIdDate = null;
+      }
+      if (mode === "cookieless") {
+        this.permanentId = null;
+        if (this.config.useLocalStorage) {
+          this.clearPermanentId();
+        }
+      }
+    }
+    /**
+     * Load permanent ID from localStorage
+     */
+    loadPermanentId() {
+      if (typeof window === "undefined")
+        return null;
+      try {
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        const stored = localStorage.getItem(storageKey);
+        if (stored) {
+          this.permanentId = stored;
+          return stored;
+        }
+      } catch (error) {
+      }
+      return null;
+    }
+    /**
+     * Save permanent ID to localStorage
+     */
+    savePermanentId(id) {
+      if (typeof window === "undefined")
+        return;
+      try {
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        localStorage.setItem(storageKey, id);
+      } catch (error) {
+      }
+    }
+    /**
+     * Clear permanent ID from localStorage
+     */
+    clearPermanentId() {
+      if (typeof window === "undefined")
+        return;
+      try {
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        localStorage.removeItem(storageKey);
+      } catch (error) {
+      }
+    }
+    /**
+     * Get info about current ID for debugging
+     */
+    getIdInfo() {
+      const id = this.getCurrentUserId();
+      return {
+        mode: this.config.mode,
+        id,
+        isDailyRotating: id.startsWith("daily_")
+      };
+    }
+  };
+
   // src/index.ts
   var GrainAnalytics = class {
     constructor(config) {
@@ -6510,12 +6715,14 @@ var Grain = (() => {
       this.isDestroyed = false;
       this.globalUserId = null;
       this.persistentAnonymousUserId = null;
+      // Deprecated: use idManager instead
       // Remote Config properties
       this.configCache = null;
       this.configRefreshTimer = null;
       this.configChangeListeners = [];
       this.configFetchPromise = null;
       this.cookiesEnabled = false;
+      // Deprecated: cookies no longer used for IDs
       // Automatic Tracking properties
       this.activityDetector = null;
       this.heartbeatManager = null;
@@ -6550,11 +6757,10 @@ var Grain = (() => {
         configRefreshInterval: 3e5,
         // 5 minutes
         enableConfigCache: true,
-        // Privacy defaults
-        consentMode: "opt-out",
+        // Privacy defaults (v2.0)
+        consentMode: "cookieless",
+        // Default: privacy-first, no permanent tracking
         waitForConsent: false,
-        enableCookies: false,
-        anonymizeIP: false,
         disableAutoProperties: false,
         // Automatic Tracking defaults
         enableHeartbeat: true,
@@ -6564,23 +6770,25 @@ var Grain = (() => {
         // 5 minutes
         enableAutoPageView: true,
         stripQueryParams: true,
+        // Privacy-first: strip by default
+        stripHash: false,
         // Heatmap Tracking defaults
         enableHeatmapTracking: true,
         ...config,
         tenantId: config.tenantId
       };
       this.consentManager = new ConsentManager(this.config.tenantId, this.config.consentMode);
-      if (this.config.enableCookies) {
-        this.cookiesEnabled = areCookiesEnabled();
-        if (!this.cookiesEnabled && this.config.debug) {
-          console.warn("[Grain Analytics] Cookies are not available, falling back to localStorage");
-        }
-      }
+      const idMode = this.consentManager.getIdMode();
+      this.idManager = new IdManager({
+        mode: idMode,
+        tenantId: this.config.tenantId,
+        useLocalStorage: true
+        // For permanent IDs when consented
+      });
       if (config.userId) {
         this.globalUserId = config.userId;
       }
       this.validateConfig();
-      this.initializePersistentAnonymousUserId();
       this.setupBeforeUnload();
       this.startFlushTimer();
       this.initializeConfigCache();
@@ -6594,6 +6802,8 @@ var Grain = (() => {
         }
       }
       this.consentManager.addListener((state) => {
+        const idMode2 = this.consentManager.getIdMode();
+        this.idManager.setMode(idMode2);
         if (state.granted) {
           this.handleConsentGranted();
         }
@@ -6634,10 +6844,12 @@ var Grain = (() => {
      */
     shouldAllowPersistentStorage() {
       const hasConsent = this.consentManager.hasConsent("analytics");
-      const isOptInMode = this.config.consentMode === "opt-in";
+      const isCookieless = this.config.consentMode === "cookieless";
       const userExplicitlyIdentified = !!this.globalUserId;
       const isJWTAuth = this.config.authStrategy === "JWT";
-      return hasConsent || !isOptInMode || userExplicitlyIdentified || isJWTAuth;
+      if (isCookieless)
+        return false;
+      return hasConsent || userExplicitlyIdentified || isJWTAuth;
     }
     /**
      * Generate a proper UUIDv4 identifier for anonymous user ID
@@ -6720,21 +6932,19 @@ var Grain = (() => {
       }
     }
     /**
-     * Get the effective user ID (global userId or persistent anonymous ID)
+     * Get the effective user ID (v2.0)
      * 
-     * GDPR Compliance: In opt-in mode without consent and no explicit user identification,
-     * this should not be called. Use getEphemeralSessionId() instead.
+     * Privacy-first implementation:
+     * - Returns global userId if explicitly set (via identify/login)
+     * - Otherwise uses IdManager to generate:
+     *   - Daily rotating ID (cookieless mode)
+     *   - Permanent ID (with consent)
      */
     getEffectiveUserIdInternal() {
       if (this.globalUserId) {
         return this.globalUserId;
       }
-      if (this.persistentAnonymousUserId) {
-        return this.persistentAnonymousUserId;
-      }
-      this.persistentAnonymousUserId = this.generateAnonymousUserId();
-      this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
-      return this.persistentAnonymousUserId;
+      return this.idManager.getCurrentUserId();
     }
     log(...args) {
       if (this.config.debug) {
@@ -7072,6 +7282,7 @@ var Grain = (() => {
             this,
             {
               stripQueryParams: this.config.stripQueryParams,
+              stripHash: this.config.stripHash,
               debug: this.config.debug,
               tenantId: this.config.tenantId
             }
@@ -7365,11 +7576,12 @@ var Grain = (() => {
       const hasConsent = this.consentManager.hasConsent("analytics");
       const event = {
         eventName,
-        userId: hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId(),
+        userId: this.getEffectiveUserId(),
+        // IdManager handles daily vs permanent based on consent
         properties: {
           ...properties,
           _minimal: !hasConsent,
-          // Flag to indicate minimal tracking
+          // Flag to indicate minimal tracking (daily rotating ID)
           _consent_status: hasConsent ? "granted" : "pending"
         }
       };
@@ -7467,10 +7679,13 @@ var Grain = (() => {
           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;
-        }
+        const hasConsent = this.consentManager.hasConsent("analytics");
+        formattedEvent.properties = {
+          ...formattedEvent.properties,
+          _minimal: !hasConsent,
+          // Flag: true = daily rotating ID, false = permanent ID
+          _consent_status: hasConsent ? "granted" : "pending"
+        };
         this.eventQueue.push(formattedEvent);
         this.eventCountSinceLastHeartbeat++;
         this.sessionEventCount++;
@@ -8090,28 +8305,42 @@ var Grain = (() => {
     }
     // Privacy & Consent Methods
     /**
-     * Grant consent for tracking
+     * Grant consent for tracking (v2.0)
+     * Switches from cookie-less mode to permanent IDs
      * @param categories - Optional array of consent categories (e.g., ['analytics', 'functional'])
      */
     grantConsent(categories) {
       try {
         this.consentManager.grantConsent(categories);
-        this.log("Consent granted", categories);
+        const idMode = this.consentManager.getIdMode();
+        this.idManager.setMode(idMode);
+        this.log("Consent granted, switched to permanent IDs", categories);
+        if (this.waitingForConsentQueue.length > 0) {
+          this.log(`Processing ${this.waitingForConsentQueue.length} queued events`);
+          this.eventQueue.push(...this.waitingForConsentQueue);
+          this.waitingForConsentQueue = [];
+          this.flush();
+        }
       } catch (error) {
         const formattedError = this.formatError(error, "grantConsent");
         this.logError(formattedError);
       }
     }
     /**
-     * Revoke consent for tracking (opt-out)
+     * Revoke consent for tracking (v2.0)
+     * Switches from permanent IDs to cookie-less mode
      * @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);
-        this.eventQueue = [];
-        this.waitingForConsentQueue = [];
+        const idMode = this.consentManager.getIdMode();
+        this.idManager.setMode(idMode);
+        this.log("Consent revoked, switched to cookie-less mode", categories);
+        if (!this.consentManager.hasConsent()) {
+          this.eventQueue = [];
+          this.waitingForConsentQueue = [];
+        }
       } catch (error) {
         const formattedError = this.formatError(error, "revokeConsent");
         this.logError(formattedError);