@mostly-good-metrics/javascript 0.4.4 → 0.5.1

package/src/client.test.ts

@@ -258,7 +258,7 @@ describe('MostlyGoodMetrics', () => {
       await new Promise((resolve) => setTimeout(resolve, 10));
 
       const events = await storage.fetchEvents(1);
-      expect(events[0].userId).toBe('user_456');
+      expect(events[0].user_id).toBe('user_456');
     });
 
     it('should not set empty userId', () => {
@@ -266,6 +266,97 @@ describe('MostlyGoodMetrics', () => {
       MostlyGoodMetrics.identify('');
       expect(MostlyGoodMetrics.shared?.userId).toBe('user_123');
     });
+
+    it('should send $identify event with email', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+      MostlyGoodMetrics.identify('user_123', { email: 'test@example.com' });
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvent = events.find((e) => e.name === '$identify');
+      expect(identifyEvent).toBeDefined();
+      expect(identifyEvent?.properties?.email).toBe('test@example.com');
+      expect(identifyEvent?.properties?.name).toBeUndefined();
+    });
+
+    it('should send $identify event with name', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+      MostlyGoodMetrics.identify('user_123', { name: 'John Doe' });
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvent = events.find((e) => e.name === '$identify');
+      expect(identifyEvent).toBeDefined();
+      expect(identifyEvent?.properties?.name).toBe('John Doe');
+      expect(identifyEvent?.properties?.email).toBeUndefined();
+    });
+
+    it('should send $identify event with both email and name', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+      MostlyGoodMetrics.identify('user_123', { email: 'test@example.com', name: 'John Doe' });
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvent = events.find((e) => e.name === '$identify');
+      expect(identifyEvent).toBeDefined();
+      expect(identifyEvent?.properties?.email).toBe('test@example.com');
+      expect(identifyEvent?.properties?.name).toBe('John Doe');
+    });
+
+    it('should not send $identify event without profile data', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+      MostlyGoodMetrics.identify('user_123');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvent = events.find((e) => e.name === '$identify');
+      expect(identifyEvent).toBeUndefined();
+    });
+
+    it('should debounce $identify event with same profile data', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+
+      MostlyGoodMetrics.identify('user_123', { email: 'debounce-test@example.com' });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Call again with same data - should not send another event
+      MostlyGoodMetrics.identify('user_123', { email: 'debounce-test@example.com' });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvents = events.filter((e) => e.name === '$identify');
+      expect(identifyEvents.length).toBe(1);
+    });
+
+    it('should send new $identify event when profile data changes', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+
+      MostlyGoodMetrics.identify('user_123', { email: 'change-test@example.com' });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Call with different email - should send new event
+      MostlyGoodMetrics.identify('user_123', { email: 'changed@example.com' });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvents = events.filter((e) => e.name === '$identify');
+      expect(identifyEvents.length).toBe(2);
+    });
+
+    it('should not send $identify event with empty profile', async () => {
+      MostlyGoodMetrics.resetIdentity(); // Clear any previous identify state
+      MostlyGoodMetrics.identify('user_123', {});
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(10);
+      const identifyEvent = events.find((e) => e.name === '$identify');
+      expect(identifyEvent).toBeUndefined();
+    });
   });
 
   describe('resetIdentity', () => {
@@ -283,6 +374,86 @@ describe('MostlyGoodMetrics', () => {
       MostlyGoodMetrics.resetIdentity();
       expect(MostlyGoodMetrics.shared?.userId).toBeNull();
     });
+
+    it('should keep anonymousId unchanged', () => {
+      const originalAnonymousId = MostlyGoodMetrics.shared?.anonymousId;
+      MostlyGoodMetrics.resetIdentity();
+      const newAnonymousId = MostlyGoodMetrics.shared?.anonymousId;
+      expect(newAnonymousId).toBe(originalAnonymousId);
+    });
+  });
+
+  describe('anonymousId', () => {
+    it('should auto-generate anonymousId on init', () => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+      expect(MostlyGoodMetrics.shared?.anonymousId).toBeDefined();
+      expect(MostlyGoodMetrics.shared?.anonymousId.length).toBeGreaterThan(0);
+    });
+
+    it('should include anonymousId as user_id in events when not identified', async () => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].user_id).toBe(MostlyGoodMetrics.shared?.anonymousId);
+    });
+
+    it('should allow wrapper SDK to override anonymousId', () => {
+      const customAnonymousId = 'react-native-device-id-12345';
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        anonymousId: customAnonymousId,
+      });
+      expect(MostlyGoodMetrics.shared?.anonymousId).toBe(customAnonymousId);
+    });
+
+    it('should include custom anonymousId as user_id in events', async () => {
+      const customAnonymousId = 'react-native-device-id-12345';
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        anonymousId: customAnonymousId,
+      });
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].user_id).toBe(customAnonymousId);
+    });
+
+    it('should use identified userId over anonymousId', async () => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+      MostlyGoodMetrics.identify('identified_user_123');
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].user_id).toBe('identified_user_123');
+    });
   });
 
   describe('flush', () => {

package/src/client.ts

@@ -12,10 +12,12 @@ import {
   ResolvedConfiguration,
   SystemEvents,
   SystemProperties,
+  UserProfile,
 } from './types';
 import {
   delay,
   detectDeviceType,
+  generateAnonymousId,
   generateUUID,
   getDeviceModel,
   getISOTimestamp,
@@ -42,6 +44,7 @@ export class MostlyGoodMetrics {
   private flushTimer: ReturnType<typeof setInterval> | null = null;
   private isFlushingInternal = false;
   private sessionIdValue: string;
+  private anonymousIdValue: string;
   private lifecycleSetup = false;
 
   /**
@@ -51,6 +54,13 @@ export class MostlyGoodMetrics {
     this.config = resolveConfiguration(config);
     this.sessionIdValue = generateUUID();
 
+    // Configure cookie settings before initializing anonymous ID
+    persistence.configureCookies(config.cookieDomain, config.disableCookies);
+    this.anonymousIdValue = persistence.initializeAnonymousId(
+      config.anonymousId,
+      generateAnonymousId
+    );
+
     // Set up logging
     setDebugLogging(this.config.enableDebugLogging);
 
@@ -113,9 +123,9 @@ export class MostlyGoodMetrics {
     }
   }
 
-  // ============================================================
+  // =====================================================
   // Static convenience methods (delegate to shared instance)
-  // ============================================================
+  // =====================================================
 
   /**
    * Track an event with the given name and optional properties.
@@ -125,10 +135,12 @@ export class MostlyGoodMetrics {
   }
 
   /**
-   * Identify the current user.
+   * Identify the current user with optional profile data.
+   * @param userId The user's unique identifier
+   * @param profile Optional profile data (email, name)
    */
-  static identify(userId: string): void {
-    MostlyGoodMetrics.instance?.identify(userId);
+  static identify(userId: string, profile?: UserProfile): void {
+    MostlyGoodMetrics.instance?.identify(userId, profile);
   }
 
   /**
@@ -201,9 +213,9 @@ export class MostlyGoodMetrics {
     return MostlyGoodMetrics.instance?.getSuperProperties() ?? {};
   }
 
-  // ============================================================
+  // =====================================================
   // Instance properties
-  // ============================================================
+  // =====================================================
 
   /**
    * Get the current user ID.
@@ -219,6 +231,13 @@ export class MostlyGoodMetrics {
     return this.sessionIdValue;
   }
 
+  /**
+   * Get the anonymous ID (auto-generated UUID, persisted across sessions).
+   */
+  get anonymousId(): string {
+    return this.anonymousIdValue;
+  }
+
   /**
    * Check if a flush operation is in progress.
    */
@@ -233,9 +252,9 @@ export class MostlyGoodMetrics {
     return { ...this.config };
   }
 
-  // ============================================================
+  // =====================================================
   // Instance methods
-  // ============================================================
+  // =====================================================
 
   /**
    * Track an event with the given name and optional properties.
@@ -265,11 +284,13 @@ export class MostlyGoodMetrics {
       name,
       client_event_id: generateUUID(),
       timestamp: getISOTimestamp(),
-      userId: this.userId ?? undefined,
-      sessionId: this.sessionIdValue,
+
+      user_id: this.userId ?? this.anonymousIdValue,
+
+      session_id: this.sessionIdValue,
       platform: this.config.platform,
-      appVersion: this.config.appVersion || undefined,
-      osVersion: this.config.osVersion || getOSVersion() || undefined,
+      app_version: this.config.appVersion || undefined,
+      os_version: this.config.osVersion || getOSVersion() || undefined,
       environment: this.config.environment,
       locale: getLocale(),
       timezone: getTimezone(),
@@ -288,9 +309,14 @@ export class MostlyGoodMetrics {
   }
 
   /**
-   * Identify the current user.
+   * Identify the current user with optional profile data.
+   * Profile data is sent to the backend via the $identify event.
+   * Debouncing: only sends $identify if payload changed or >24h since last send.
+   *
+   * @param userId The user's unique identifier
+   * @param profile Optional profile data (email, name)
    */
-  identify(userId: string): void {
+  identify(userId: string, profile?: UserProfile): void {
     if (!userId) {
       logger.warn('identify called with empty userId');
       return;
@@ -298,14 +324,78 @@ export class MostlyGoodMetrics {
 
     logger.debug(`Identifying user: ${userId}`);
     persistence.setUserId(userId);
+
+    // If profile data is provided, check if we should send $identify event
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional truthy check for non-empty strings
+    if (profile && (profile.email || profile.name)) {
+      this.sendIdentifyEventIfNeeded(userId, profile);
+    }
+  }
+
+  /**
+   * Send $identify event if debounce conditions are met.
+   * Only sends if: hash changed OR more than 24 hours since last send.
+   */
+  private sendIdentifyEventIfNeeded(userId: string, profile: UserProfile): void {
+    // Compute hash of the identify payload
+    const payloadString = JSON.stringify({ userId, email: profile.email, name: profile.name });
+    const currentHash = this.simpleHash(payloadString);
+
+    const storedHash = persistence.getIdentifyHash();
+    const lastSentAt = persistence.getIdentifyLastSentAt();
+    const now = Date.now();
+    const twentyFourHoursMs = 24 * 60 * 60 * 1000;
+
+    const hashChanged = storedHash !== currentHash;
+    const expiredTime = !lastSentAt || now - lastSentAt > twentyFourHoursMs;
+
+    if (hashChanged || expiredTime) {
+      logger.debug(
+        `Sending $identify event (hashChanged=${hashChanged}, expiredTime=${expiredTime})`
+      );
+
+      // Build properties object with only defined values
+      const properties: EventProperties = {};
+      if (profile.email) {
+        properties.email = profile.email;
+      }
+      if (profile.name) {
+        properties.name = profile.name;
+      }
+
+      // Track the $identify event
+      this.track(SystemEvents.IDENTIFY, properties);
+
+      // Update stored hash and timestamp
+      persistence.setIdentifyHash(currentHash);
+      persistence.setIdentifyLastSentAt(now);
+    } else {
+      logger.debug('Skipping $identify event (debounced)');
+    }
+  }
+
+  /**
+   * Simple hash function for debouncing.
+   * Uses a basic string hash - not cryptographic, just for comparison.
+   */
+  private simpleHash(str: string): string {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash; // Convert to 32-bit integer
+    }
+    return hash.toString(16);
   }
 
   /**
    * Reset user identity.
+   * Clears the user ID and identify debounce state.
    */
   resetIdentity(): void {
     logger.debug('Resetting user identity');
     persistence.setUserId(null);
+    persistence.clearIdentifyState();
   }
 
   /**
@@ -398,9 +488,9 @@ export class MostlyGoodMetrics {
     logger.debug('MostlyGoodMetrics instance destroyed');
   }
 
-  // ============================================================
+  // =====================================================
   // Private methods
-  // ============================================================
+  // =====================================================
 
   private async checkBatchSize(): Promise<void> {
     const count = await this.storage.eventCount();
@@ -466,10 +556,12 @@ export class MostlyGoodMetrics {
   private buildPayload(events: MGMEvent[]): MGMEventsPayload {
     const context: MGMEventContext = {
       platform: this.config.platform,
-      appVersion: this.config.appVersion || undefined,
-      osVersion: this.config.osVersion || getOSVersion() || undefined,
-      userId: this.userId ?? undefined,
-      sessionId: this.sessionIdValue,
+      app_version: this.config.appVersion || undefined,
+      os_version: this.config.osVersion || getOSVersion() || undefined,
+
+      user_id: this.userId ?? this.anonymousIdValue,
+
+      session_id: this.sessionIdValue,
       environment: this.config.environment,
       locale: getLocale(),
       timezone: getTimezone(),

package/src/index.ts

@@ -19,8 +19,11 @@
  *   page: '/checkout',
  * });
  *
- * // Identify users
- * MostlyGoodMetrics.identify('user_123');
+ * // Identify users with profile data
+ * MostlyGoodMetrics.identify('user_123', {
+ *   email: 'user@example.com',
+ *   name: 'Jane Doe',
+ * });
  * ```
  */
 
@@ -43,6 +46,7 @@ export type {
   SendResult,
   IEventStorage,
   INetworkClient,
+  UserProfile,
 } from './types';
 
 // Error class
@@ -65,6 +69,7 @@ export { FetchNetworkClient, createDefaultNetworkClient } from './network';
 
 // Utilities (for advanced usage)
 export {
+  generateAnonymousId,
   generateUUID,
   getISOTimestamp,
   isValidEventName,

package/src/storage.test.ts

@@ -322,3 +322,129 @@ describe('PersistenceManager super properties', () => {
     expect(props).toEqual({});
   });
 });
+
+describe('PersistenceManager anonymous ID (localStorage)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (localStorage.getItem as jest.Mock).mockReturnValue(null);
+    // Disable cookies for these tests to test localStorage behavior
+    persistence.configureCookies(undefined, true);
+  });
+
+  const generateMockUUID = () => 'mock-uuid-12345';
+
+  it('should generate anonymous ID if none exists', () => {
+    const id = persistence.initializeAnonymousId(undefined, generateMockUUID);
+    expect(id).toBe('mock-uuid-12345');
+    expect(localStorage.setItem).toHaveBeenCalledWith(
+      'mostlygoodmetrics_anonymous_id',
+      'mock-uuid-12345'
+    );
+  });
+
+  it('should return existing anonymous ID from localStorage', () => {
+    (localStorage.getItem as jest.Mock).mockReturnValueOnce('existing-anonymous-id');
+    const id = persistence.initializeAnonymousId(undefined, generateMockUUID);
+    expect(id).toBe('existing-anonymous-id');
+  });
+
+  it('should use override ID from wrapper SDK', () => {
+    const overrideId = 'react-native-device-id';
+    const id = persistence.initializeAnonymousId(overrideId, generateMockUUID);
+    expect(id).toBe(overrideId);
+    expect(localStorage.setItem).toHaveBeenCalledWith('mostlygoodmetrics_anonymous_id', overrideId);
+  });
+
+  it('should prefer override ID over existing persisted ID', () => {
+    (localStorage.getItem as jest.Mock).mockReturnValueOnce('existing-anonymous-id');
+    const overrideId = 'react-native-device-id';
+    const id = persistence.initializeAnonymousId(overrideId, generateMockUUID);
+    expect(id).toBe(overrideId);
+  });
+
+  it('should reset anonymous ID with new UUID', () => {
+    let callCount = 0;
+    const generateNewUUID = () => {
+      callCount++;
+      return `new-uuid-${callCount}`;
+    };
+
+    const id1 = persistence.resetAnonymousId(generateNewUUID);
+    expect(id1).toBe('new-uuid-1');
+
+    const id2 = persistence.resetAnonymousId(generateNewUUID);
+    expect(id2).toBe('new-uuid-2');
+    expect(id2).not.toBe(id1);
+  });
+
+  it('should persist anonymous ID to localStorage', () => {
+    persistence.setAnonymousId('test-anonymous-id');
+    expect(localStorage.setItem).toHaveBeenCalledWith(
+      'mostlygoodmetrics_anonymous_id',
+      'test-anonymous-id'
+    );
+  });
+
+  it('should get anonymous ID from localStorage', () => {
+    (localStorage.getItem as jest.Mock).mockReturnValueOnce('stored-anonymous-id');
+    const id = persistence.getAnonymousId();
+    expect(id).toBe('stored-anonymous-id');
+  });
+});
+
+describe('PersistenceManager anonymous ID (cookies)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (localStorage.getItem as jest.Mock).mockReturnValue(null);
+    // Clear document.cookie
+    document.cookie = 'mostlygoodmetrics_anonymous_id=; path=/; max-age=0';
+  });
+
+  const generateMockUUID = () => 'mock-uuid-12345';
+
+  it('should use cookies when enabled', () => {
+    persistence.configureCookies(undefined, false);
+    persistence.setAnonymousId('cookie-test-id');
+    expect(document.cookie).toContain('mostlygoodmetrics_anonymous_id=cookie-test-id');
+  });
+
+  it('should read from cookies before localStorage', () => {
+    persistence.configureCookies(undefined, false);
+    document.cookie = 'mostlygoodmetrics_anonymous_id=cookie-id; path=/';
+    (localStorage.getItem as jest.Mock).mockReturnValue('localStorage-id');
+
+    const id = persistence.getAnonymousId();
+    expect(id).toBe('cookie-id');
+  });
+
+  it('should fall back to localStorage when cookie is not set', () => {
+    persistence.configureCookies(undefined, false);
+    (localStorage.getItem as jest.Mock).mockReturnValue('localStorage-id');
+
+    const id = persistence.getAnonymousId();
+    expect(id).toBe('localStorage-id');
+  });
+
+  it('should set cookie with custom domain for cross-subdomain support', () => {
+    persistence.configureCookies('.example.com', false);
+    persistence.setAnonymousId('cross-domain-id');
+    // Note: jsdom rejects cookies for non-matching domains, so we verify localStorage fallback
+    // In real browsers, the cookie would be set with domain=.example.com
+    expect(localStorage.setItem).toHaveBeenCalledWith(
+      'mostlygoodmetrics_anonymous_id',
+      'cross-domain-id'
+    );
+  });
+
+  it('should not use cookies when disabled', () => {
+    persistence.configureCookies(undefined, true);
+    persistence.setAnonymousId('no-cookie-id');
+    // Cookie should not contain our ID (cleared in beforeEach)
+    expect(document.cookie).not.toContain('mostlygoodmetrics_anonymous_id=no-cookie-id');
+    // But localStorage should have it
+    expect(localStorage.setItem).toHaveBeenCalledWith(
+      'mostlygoodmetrics_anonymous_id',
+      'no-cookie-id'
+    );
+  });
+});