@mostly-good-metrics/javascript 0.4.4 → 0.5.1

package/src/storage.ts

@@ -3,8 +3,11 @@ 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';
+const IDENTIFY_HASH_KEY = 'mostlygoodmetrics_identify_hash';
+const IDENTIFY_TIMESTAMP_KEY = 'mostlygoodmetrics_identify_timestamp';
 
 /**
  * Check if we're running in a browser environment with localStorage available.
@@ -23,6 +26,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 +229,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 +280,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).
    */
@@ -309,6 +463,55 @@ class PersistenceManager {
       }
     }
   }
+
+  /**
+   * Get the stored identify hash (for debouncing).
+   */
+  getIdentifyHash(): string | null {
+    if (isLocalStorageAvailable()) {
+      return localStorage.getItem(IDENTIFY_HASH_KEY);
+    }
+    return null;
+  }
+
+  /**
+   * Set the identify hash.
+   */
+  setIdentifyHash(hash: string): void {
+    if (isLocalStorageAvailable()) {
+      localStorage.setItem(IDENTIFY_HASH_KEY, hash);
+    }
+  }
+
+  /**
+   * Get the timestamp of the last identify event sent.
+   */
+  getIdentifyLastSentAt(): number | null {
+    if (isLocalStorageAvailable()) {
+      const timestamp = localStorage.getItem(IDENTIFY_TIMESTAMP_KEY);
+      return timestamp ? parseInt(timestamp, 10) : null;
+    }
+    return null;
+  }
+
+  /**
+   * Set the timestamp of the last identify event sent.
+   */
+  setIdentifyLastSentAt(timestamp: number): void {
+    if (isLocalStorageAvailable()) {
+      localStorage.setItem(IDENTIFY_TIMESTAMP_KEY, timestamp.toString());
+    }
+  }
+
+  /**
+   * Clear identify debounce state (used when resetting identity).
+   */
+  clearIdentifyState(): void {
+    if (isLocalStorageAvailable()) {
+      localStorage.removeItem(IDENTIFY_HASH_KEY);
+      localStorage.removeItem(IDENTIFY_TIMESTAMP_KEY);
+    }
+  }
 }
 
 export const persistence = new PersistenceManager();

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.
@@ -114,7 +136,10 @@ export interface MGMConfiguration {
  * Internal resolved configuration with all defaults applied.
  */
 export interface ResolvedConfiguration extends Required<
-  Omit<MGMConfiguration, 'storage' | 'networkClient' | 'onError'>
+  Omit<
+    MGMConfiguration,
+    'storage' | 'networkClient' | 'onError' | 'anonymousId' | 'cookieDomain' | 'disableCookies'
+  >
 > {
   storage?: IEventStorage;
   networkClient?: INetworkClient;
@@ -160,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.
@@ -176,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.
@@ -196,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").
@@ -220,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;
 }
@@ -360,8 +389,24 @@ export const SystemEvents = {
   APP_UPDATED: '$app_updated',
   APP_OPENED: '$app_opened',
   APP_BACKGROUNDED: '$app_backgrounded',
+  IDENTIFY: '$identify',
 } as const;
 
+/**
+ * User profile data for the identify() call.
+ */
+export interface UserProfile {
+  /**
+   * The user's email address.
+   */
+  email?: string;
+
+  /**
+   * The user's display name.
+   */
+  name?: string;
+}
+
 /**
  * System property keys (prefixed with $).
  */
@@ -383,7 +428,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.
  */