@grainql/analytics-web 2.1.1 → 2.2.0

package/dist/react/index.js

@@ -116,6 +116,23 @@ class GrainAnalytics {
             return v.toString(16);
         });
     }
+    /**
+     * Check if we should allow persistent storage (GDPR compliance)
+     *
+     * Returns true if:
+     * - Consent has been granted, OR
+     * - Not in opt-in mode, OR
+     * - User has been explicitly identified by the site (login/identify), OR
+     * - Using JWT auth strategy (functional/essential purpose)
+     */
+    shouldAllowPersistentStorage() {
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        const isOptInMode = this.config.consentMode === 'opt-in';
+        const userExplicitlyIdentified = !!this.globalUserId;
+        const isJWTAuth = this.config.authStrategy === 'JWT';
+        // Allow persistent storage if any of these conditions are met
+        return hasConsent || !isOptInMode || userExplicitlyIdentified || isJWTAuth;
+    }
     /**
      * Generate a proper UUIDv4 identifier for anonymous user ID
      */
@@ -125,10 +142,19 @@ class GrainAnalytics {
     /**
      * Initialize persistent anonymous user ID from cookies or localStorage
      * Priority: Cookie → localStorage → generate new
+     *
+     * GDPR Compliance: In opt-in mode without consent, we skip loading/saving
+     * persistent IDs unless the user has been explicitly identified by the site
+     * or when using JWT auth (functional/essential purpose)
      */
     initializePersistentAnonymousUserId() {
         if (typeof window === 'undefined')
             return;
+        // Check if we should avoid persistent storage (GDPR compliance)
+        if (!this.shouldAllowPersistentStorage()) {
+            this.log('Opt-in mode without consent: skipping persistent ID initialization (GDPR compliance)');
+            return; // Don't load or create persistent ID
+        }
         const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
         const cookieName = '_grain_uid';
         try {
@@ -166,10 +192,18 @@ class GrainAnalytics {
     }
     /**
      * Save persistent anonymous user ID to cookie and/or localStorage
+     *
+     * GDPR Compliance: In opt-in mode without consent, we don't persist IDs
+     * unless the user has been explicitly identified or using JWT auth
      */
     savePersistentAnonymousUserId(userId) {
         if (typeof window === 'undefined')
             return;
+        // Check if we should avoid persistent storage (GDPR compliance)
+        if (!this.shouldAllowPersistentStorage()) {
+            this.log('Opt-in mode without consent: skipping persistent ID save (GDPR compliance)');
+            return; // Don't save persistent ID
+        }
         const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
         const cookieName = '_grain_uid';
         try {
@@ -178,7 +212,7 @@ class GrainAnalytics {
                 const cookieOptions = {
                     maxAge: 365 * 24 * 60 * 60, // 365 days
                     sameSite: 'lax',
-                    secure: window.location.protocol === 'https:',
+                    secure: typeof window !== 'undefined' && window.location.protocol === 'https:',
                     ...this.config.cookieOptions,
                 };
                 (0, cookies_1.setCookie)(cookieName, userId, cookieOptions);
@@ -192,6 +226,9 @@ class GrainAnalytics {
     }
     /**
      * Get the effective user ID (global userId or persistent anonymous ID)
+     *
+     * GDPR Compliance: In opt-in mode without consent and no explicit user identification,
+     * this should not be called. Use getEphemeralSessionId() instead.
      */
     getEffectiveUserIdInternal() {
         if (this.globalUserId) {
@@ -202,16 +239,8 @@ class GrainAnalytics {
         }
         // Generate a new UUIDv4 identifier as fallback
         this.persistentAnonymousUserId = this.generateAnonymousUserId();
-        // Try to persist it
-        if (typeof window !== 'undefined') {
-            try {
-                const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
-                localStorage.setItem(storageKey, this.persistentAnonymousUserId);
-            }
-            catch (error) {
-                this.log('Failed to persist generated anonymous user ID:', error);
-            }
-        }
+        // Try to persist it (will be skipped in opt-in mode without consent)
+        this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
         return this.persistentAnonymousUserId;
     }
     log(...args) {
@@ -474,6 +503,8 @@ class GrainAnalytics {
         }
     }
     startFlushTimer() {
+        if (typeof window === 'undefined')
+            return;
         if (this.flushTimer) {
             clearInterval(this.flushTimer);
         }
@@ -557,7 +588,12 @@ class GrainAnalytics {
      */
     handleConsentGranted() {
         this.flushWaitingForConsentQueue();
-        // Track consent granted event with mapping
+        // Initialize persistent ID now that consent is granted (if not already initialized)
+        if (!this.persistentAnonymousUserId) {
+            this.initializePersistentAnonymousUserId();
+            this.log('Initialized persistent ID after consent grant');
+        }
+        // Track consent granted event with mapping from ephemeral to persistent ID
         if (this.ephemeralSessionId) {
             this.trackSystemEvent('_grain_consent_granted', {
                 previous_session_id: this.ephemeralSessionId,
@@ -727,19 +763,11 @@ class GrainAnalytics {
             this.persistentAnonymousUserId = null;
         }
         else {
-            // If clearing user ID, ensure we have a UUIDv4 identifier
+            // If clearing user ID, ensure we have an identifier
             if (!this.persistentAnonymousUserId) {
                 this.persistentAnonymousUserId = this.generateAnonymousUserId();
-                // Try to persist the new anonymous ID
-                if (typeof window !== 'undefined') {
-                    try {
-                        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
-                        localStorage.setItem(storageKey, this.persistentAnonymousUserId);
-                    }
-                    catch (error) {
-                        this.log('Failed to persist new anonymous user ID:', error);
-                    }
-                }
+                // Try to persist the new anonymous ID (respects GDPR opt-in mode)
+                this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
             }
         }
     }
@@ -1320,6 +1348,8 @@ class GrainAnalytics {
      * Start automatic configuration refresh timer
      */
     startConfigRefreshTimer() {
+        if (typeof window === 'undefined')
+            return;
         if (this.configRefreshTimer) {
             clearInterval(this.configRefreshTimer);
         }

package/dist/react/index.mjs

@@ -112,6 +112,23 @@ export class GrainAnalytics {
             return v.toString(16);
         });
     }
+    /**
+     * Check if we should allow persistent storage (GDPR compliance)
+     *
+     * Returns true if:
+     * - Consent has been granted, OR
+     * - Not in opt-in mode, OR
+     * - User has been explicitly identified by the site (login/identify), OR
+     * - Using JWT auth strategy (functional/essential purpose)
+     */
+    shouldAllowPersistentStorage() {
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        const isOptInMode = this.config.consentMode === 'opt-in';
+        const userExplicitlyIdentified = !!this.globalUserId;
+        const isJWTAuth = this.config.authStrategy === 'JWT';
+        // Allow persistent storage if any of these conditions are met
+        return hasConsent || !isOptInMode || userExplicitlyIdentified || isJWTAuth;
+    }
     /**
      * Generate a proper UUIDv4 identifier for anonymous user ID
      */
@@ -121,10 +138,19 @@ export class GrainAnalytics {
     /**
      * Initialize persistent anonymous user ID from cookies or localStorage
      * Priority: Cookie → localStorage → generate new
+     *
+     * GDPR Compliance: In opt-in mode without consent, we skip loading/saving
+     * persistent IDs unless the user has been explicitly identified by the site
+     * or when using JWT auth (functional/essential purpose)
      */
     initializePersistentAnonymousUserId() {
         if (typeof window === 'undefined')
             return;
+        // Check if we should avoid persistent storage (GDPR compliance)
+        if (!this.shouldAllowPersistentStorage()) {
+            this.log('Opt-in mode without consent: skipping persistent ID initialization (GDPR compliance)');
+            return; // Don't load or create persistent ID
+        }
         const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
         const cookieName = '_grain_uid';
         try {
@@ -162,10 +188,18 @@ export class GrainAnalytics {
     }
     /**
      * Save persistent anonymous user ID to cookie and/or localStorage
+     *
+     * GDPR Compliance: In opt-in mode without consent, we don't persist IDs
+     * unless the user has been explicitly identified or using JWT auth
      */
     savePersistentAnonymousUserId(userId) {
         if (typeof window === 'undefined')
             return;
+        // Check if we should avoid persistent storage (GDPR compliance)
+        if (!this.shouldAllowPersistentStorage()) {
+            this.log('Opt-in mode without consent: skipping persistent ID save (GDPR compliance)');
+            return; // Don't save persistent ID
+        }
         const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
         const cookieName = '_grain_uid';
         try {
@@ -174,7 +208,7 @@ export class GrainAnalytics {
                 const cookieOptions = {
                     maxAge: 365 * 24 * 60 * 60, // 365 days
                     sameSite: 'lax',
-                    secure: window.location.protocol === 'https:',
+                    secure: typeof window !== 'undefined' && window.location.protocol === 'https:',
                     ...this.config.cookieOptions,
                 };
                 setCookie(cookieName, userId, cookieOptions);
@@ -188,6 +222,9 @@ export class GrainAnalytics {
     }
     /**
      * Get the effective user ID (global userId or persistent anonymous ID)
+     *
+     * GDPR Compliance: In opt-in mode without consent and no explicit user identification,
+     * this should not be called. Use getEphemeralSessionId() instead.
      */
     getEffectiveUserIdInternal() {
         if (this.globalUserId) {
@@ -198,16 +235,8 @@ export class GrainAnalytics {
         }
         // Generate a new UUIDv4 identifier as fallback
         this.persistentAnonymousUserId = this.generateAnonymousUserId();
-        // Try to persist it
-        if (typeof window !== 'undefined') {
-            try {
-                const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
-                localStorage.setItem(storageKey, this.persistentAnonymousUserId);
-            }
-            catch (error) {
-                this.log('Failed to persist generated anonymous user ID:', error);
-            }
-        }
+        // Try to persist it (will be skipped in opt-in mode without consent)
+        this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
         return this.persistentAnonymousUserId;
     }
     log(...args) {
@@ -470,6 +499,8 @@ export class GrainAnalytics {
         }
     }
     startFlushTimer() {
+        if (typeof window === 'undefined')
+            return;
         if (this.flushTimer) {
             clearInterval(this.flushTimer);
         }
@@ -553,7 +584,12 @@ export class GrainAnalytics {
      */
     handleConsentGranted() {
         this.flushWaitingForConsentQueue();
-        // Track consent granted event with mapping
+        // Initialize persistent ID now that consent is granted (if not already initialized)
+        if (!this.persistentAnonymousUserId) {
+            this.initializePersistentAnonymousUserId();
+            this.log('Initialized persistent ID after consent grant');
+        }
+        // Track consent granted event with mapping from ephemeral to persistent ID
         if (this.ephemeralSessionId) {
             this.trackSystemEvent('_grain_consent_granted', {
                 previous_session_id: this.ephemeralSessionId,
@@ -723,19 +759,11 @@ export class GrainAnalytics {
             this.persistentAnonymousUserId = null;
         }
         else {
-            // If clearing user ID, ensure we have a UUIDv4 identifier
+            // If clearing user ID, ensure we have an identifier
             if (!this.persistentAnonymousUserId) {
                 this.persistentAnonymousUserId = this.generateAnonymousUserId();
-                // Try to persist the new anonymous ID
-                if (typeof window !== 'undefined') {
-                    try {
-                        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
-                        localStorage.setItem(storageKey, this.persistentAnonymousUserId);
-                    }
-                    catch (error) {
-                        this.log('Failed to persist new anonymous user ID:', error);
-                    }
-                }
+                // Try to persist the new anonymous ID (respects GDPR opt-in mode)
+                this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
             }
         }
     }
@@ -1316,6 +1344,8 @@ export class GrainAnalytics {
      * Start automatic configuration refresh timer
      */
     startConfigRefreshTimer() {
+        if (typeof window === 'undefined')
+            return;
         if (this.configRefreshTimer) {
             clearInterval(this.configRefreshTimer);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainql/analytics-web",
-  "version": "2.1.1",
+  "version": "2.2.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",
@@ -42,7 +42,10 @@
     "test:ci": "jest --ci --coverage",
     "prepublishOnly": "npm run clean && npm run build",
     "size": "npm run build && node scripts/bundle-analysis.js",
-    "size:limit": "size-limit"
+    "size:limit": "size-limit",
+    "dev:mini-app": "cd mini-app && npm run dev",
+    "build:mini-app": "cd mini-app && npm run build",
+    "start:mini-app": "cd mini-app && npm run start"
   },
   "keywords": [
     "analytics",