@mostly-good-metrics/javascript 0.4.3 → 0.5.0

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'
+    );
+  });
+});

package/src/storage.ts

@@ -3,6 +3,7 @@ import { Constraints, EventProperties, IEventStorage, MGMError, MGMEvent } from
 
 const STORAGE_KEY = 'mostlygoodmetrics_events';
 const USER_ID_KEY = 'mostlygoodmetrics_user_id';
+const ANONYMOUS_ID_KEY = 'mostlygoodmetrics_anonymous_id';
 const APP_VERSION_KEY = 'mostlygoodmetrics_app_version';
 const SUPER_PROPERTIES_KEY = 'mostlygoodmetrics_super_properties';
 
@@ -23,6 +24,59 @@ function isLocalStorageAvailable(): boolean {
   }
 }
 
+/**
+ * Check if cookies are available in this environment.
+ */
+function isCookieAvailable(): boolean {
+  try {
+    if (typeof document === 'undefined' || typeof document.cookie === 'undefined') {
+      return false;
+    }
+    // Test if we can actually set a cookie
+    const testKey = '__mgm_cookie_test__';
+    document.cookie = `${testKey}=test; path=/; max-age=60`;
+    const hasTest = document.cookie.indexOf(testKey) !== -1;
+    // Clean up test cookie
+    document.cookie = `${testKey}=; path=/; max-age=0`;
+    return hasTest;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get a cookie value by name.
+ */
+function getCookie(name: string): string | null {
+  if (!isCookieAvailable()) {
+    return null;
+  }
+  const cookies = document.cookie.split(';');
+  for (const cookie of cookies) {
+    const [cookieName, cookieValue] = cookie.trim().split('=');
+    if (cookieName === name) {
+      return decodeURIComponent(cookieValue);
+    }
+  }
+  return null;
+}
+
+/**
+ * Set a cookie with optional domain for cross-subdomain support.
+ * Uses a 1-year expiry by default.
+ */
+function setCookie(name: string, value: string, domain?: string): void {
+  if (!isCookieAvailable()) {
+    return;
+  }
+  const maxAge = 365 * 24 * 60 * 60; // 1 year in seconds
+  let cookieString = `${name}=${encodeURIComponent(value)}; path=/; max-age=${maxAge}; SameSite=Lax`;
+  if (domain) {
+    cookieString += `; domain=${domain}`;
+  }
+  document.cookie = cookieString;
+}
+
 /**
  * In-memory event storage implementation.
  * Used as a fallback when localStorage is not available,
@@ -173,12 +227,32 @@ export function createDefaultStorage(maxEvents: number): IEventStorage {
 
 /**
  * Persistence helpers for user ID and app version.
- * These use localStorage when available, otherwise fall back to in-memory.
+ * Uses cookies first (for cross-subdomain support), then localStorage as fallback.
  */
 class PersistenceManager {
   private inMemoryUserId: string | null = null;
+  private inMemoryAnonymousId: string | null = null;
   private inMemoryAppVersion: string | null = null;
   private inMemorySuperProperties: EventProperties = {};
+  private cookieDomain: string | undefined = undefined;
+  private disableCookies = false;
+
+  /**
+   * Configure cookie settings.
+   * @param cookieDomain Domain for cross-subdomain cookies (e.g., '.example.com')
+   * @param disableCookies If true, only use localStorage (no cookies)
+   */
+  configureCookies(cookieDomain?: string, disableCookies?: boolean): void {
+    this.cookieDomain = cookieDomain;
+    this.disableCookies = disableCookies ?? false;
+  }
+
+  /**
+   * Check if cookies should be used.
+   */
+  private shouldUseCookies(): boolean {
+    return !this.disableCookies && isCookieAvailable();
+  }
 
   /**
    * Get the persisted user ID.
@@ -204,6 +278,84 @@ class PersistenceManager {
     this.inMemoryUserId = userId;
   }
 
+  /**
+   * Get the anonymous ID (auto-generated UUID).
+   * Checks cookies first, then localStorage, then in-memory.
+   */
+  getAnonymousId(): string | null {
+    // Try cookies first (for cross-subdomain support)
+    if (this.shouldUseCookies()) {
+      const cookieId = getCookie(ANONYMOUS_ID_KEY);
+      if (cookieId) {
+        return cookieId;
+      }
+    }
+
+    // Fall back to localStorage
+    if (isLocalStorageAvailable()) {
+      return localStorage.getItem(ANONYMOUS_ID_KEY);
+    }
+
+    return this.inMemoryAnonymousId;
+  }
+
+  /**
+   * Set the anonymous ID (persists across sessions).
+   * Saves to both cookies and localStorage for redundancy.
+   */
+  setAnonymousId(anonymousId: string): void {
+    // Save to cookies if enabled
+    if (this.shouldUseCookies()) {
+      setCookie(ANONYMOUS_ID_KEY, anonymousId, this.cookieDomain);
+    }
+
+    // Also save to localStorage as fallback
+    if (isLocalStorageAvailable()) {
+      localStorage.setItem(ANONYMOUS_ID_KEY, anonymousId);
+    }
+
+    this.inMemoryAnonymousId = anonymousId;
+  }
+
+  /**
+   * Initialize the anonymous ID. If an override is provided, use it.
+   * Otherwise, use existing persisted ID or generate a new UUID.
+   * @param overrideId Optional ID from wrapper SDK (e.g., React Native device ID)
+   * @param generateUUID Function to generate a UUID
+   */
+  initializeAnonymousId(overrideId: string | undefined, generateUUID: () => string): string {
+    // If wrapper SDK provides an override, always use it
+    if (overrideId) {
+      this.setAnonymousId(overrideId);
+      return overrideId;
+    }
+
+    // Check for existing persisted anonymous ID
+    const existingId = this.getAnonymousId();
+    if (existingId) {
+      // Ensure it's saved to cookies if we have cookie support now
+      if (this.shouldUseCookies() && !getCookie(ANONYMOUS_ID_KEY)) {
+        setCookie(ANONYMOUS_ID_KEY, existingId, this.cookieDomain);
+      }
+      return existingId;
+    }
+
+    // Generate and persist a new anonymous ID
+    const newId = generateUUID();
+    this.setAnonymousId(newId);
+    return newId;
+  }
+
+  /**
+   * Reset the anonymous ID to a new UUID.
+   * @param generateUUID Function to generate a UUID
+   */
+  resetAnonymousId(generateUUID: () => string): string {
+    const newId = generateUUID();
+    this.setAnonymousId(newId);
+    return newId;
+  }
+
   /**
    * Get the persisted app version (for detecting updates).
    */

package/src/types.ts

@@ -50,7 +50,7 @@ export interface MGMConfiguration {
   /**
    * Whether to automatically track app lifecycle events
    * ($app_opened, $app_backgrounded, $app_installed, $app_updated).
-   * @default true
+   * @default false
    */
   trackAppLifecycleEvents?: boolean;
 
@@ -91,6 +91,28 @@ export interface MGMConfiguration {
    */
   sdkVersion?: string;
 
+  /**
+   * Override the auto-generated anonymous user ID.
+   * Wrapper SDKs (e.g., React Native) can pass a device-specific ID here.
+   * If not provided, a UUID will be auto-generated and persisted.
+   */
+  anonymousId?: string;
+
+  /**
+   * Cookie domain for cross-subdomain tracking.
+   * Set to '.yourdomain.com' to share anonymous ID across subdomains.
+   * Example: '.example.com' allows sharing between app.example.com and www.example.com
+   */
+  cookieDomain?: string;
+
+  /**
+   * Disable cookie storage entirely.
+   * When true, only localStorage will be used (no cross-subdomain tracking).
+   * Useful for GDPR compliance or privacy-focused applications.
+   * @default false
+   */
+  disableCookies?: boolean;
+
   /**
    * Custom storage adapter. If not provided, uses localStorage in browsers
    * or in-memory storage in non-browser environments.
@@ -101,16 +123,27 @@ export interface MGMConfiguration {
    * Custom network client. If not provided, uses fetch-based client.
    */
   networkClient?: INetworkClient;
+
+  /**
+   * Callback invoked when a network error occurs.
+   * Useful for reporting errors to external services like Sentry.
+   * @param error The error that occurred
+   */
+  onError?: (error: MGMError) => void;
 }
 
 /**
  * Internal resolved configuration with all defaults applied.
  */
 export interface ResolvedConfiguration extends Required<
-  Omit<MGMConfiguration, 'storage' | 'networkClient'>
+  Omit<
+    MGMConfiguration,
+    'storage' | 'networkClient' | 'onError' | 'anonymousId' | 'cookieDomain' | 'disableCookies'
+  >
 > {
   storage?: IEventStorage;
   networkClient?: INetworkClient;
+  onError?: (error: MGMError) => void;
 }
 
 /**
@@ -152,13 +185,15 @@ export interface MGMEvent {
 
   /**
    * The user ID associated with this event.
+   * Uses identified user if set, otherwise falls back to anonymous UUID.
    */
-  userId?: string;
+
+  user_id: string;
 
   /**
    * The session ID associated with this event.
    */
-  sessionId?: string;
+  session_id?: string;
 
   /**
    * The platform this event was generated from.
@@ -168,17 +203,17 @@ export interface MGMEvent {
   /**
    * The app version string.
    */
-  appVersion?: string;
+  app_version?: string;
 
   /**
    * The app build number (separate from version).
    */
-  appBuildNumber?: string;
+  app_build_number?: string;
 
   /**
    * The OS version string.
    */
-  osVersion?: string;
+  os_version?: string;
 
   /**
    * The environment name.
@@ -188,7 +223,7 @@ export interface MGMEvent {
   /**
    * The device manufacturer (e.g., "Apple", "Samsung").
    */
-  deviceManufacturer?: string;
+  device_manufacturer?: string;
 
   /**
    * The user's locale (e.g., "en-US").
@@ -212,13 +247,15 @@ export interface MGMEvent {
  */
 export interface MGMEventContext {
   platform: Platform;
-  appVersion?: string;
-  appBuildNumber?: string;
-  osVersion?: string;
-  userId?: string;
-  sessionId?: string;
+  app_version?: string;
+  app_build_number?: string;
+  os_version?: string;
+
+  user_id: string;
+
+  session_id?: string;
   environment: string;
-  deviceManufacturer?: string;
+  device_manufacturer?: string;
   locale?: string;
   timezone?: string;
 }
@@ -375,7 +412,7 @@ export const DefaultConfiguration = {
   flushInterval: 30,
   maxStoredEvents: 10000,
   enableDebugLogging: false,
-  trackAppLifecycleEvents: true,
+  trackAppLifecycleEvents: false,
 } as const;
 
 /**

package/src/utils.test.ts

@@ -1,4 +1,5 @@
 import {
+  generateAnonymousId,
   generateUUID,
   getISOTimestamp,
   isValidEventName,
@@ -26,6 +27,26 @@ describe('generateUUID', () => {
   });
 });
 
+describe('generateAnonymousId', () => {
+  it('should generate an ID with $anon_ prefix', () => {
+    const id = generateAnonymousId();
+    expect(id).toMatch(/^\$anon_[a-z0-9]{12}$/);
+  });
+
+  it('should generate unique IDs', () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      ids.add(generateAnonymousId());
+    }
+    expect(ids.size).toBe(100);
+  });
+
+  it('should be 18 characters total ($anon_ + 12 random)', () => {
+    const id = generateAnonymousId();
+    expect(id.length).toBe(18);
+  });
+});
+
 describe('getISOTimestamp', () => {
   it('should return a valid ISO8601 timestamp', () => {
     const timestamp = getISOTimestamp();

package/src/utils.ts

@@ -29,6 +29,35 @@ export function generateUUID(): string {
   });
 }
 
+/**
+ * Generate a short random string for anonymous IDs.
+ * Uses base36 (0-9, a-z) for URL-safe, readable IDs.
+ */
+function generateRandomString(length: number): string {
+  const chars = '0123456789abcdefghijklmnopqrstuvwxyz';
+  let result = '';
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const array = new Uint8Array(length);
+    crypto.getRandomValues(array);
+    for (let i = 0; i < length; i++) {
+      result += chars[array[i] % chars.length];
+    }
+  } else {
+    for (let i = 0; i < length; i++) {
+      result += chars[Math.floor(Math.random() * chars.length)];
+    }
+  }
+  return result;
+}
+
+/**
+ * Generate an anonymous user ID with $anon_ prefix.
+ * Format: $anon_xxxxxxxxxxxx (12 random chars)
+ */
+export function generateAnonymousId(): string {
+  return `$anon_${generateRandomString(12)}`;
+}
+
 /**
  * Get the current timestamp in ISO8601 format.
  */
@@ -183,6 +212,7 @@ export function resolveConfiguration(config: MGMConfiguration): ResolvedConfigur
     sdkVersion: config.sdkVersion ?? '',
     storage: config.storage,
     networkClient: config.networkClient,
+    onError: config.onError,
   };
 }