@mostly-good-metrics/javascript 0.5.0 → 0.6.0

package/src/client.ts

@@ -3,6 +3,8 @@ import { createDefaultNetworkClient } from './network';
 import { createDefaultStorage, persistence } from './storage';
 import {
   EventProperties,
+  Experiment,
+  ExperimentsResponse,
   IEventStorage,
   INetworkClient,
   MGMConfiguration,
@@ -12,6 +14,7 @@ import {
   ResolvedConfiguration,
   SystemEvents,
   SystemProperties,
+  UserProfile,
 } from './types';
 import {
   delay,
@@ -46,6 +49,12 @@ export class MostlyGoodMetrics {
   private anonymousIdValue: string;
   private lifecycleSetup = false;
 
+  // A/B testing state
+  private experiments: Map<string, Experiment> = new Map();
+  private experimentsLoaded = false;
+  private experimentsReadyResolve: (() => void) | null = null;
+  private experimentsReadyPromise: Promise<void>;
+
   /**
    * Private constructor - use `configure` to create an instance.
    */
@@ -69,6 +78,11 @@ export class MostlyGoodMetrics {
     // Initialize network client
     this.networkClient = this.config.networkClient ?? createDefaultNetworkClient();
 
+    // Initialize experiments ready promise
+    this.experimentsReadyPromise = new Promise((resolve) => {
+      this.experimentsReadyResolve = resolve;
+    });
+
     logger.info(`MostlyGoodMetrics initialized with environment: ${this.config.environment}`);
 
     // Start auto-flush timer
@@ -78,6 +92,9 @@ export class MostlyGoodMetrics {
     if (this.config.trackAppLifecycleEvents) {
       this.setupLifecycleTracking();
     }
+
+    // Fetch experiments in background
+    void this.fetchExperiments();
   }
 
   /**
@@ -134,10 +151,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);
   }
 
   /**
@@ -210,6 +229,22 @@ export class MostlyGoodMetrics {
     return MostlyGoodMetrics.instance?.getSuperProperties() ?? {};
   }
 
+  /**
+   * Get the variant for an experiment.
+   * Returns the assigned variant ('a', 'b', etc.) or null if experiment not found.
+   */
+  static getVariant(experimentName: string): string | null {
+    return MostlyGoodMetrics.instance?.getVariant(experimentName) ?? null;
+  }
+
+  /**
+   * Returns a promise that resolves when experiments have been loaded.
+   * Useful for waiting before calling getVariant() to ensure server-side experiments are available.
+   */
+  static ready(): Promise<void> {
+    return MostlyGoodMetrics.instance?.ready() ?? Promise.resolve();
+  }
+
   // =====================================================
   // Instance properties
   // =====================================================
@@ -306,9 +341,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;
@@ -316,14 +356,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();
   }
 
   /**
@@ -407,6 +511,63 @@ export class MostlyGoodMetrics {
     return persistence.getSuperProperties();
   }
 
+  /**
+   * Get the variant for an experiment.
+   * Returns the assigned variant ('a', 'b', etc.) or null if experiment not found.
+   *
+   * Assignment is deterministic based on userId + experimentName, so the same
+   * user always gets the same variant for the same experiment.
+   *
+   * The variant is automatically stored as a super property (experiment_{name}: 'variant')
+   * so it's attached to all subsequent events.
+   */
+  getVariant(experimentName: string): string | null {
+    if (!experimentName) {
+      logger.warn('getVariant called with empty experimentName');
+      return null;
+    }
+
+    // Check if we have this experiment cached
+    const experiment = this.experiments.get(experimentName);
+
+    if (!experiment) {
+      if (this.experimentsLoaded) {
+        // Experiments loaded but this one doesn't exist
+        logger.debug(`Experiment not found: ${experimentName}`);
+        return null;
+      }
+      // Experiments not loaded yet - can't assign variant without knowing variants
+      logger.debug(`Experiments not loaded yet, cannot assign variant for: ${experimentName}`);
+      return null;
+    }
+
+    if (!experiment.variants || experiment.variants.length === 0) {
+      logger.warn(`Experiment ${experimentName} has no variants`);
+      return null;
+    }
+
+    // Get the user ID for deterministic assignment
+    const userId = this.userId ?? this.anonymousIdValue;
+
+    // Compute deterministic variant assignment
+    const variant = this.computeVariant(userId, experimentName, experiment.variants);
+
+    // Store as super property so it's attached to all events
+    const propertyName = `experiment_${this.toSnakeCase(experimentName)}`;
+    this.setSuperProperty(propertyName, variant);
+
+    logger.debug(`Assigned variant '${variant}' for experiment '${experimentName}'`);
+    return variant;
+  }
+
+  /**
+   * Returns a promise that resolves when experiments have been loaded.
+   * Useful for waiting before calling getVariant() to ensure server-side experiments are available.
+   */
+  ready(): Promise<void> {
+    return this.experimentsReadyPromise;
+  }
+
   /**
    * Clean up resources (stop timers, etc.).
    */
@@ -620,4 +781,87 @@ export class MostlyGoodMetrics {
     // the regular flush mechanism for most events
     logger.debug('Page unloading, attempting beacon flush');
   }
+
+  // =====================================================
+  // A/B Testing methods
+  // =====================================================
+
+  /**
+   * Fetch experiments from the server.
+   * Called automatically during initialization.
+   */
+  private async fetchExperiments(): Promise<void> {
+    const url = `${this.config.baseURL}/v1/experiments`;
+
+    try {
+      logger.debug('Fetching experiments...');
+
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+      });
+
+      if (!response.ok) {
+        logger.warn(`Failed to fetch experiments: ${response.status}`);
+        this.markExperimentsReady();
+        return;
+      }
+
+      const data = (await response.json()) as ExperimentsResponse;
+
+      // Cache experiments by ID
+      this.experiments.clear();
+      for (const experiment of data.experiments || []) {
+        this.experiments.set(experiment.id, experiment);
+      }
+
+      logger.debug(`Loaded ${this.experiments.size} experiments`);
+    } catch (e) {
+      logger.warn('Failed to fetch experiments', e);
+    } finally {
+      this.markExperimentsReady();
+    }
+  }
+
+  /**
+   * Mark experiments as loaded and resolve the ready promise.
+   */
+  private markExperimentsReady(): void {
+    this.experimentsLoaded = true;
+    if (this.experimentsReadyResolve) {
+      this.experimentsReadyResolve();
+      this.experimentsReadyResolve = null;
+    }
+  }
+
+  /**
+   * Compute a deterministic variant assignment based on userId and experimentName.
+   * Same user + same experiment = same variant (consistent assignment).
+   */
+  private computeVariant(userId: string, experimentName: string, variants: string[]): string {
+    // Create a deterministic hash from userId + experimentName
+    const hashInput = `${userId}:${experimentName}`;
+    const hash = this.simpleHash(hashInput);
+
+    // Convert hash to a positive number and mod by variant count
+    const hashNum = Math.abs(parseInt(hash, 16));
+    const variantIndex = hashNum % variants.length;
+
+    return variants[variantIndex];
+  }
+
+  /**
+   * Convert a string to snake_case.
+   * Used for experiment property names (e.g., "button-color" -> "button_color").
+   */
+  private toSnakeCase(str: string): string {
+    return str
+      .replace(/([A-Z])/g, '_$1')
+      .replace(/[-\s]+/g, '_')
+      .toLowerCase()
+      .replace(/^_/, '');
+  }
 }

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,9 @@ export type {
   SendResult,
   IEventStorage,
   INetworkClient,
+  UserProfile,
+  Experiment,
+  ExperimentsResponse,
 } from './types';
 
 // Error class

package/src/storage.ts

@@ -6,6 +6,8 @@ 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.
@@ -461,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

@@ -389,8 +389,46 @@ 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;
+}
+
+/**
+ * An experiment configuration from the server.
+ */
+export interface Experiment {
+  /**
+   * The experiment identifier (e.g., "button-color").
+   */
+  id: string;
+
+  /**
+   * The variants for this experiment (e.g., ["a", "b"]).
+   */
+  variants: string[];
+}
+
+/**
+ * Response from the experiments API endpoint.
+ */
+export interface ExperimentsResponse {
+  experiments: Experiment[];
+}
+
 /**
  * System property keys (prefixed with $).
  */