@mostly-good-metrics/javascript 0.4.4 → 0.5.0

package/dist/types/types.d.ts

@@ -43,7 +43,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;
     /**
@@ -77,6 +77,25 @@ export interface MGMConfiguration {
      * If not provided, uses the JS SDK's version.
      */
     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.
@@ -96,7 +115,7 @@ export interface MGMConfiguration {
 /**
  * Internal resolved configuration with all defaults applied.
  */
-export interface ResolvedConfiguration extends Required<Omit<MGMConfiguration, 'storage' | 'networkClient' | 'onError'>> {
+export interface ResolvedConfiguration extends Required<Omit<MGMConfiguration, 'storage' | 'networkClient' | 'onError' | 'anonymousId' | 'cookieDomain' | 'disableCookies'>> {
     storage?: IEventStorage;
     networkClient?: INetworkClient;
     onError?: (error: MGMError) => void;
@@ -131,12 +150,13 @@ export interface MGMEvent {
     timestamp: string;
     /**
      * 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.
      */
@@ -144,15 +164,15 @@ 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.
      */
@@ -160,7 +180,7 @@ export interface MGMEvent {
     /**
      * The device manufacturer (e.g., "Apple", "Samsung").
      */
-    deviceManufacturer?: string;
+    device_manufacturer?: string;
     /**
      * The user's locale (e.g., "en-US").
      */
@@ -180,13 +200,13 @@ 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;
 }
@@ -306,7 +326,7 @@ export declare const DefaultConfiguration: {
     readonly flushInterval: 30;
     readonly maxStoredEvents: 10000;
     readonly enableDebugLogging: false;
-    readonly trackAppLifecycleEvents: true;
+    readonly trackAppLifecycleEvents: false;
 };
 /**
  * Validation constraints.

package/dist/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types/utils.d.ts

@@ -3,6 +3,11 @@ import { DeviceType, EventProperties, MGMConfiguration, Platform, ResolvedConfig
  * Generate a UUID v4 string.
  */
 export declare function generateUUID(): string;
+/**
+ * Generate an anonymous user ID with $anon_ prefix.
+ * Format: $anon_xxxxxxxxxxxx (12 random chars)
+ */
+export declare function generateAnonymousId(): string;
 /**
  * Get the current timestamp in ISO8601 format.
  */

package/dist/types/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,UAAU,EAEV,eAAe,EAEf,gBAAgB,EAEhB,QAAQ,EACR,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,QAAQ,GAAE,MAAuC,GAChD,eAAe,GAAG,SAAS,CAW7B;AA0DD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,qBAAqB,CAoCpF;AAeD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAQzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA0B7C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA0BrC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAyBvC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,UAAU,EAEV,eAAe,EAEf,gBAAgB,EAEhB,QAAQ,EACR,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAuBD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,QAAQ,GAAE,MAAuC,GAChD,eAAe,GAAG,SAAS,CAW7B;AA0DD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,qBAAqB,CAoCpF;AAeD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAQzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA0B7C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA0BrC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAyBvC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostly-good-metrics/javascript",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "JavaScript/TypeScript SDK for MostlyGoodMetrics - a lightweight analytics library for web applications",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

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', () => {
@@ -283,6 +283,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

@@ -16,6 +16,7 @@ import {
 import {
   delay,
   detectDeviceType,
+  generateAnonymousId,
   generateUUID,
   getDeviceModel,
   getISOTimestamp,
@@ -42,6 +43,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 +53,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 +122,9 @@ export class MostlyGoodMetrics {
     }
   }
 
-  // ============================================================
+  // =====================================================
   // Static convenience methods (delegate to shared instance)
-  // ============================================================
+  // =====================================================
 
   /**
    * Track an event with the given name and optional properties.
@@ -201,9 +210,9 @@ export class MostlyGoodMetrics {
     return MostlyGoodMetrics.instance?.getSuperProperties() ?? {};
   }
 
-  // ============================================================
+  // =====================================================
   // Instance properties
-  // ============================================================
+  // =====================================================
 
   /**
    * Get the current user ID.
@@ -219,6 +228,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 +249,9 @@ export class MostlyGoodMetrics {
     return { ...this.config };
   }
 
-  // ============================================================
+  // =====================================================
   // Instance methods
-  // ============================================================
+  // =====================================================
 
   /**
    * Track an event with the given name and optional properties.
@@ -265,11 +281,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(),
@@ -398,9 +416,9 @@ export class MostlyGoodMetrics {
     logger.debug('MostlyGoodMetrics instance destroyed');
   }
 
-  // ============================================================
+  // =====================================================
   // Private methods
-  // ============================================================
+  // =====================================================
 
   private async checkBatchSize(): Promise<void> {
     const count = await this.storage.eventCount();
@@ -466,10 +484,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

@@ -65,6 +65,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'
+    );
+  });
+});