@grainql/analytics-web 2.0.0 → 2.1.0

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v2.0.0 | MIT License | Development Build */
+/* Grain Analytics Web SDK v2.1.0 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;
@@ -26,9 +26,611 @@ var Grain = (() => {
     createGrainAnalytics: () => createGrainAnalytics,
     default: () => src_default
   });
+
+  // src/consent.ts
+  var DEFAULT_CONSENT_CATEGORIES = ["necessary", "analytics", "functional"];
+  var CONSENT_VERSION = "1.0.0";
+  var ConsentManager = class {
+    constructor(tenantId, consentMode = "opt-out") {
+      this.consentState = null;
+      this.listeners = [];
+      this.consentMode = consentMode;
+      this.storageKey = `grain_consent_${tenantId}`;
+      this.loadConsentState();
+    }
+    /**
+     * Load consent state from localStorage
+     */
+    loadConsentState() {
+      if (typeof window === "undefined")
+        return;
+      try {
+        const stored = localStorage.getItem(this.storageKey);
+        if (stored) {
+          const parsed = JSON.parse(stored);
+          this.consentState = {
+            ...parsed,
+            timestamp: new Date(parsed.timestamp)
+          };
+        } else if (this.consentMode === "opt-out" || this.consentMode === "disabled") {
+          this.consentState = {
+            granted: true,
+            categories: DEFAULT_CONSENT_CATEGORIES,
+            timestamp: /* @__PURE__ */ new Date(),
+            version: CONSENT_VERSION
+          };
+          this.saveConsentState();
+        }
+      } catch (error) {
+        console.error("[Grain Consent] Failed to load consent state:", error);
+      }
+    }
+    /**
+     * Save consent state to localStorage
+     */
+    saveConsentState() {
+      if (typeof window === "undefined" || !this.consentState)
+        return;
+      try {
+        localStorage.setItem(this.storageKey, JSON.stringify(this.consentState));
+      } catch (error) {
+        console.error("[Grain Consent] Failed to save consent state:", error);
+      }
+    }
+    /**
+     * Grant consent with optional categories
+     */
+    grantConsent(categories) {
+      const grantedCategories = categories || DEFAULT_CONSENT_CATEGORIES;
+      this.consentState = {
+        granted: true,
+        categories: grantedCategories,
+        timestamp: /* @__PURE__ */ new Date(),
+        version: CONSENT_VERSION
+      };
+      this.saveConsentState();
+      this.notifyListeners();
+    }
+    /**
+     * Revoke consent (opt-out)
+     */
+    revokeConsent(categories) {
+      if (!this.consentState) {
+        this.consentState = {
+          granted: false,
+          categories: [],
+          timestamp: /* @__PURE__ */ new Date(),
+          version: CONSENT_VERSION
+        };
+      } else if (categories) {
+        this.consentState = {
+          ...this.consentState,
+          categories: this.consentState.categories.filter((cat) => !categories.includes(cat)),
+          granted: this.consentState.categories.length > 0,
+          timestamp: /* @__PURE__ */ new Date()
+        };
+      } else {
+        this.consentState = {
+          granted: false,
+          categories: [],
+          timestamp: /* @__PURE__ */ new Date(),
+          version: CONSENT_VERSION
+        };
+      }
+      this.saveConsentState();
+      this.notifyListeners();
+    }
+    /**
+     * Get current consent state
+     */
+    getConsentState() {
+      return this.consentState ? { ...this.consentState } : null;
+    }
+    /**
+     * Check if user has granted consent
+     */
+    hasConsent(category) {
+      if (this.consentMode === "disabled") {
+        return true;
+      }
+      if (this.consentMode === "opt-in" && !this.consentState) {
+        return false;
+      }
+      if (!this.consentState?.granted) {
+        return false;
+      }
+      if (category) {
+        return this.consentState.categories.includes(category);
+      }
+      return true;
+    }
+    /**
+     * Check if we should wait for consent before tracking
+     */
+    shouldWaitForConsent() {
+      return this.consentMode === "opt-in" && !this.consentState?.granted;
+    }
+    /**
+     * Add consent change listener
+     */
+    addListener(listener) {
+      this.listeners.push(listener);
+    }
+    /**
+     * Remove consent change listener
+     */
+    removeListener(listener) {
+      const index = this.listeners.indexOf(listener);
+      if (index > -1) {
+        this.listeners.splice(index, 1);
+      }
+    }
+    /**
+     * Notify all listeners of consent state change
+     */
+    notifyListeners() {
+      if (!this.consentState)
+        return;
+      this.listeners.forEach((listener) => {
+        try {
+          listener(this.consentState);
+        } catch (error) {
+          console.error("[Grain Consent] Listener error:", error);
+        }
+      });
+    }
+    /**
+     * Clear all consent data
+     */
+    clearConsent() {
+      if (typeof window === "undefined")
+        return;
+      try {
+        localStorage.removeItem(this.storageKey);
+        this.consentState = null;
+      } catch (error) {
+        console.error("[Grain Consent] Failed to clear consent:", error);
+      }
+    }
+  };
+
+  // src/cookies.ts
+  function setCookie(name, value, config) {
+    if (typeof document === "undefined")
+      return;
+    const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+    if (config?.maxAge !== void 0) {
+      parts.push(`max-age=${config.maxAge}`);
+    }
+    if (config?.domain) {
+      parts.push(`domain=${config.domain}`);
+    }
+    if (config?.path) {
+      parts.push(`path=${config.path}`);
+    } else {
+      parts.push("path=/");
+    }
+    if (config?.sameSite) {
+      parts.push(`samesite=${config.sameSite}`);
+    }
+    if (config?.secure) {
+      parts.push("secure");
+    }
+    document.cookie = parts.join("; ");
+  }
+  function getCookie(name) {
+    if (typeof document === "undefined")
+      return null;
+    const nameEQ = encodeURIComponent(name) + "=";
+    const cookies = document.cookie.split(";");
+    for (let i = 0; i < cookies.length; i++) {
+      let cookie = cookies[i];
+      while (cookie.charAt(0) === " ") {
+        cookie = cookie.substring(1);
+      }
+      if (cookie.indexOf(nameEQ) === 0) {
+        return decodeURIComponent(cookie.substring(nameEQ.length));
+      }
+    }
+    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 {
+    constructor() {
+      this.activityThreshold = 3e4;
+      // 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;
+    }
+  };
+
+  // src/heartbeat.ts
+  var HeartbeatManager = class {
+    constructor(tracker, activityDetector, config) {
+      this.heartbeatTimer = null;
+      this.isDestroyed = false;
+      this.tracker = tracker;
+      this.activityDetector = activityDetector;
+      this.config = config;
+      this.lastHeartbeatTime = Date.now();
+      this.currentInterval = config.activeInterval;
+      this.scheduleNextHeartbeat();
+    }
+    /**
+     * Schedule the next heartbeat based on current activity
+     */
+    scheduleNextHeartbeat() {
+      if (this.isDestroyed)
+        return;
+      if (this.heartbeatTimer !== null) {
+        clearTimeout(this.heartbeatTimer);
+      }
+      const isActive = this.activityDetector.isActive(6e4);
+      this.currentInterval = isActive ? this.config.activeInterval : this.config.inactiveInterval;
+      this.heartbeatTimer = window.setTimeout(() => {
+        this.sendHeartbeat();
+        this.scheduleNextHeartbeat();
+      }, this.currentInterval);
+      if (this.config.debug) {
+        console.log(
+          `[Heartbeat] Scheduled next heartbeat in ${this.currentInterval / 1e3}s (${isActive ? "active" : "inactive"})`
+        );
+      }
+    }
+    /**
+     * Send heartbeat event
+     */
+    sendHeartbeat() {
+      if (this.isDestroyed)
+        return;
+      const now = Date.now();
+      const isActive = this.activityDetector.isActive(6e4);
+      const hasConsent = this.tracker.hasConsent("analytics");
+      const properties = {
+        type: "heartbeat",
+        status: isActive ? "active" : "inactive",
+        timestamp: now
+      };
+      if (hasConsent) {
+        const page = this.tracker.getCurrentPage();
+        if (page) {
+          properties.page = page;
+        }
+        properties.duration = now - this.lastHeartbeatTime;
+        properties.event_count = this.tracker.getEventCountSinceLastHeartbeat();
+        this.tracker.resetEventCountSinceLastHeartbeat();
+      }
+      this.tracker.trackSystemEvent("_grain_heartbeat", properties);
+      this.lastHeartbeatTime = now;
+      if (this.config.debug) {
+        console.log("[Heartbeat] Sent heartbeat:", properties);
+      }
+    }
+    /**
+     * Destroy the heartbeat manager
+     */
+    destroy() {
+      if (this.isDestroyed)
+        return;
+      if (this.heartbeatTimer !== null) {
+        clearTimeout(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+      }
+      this.isDestroyed = true;
+      if (this.config.debug) {
+        console.log("[Heartbeat] Destroyed");
+      }
+    }
+  };
+
+  // src/page-tracking.ts
+  var PageTrackingManager = class {
+    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;
+      this.trackCurrentPage();
+      this.setupHistoryListeners();
+      this.setupHashChangeListener();
+    }
+    /**
+     * Setup History API listeners (pushState, replaceState, popstate)
+     */
+    setupHistoryListeners() {
+      if (typeof window === "undefined" || typeof history === "undefined")
+        return;
+      this.originalPushState = history.pushState;
+      history.pushState = (state, title, url) => {
+        this.originalPushState?.call(history, state, title, url);
+        this.trackCurrentPage();
+      };
+      this.originalReplaceState = history.replaceState;
+      history.replaceState = (state, title, url) => {
+        this.originalReplaceState?.call(history, state, title, url);
+        this.trackCurrentPage();
+      };
+      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);
+      if (page === this.currentPath) {
+        return;
+      }
+      this.currentPath = page;
+      const hasConsent = this.tracker.hasConsent("analytics");
+      const properties = {
+        page,
+        timestamp: Date.now()
+      };
+      if (hasConsent) {
+        properties.referrer = document.referrer || "";
+        properties.title = document.title || "";
+        properties.full_url = window.location.href;
+      }
+      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 (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");
+      const baseProperties = {
+        page,
+        timestamp: Date.now(),
+        ...properties
+      };
+      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;
+      if (typeof history !== "undefined") {
+        if (this.originalPushState) {
+          history.pushState = this.originalPushState;
+        }
+        if (this.originalReplaceState) {
+          history.replaceState = this.originalReplaceState;
+        }
+      }
+      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");
+      }
+    }
+  };
+
+  // src/index.ts
   var GrainAnalytics = class {
     constructor(config) {
       this.eventQueue = [];
+      this.waitingForConsentQueue = [];
       this.flushTimer = null;
       this.isDestroyed = false;
       this.globalUserId = null;
@@ -38,6 +640,13 @@ var Grain = (() => {
       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",
@@ -56,9 +665,30 @@ var Grain = (() => {
         configRefreshInterval: 3e5,
         // 5 minutes
         enableConfigCache: true,
+        // Privacy defaults
+        consentMode: "opt-out",
+        waitForConsent: false,
+        enableCookies: false,
+        anonymizeIP: false,
+        disableAutoProperties: false,
+        // Automatic Tracking defaults
+        enableHeartbeat: true,
+        heartbeatActiveInterval: 12e4,
+        // 2 minutes
+        heartbeatInactiveInterval: 3e5,
+        // 5 minutes
+        enableAutoPageView: true,
+        stripQueryParams: 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");
+        }
+      }
       if (config.userId) {
         this.globalUserId = config.userId;
       }
@@ -67,6 +697,15 @@ var Grain = (() => {
       this.setupBeforeUnload();
       this.startFlushTimer();
       this.initializeConfigCache();
+      this.ephemeralSessionId = this.generateUUID();
+      if (typeof window !== "undefined") {
+        this.initializeAutomaticTracking();
+      }
+      this.consentManager.addListener((state) => {
+        if (state.granted) {
+          this.handleConsentGranted();
+        }
+      });
     }
     validateConfig() {
       if (!this.config.tenantId) {
@@ -99,20 +738,33 @@ var Grain = (() => {
       return this.generateUUID();
     }
     /**
-     * Initialize persistent anonymous user ID from localStorage or create new one
+     * 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 {
+        if (this.cookiesEnabled) {
+          const cookieValue = getCookie(cookieName);
+          if (cookieValue) {
+            this.persistentAnonymousUserId = cookieValue;
+            this.log("Loaded persistent anonymous user ID from cookie:", this.persistentAnonymousUserId);
+            return;
+          }
+        }
         const stored = localStorage.getItem(storageKey);
         if (stored) {
           this.persistentAnonymousUserId = stored;
-          this.log("Loaded persistent anonymous user ID:", this.persistentAnonymousUserId);
+          this.log("Loaded persistent anonymous user ID from localStorage:", this.persistentAnonymousUserId);
+          if (this.cookiesEnabled) {
+            this.savePersistentAnonymousUserId(stored);
+          }
         } else {
           this.persistentAnonymousUserId = this.generateAnonymousUserId();
-          localStorage.setItem(storageKey, this.persistentAnonymousUserId);
+          this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
           this.log("Generated new persistent anonymous user ID:", this.persistentAnonymousUserId);
         }
       } catch (error) {
@@ -120,10 +772,34 @@ var Grain = (() => {
         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 {
+        if (this.cookiesEnabled) {
+          const cookieOptions = {
+            maxAge: 365 * 24 * 60 * 60,
+            // 365 days
+            sameSite: "lax",
+            secure: window.location.protocol === "https:",
+            ...this.config.cookieOptions
+          };
+          setCookie(cookieName, userId, cookieOptions);
+        }
+        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)
      */
-    getEffectiveUserId() {
+    getEffectiveUserIdInternal() {
       if (this.globalUserId) {
         return this.globalUserId;
       }
@@ -256,7 +932,7 @@ var Grain = (() => {
     formatEvent(event) {
       return {
         eventName: event.eventName,
-        userId: event.userId || this.getEffectiveUserId(),
+        userId: event.userId || this.getEffectiveUserIdInternal(),
         properties: event.properties || {}
       };
     }
@@ -419,6 +1095,122 @@ var Grain = (() => {
         }
       });
     }
+    /**
+     * Initialize automatic tracking (heartbeat and page views)
+     */
+    initializeAutomaticTracking() {
+      if (this.config.enableHeartbeat) {
+        try {
+          this.activityDetector = new ActivityDetector();
+          this.heartbeatManager = new 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 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();
+      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");
+      const event = {
+        eventName,
+        userId: hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId(),
+        properties: {
+          ...properties,
+          _minimal: !hasConsent,
+          // Flag to indicate minimal tracking
+          _consent_status: hasConsent ? "granted" : "pending"
+        }
+      };
+      this.eventQueue.push(event);
+      this.eventCountSinceLastHeartbeat++;
+      this.log(`Queued system event: ${eventName}`, properties);
+      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) {
@@ -439,8 +1231,27 @@ var Grain = (() => {
           event = eventOrName;
           opts = propertiesOrOptions || {};
         }
+        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);
+        if (this.consentManager.shouldWaitForConsent() && this.config.waitForConsent) {
+          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);
         if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
           await this.flush();
@@ -450,6 +1261,20 @@ var Grain = (() => {
         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`);
+      this.eventQueue.push(...this.waitingForConsentQueue);
+      this.waitingForConsentQueue = [];
+      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)
      */
@@ -490,7 +1315,7 @@ var Grain = (() => {
      * Get current effective user ID (global userId or persistent anonymous ID)
      */
     getEffectiveUserIdPublic() {
-      return this.getEffectiveUserId();
+      return this.getEffectiveUserIdInternal();
     }
     /**
      * Login with auth token or userId on the fly
@@ -534,7 +1359,7 @@ var Grain = (() => {
           this.log(`Login: Setting auth strategy to ${options.authStrategy}`);
           this.config.authStrategy = options.authStrategy;
         }
-        this.log(`Login successful. Effective user ID: ${this.getEffectiveUserId()}`);
+        this.log(`Login successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`);
       } catch (error) {
         const formattedError = this.formatError(error, "login");
         this.logError(formattedError);
@@ -573,7 +1398,7 @@ var Grain = (() => {
             }
           }
         }
-        this.log(`Logout successful. Effective user ID: ${this.getEffectiveUserId()}`);
+        this.log(`Logout successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`);
       } catch (error) {
         const formattedError = this.formatError(error, "logout");
         this.logError(formattedError);
@@ -590,7 +1415,7 @@ var Grain = (() => {
           this.logError(formattedError);
           return;
         }
-        const userId = options?.userId || this.getEffectiveUserId();
+        const userId = options?.userId || this.getEffectiveUserIdInternal();
         const propertyKeys = Object.keys(properties);
         if (propertyKeys.length > 4) {
           const error = new Error("Grain Analytics: Maximum 4 properties allowed per request");
@@ -846,7 +1671,7 @@ var Grain = (() => {
           this.logError(formattedError);
           return null;
         }
-        const userId = options.userId || this.getEffectiveUserId();
+        const userId = options.userId || this.getEffectiveUserIdInternal();
         const immediateKeys = options.immediateKeys || [];
         const properties = options.properties || {};
         const request = {
@@ -1027,7 +1852,7 @@ var Grain = (() => {
      */
     async preloadConfig(immediateKeys = [], properties) {
       try {
-        const effectiveUserId = this.getEffectiveUserId();
+        const effectiveUserId = this.getEffectiveUserIdInternal();
         this.log(`Preloading config for user: ${effectiveUserId}`);
         const response = await this.fetchConfig({ immediateKeys, properties });
         if (response) {
@@ -1048,6 +1873,60 @@ var Grain = (() => {
       }
       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);
+        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
      */
@@ -1059,6 +1938,18 @@ var Grain = (() => {
       }
       this.stopConfigRefreshTimer();
       this.configChangeListeners = [];
+      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;
+      }
       if (this.eventQueue.length > 0) {
         const eventsToSend = [...this.eventQueue];
         this.eventQueue = [];