@mostly-good-metrics/javascript 0.2.0 → 0.4.0

package/src/storage.test.ts

@@ -1,4 +1,4 @@
-import { InMemoryEventStorage, LocalStorageEventStorage } from './storage';
+import { InMemoryEventStorage, LocalStorageEventStorage, persistence } from './storage';
 import { MGMEvent } from './types';
 
 const createMockEvent = (name: string): MGMEvent => ({
@@ -173,3 +173,152 @@ describe('LocalStorageEventStorage', () => {
     expect(events).toHaveLength(0);
   });
 });
+
+describe('PersistenceManager super properties', () => {
+  beforeEach(() => {
+    // Mock localStorage
+    const localStorageMock = (() => {
+      let store: Record<string, string> = {};
+      return {
+        getItem: jest.fn((key: string) => store[key] ?? null),
+        setItem: jest.fn((key: string, value: string) => {
+          store[key] = value;
+        }),
+        removeItem: jest.fn((key: string) => {
+          delete store[key];
+        }),
+        clear: jest.fn(() => {
+          store = {};
+        }),
+      };
+    })();
+
+    Object.defineProperty(window, 'localStorage', {
+      value: localStorageMock,
+      writable: true,
+    });
+
+    // Clear any existing super properties
+    persistence.clearSuperProperties();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+    persistence.clearSuperProperties();
+  });
+
+  it('should return empty object when no super properties are set', () => {
+    const props = persistence.getSuperProperties();
+    expect(props).toEqual({});
+  });
+
+  it('should set and get a single super property', () => {
+    persistence.setSuperProperty('tier', 'premium');
+
+    const props = persistence.getSuperProperties();
+    expect(props.tier).toBe('premium');
+  });
+
+  it('should set and get multiple super properties', () => {
+    persistence.setSuperProperties({
+      tier: 'enterprise',
+      region: 'us-west',
+      beta_user: true,
+    });
+
+    const props = persistence.getSuperProperties();
+    expect(props.tier).toBe('enterprise');
+    expect(props.region).toBe('us-west');
+    expect(props.beta_user).toBe(true);
+  });
+
+  it('should merge properties when setting multiple times', () => {
+    persistence.setSuperProperty('first', 'value1');
+    persistence.setSuperProperties({
+      second: 'value2',
+      third: 'value3',
+    });
+
+    const props = persistence.getSuperProperties();
+    expect(props.first).toBe('value1');
+    expect(props.second).toBe('value2');
+    expect(props.third).toBe('value3');
+  });
+
+  it('should override existing property with same key', () => {
+    persistence.setSuperProperty('key', 'original');
+    persistence.setSuperProperty('key', 'updated');
+
+    const props = persistence.getSuperProperties();
+    expect(props.key).toBe('updated');
+  });
+
+  it('should remove a single super property', () => {
+    persistence.setSuperProperties({
+      keep: 'this',
+      remove: 'this',
+    });
+
+    persistence.removeSuperProperty('remove');
+
+    const props = persistence.getSuperProperties();
+    expect(props.keep).toBe('this');
+    expect(props.remove).toBeUndefined();
+  });
+
+  it('should handle removing non-existent property gracefully', () => {
+    persistence.setSuperProperty('exists', 'value');
+
+    expect(() => persistence.removeSuperProperty('nonexistent')).not.toThrow();
+
+    const props = persistence.getSuperProperties();
+    expect(props.exists).toBe('value');
+  });
+
+  it('should clear all super properties', () => {
+    persistence.setSuperProperties({
+      prop1: 'value1',
+      prop2: 'value2',
+      prop3: 'value3',
+    });
+
+    persistence.clearSuperProperties();
+
+    const props = persistence.getSuperProperties();
+    expect(Object.keys(props)).toHaveLength(0);
+  });
+
+  it('should persist super properties to localStorage', () => {
+    persistence.setSuperProperties({
+      persistent: 'value',
+    });
+
+    expect(localStorage.setItem).toHaveBeenCalledWith(
+      'mostlygoodmetrics_super_properties',
+      JSON.stringify({ persistent: 'value' })
+    );
+  });
+
+  it('should handle various value types', () => {
+    persistence.setSuperProperties({
+      string_val: 'text',
+      number_val: 42,
+      boolean_val: true,
+      null_val: null,
+    });
+
+    const props = persistence.getSuperProperties();
+    expect(props.string_val).toBe('text');
+    expect(props.number_val).toBe(42);
+    expect(props.boolean_val).toBe(true);
+    expect(props.null_val).toBe(null);
+  });
+
+  it('should handle localStorage getItem returning corrupted JSON', () => {
+    (localStorage.getItem as jest.Mock).mockReturnValueOnce('not valid json {');
+
+    // Should not throw and should return empty object
+    const props = persistence.getSuperProperties();
+    expect(props).toEqual({});
+  });
+});

package/src/storage.ts

@@ -1,9 +1,10 @@
 import { logger } from './logger';
-import { Constraints, IEventStorage, MGMError, MGMEvent } from './types';
+import { Constraints, EventProperties, IEventStorage, MGMError, MGMEvent } from './types';
 
 const STORAGE_KEY = 'mostlygoodmetrics_events';
 const USER_ID_KEY = 'mostlygoodmetrics_user_id';
 const APP_VERSION_KEY = 'mostlygoodmetrics_app_version';
+const SUPER_PROPERTIES_KEY = 'mostlygoodmetrics_super_properties';
 
 /**
  * Check if we're running in a browser environment with localStorage available.
@@ -177,6 +178,7 @@ export function createDefaultStorage(maxEvents: number): IEventStorage {
 class PersistenceManager {
   private inMemoryUserId: string | null = null;
   private inMemoryAppVersion: string | null = null;
+  private inMemorySuperProperties: EventProperties = {};
 
   /**
    * Get the persisted user ID.
@@ -244,6 +246,69 @@ class PersistenceManager {
     }
     return false;
   }
+
+  /**
+   * Get all super properties.
+   */
+  getSuperProperties(): EventProperties {
+    if (isLocalStorageAvailable()) {
+      try {
+        const stored = localStorage.getItem(SUPER_PROPERTIES_KEY);
+        if (stored) {
+          return JSON.parse(stored) as EventProperties;
+        }
+      } catch (e) {
+        logger.warn('Failed to load super properties from localStorage', e);
+      }
+      return {};
+    }
+    return { ...this.inMemorySuperProperties };
+  }
+
+  /**
+   * Set a single super property.
+   */
+  setSuperProperty(key: string, value: EventProperties[string]): void {
+    const properties = this.getSuperProperties();
+    properties[key] = value;
+    this.saveSuperProperties(properties);
+  }
+
+  /**
+   * Set multiple super properties at once.
+   */
+  setSuperProperties(properties: EventProperties): void {
+    const current = this.getSuperProperties();
+    const merged = { ...current, ...properties };
+    this.saveSuperProperties(merged);
+  }
+
+  /**
+   * Remove a single super property.
+   */
+  removeSuperProperty(key: string): void {
+    const properties = this.getSuperProperties();
+    delete properties[key];
+    this.saveSuperProperties(properties);
+  }
+
+  /**
+   * Clear all super properties.
+   */
+  clearSuperProperties(): void {
+    this.saveSuperProperties({});
+  }
+
+  private saveSuperProperties(properties: EventProperties): void {
+    this.inMemorySuperProperties = properties;
+    if (isLocalStorageAvailable()) {
+      try {
+        localStorage.setItem(SUPER_PROPERTIES_KEY, JSON.stringify(properties));
+      } catch (e) {
+        logger.warn('Failed to save super properties to localStorage', e);
+      }
+    }
+  }
 }
 
 export const persistence = new PersistenceManager();

package/src/types.ts

@@ -159,6 +159,11 @@ export interface MGMEvent {
    */
   appVersion?: string;
 
+  /**
+   * The app build number (separate from version).
+   */
+  appBuildNumber?: string;
+
   /**
    * The OS version string.
    */
@@ -169,6 +174,21 @@ export interface MGMEvent {
    */
   environment: string;
 
+  /**
+   * The device manufacturer (e.g., "Apple", "Samsung").
+   */
+  deviceManufacturer?: string;
+
+  /**
+   * The user's locale (e.g., "en-US").
+   */
+  locale?: string;
+
+  /**
+   * The user's timezone (e.g., "America/New_York").
+   */
+  timezone?: string;
+
   /**
    * Custom properties attached to this event.
    */
@@ -182,10 +202,14 @@ export interface MGMEvent {
 export interface MGMEventContext {
   platform: Platform;
   appVersion?: string;
+  appBuildNumber?: string;
   osVersion?: string;
   userId?: string;
   sessionId?: string;
   environment: string;
+  deviceManufacturer?: string;
+  locale?: string;
+  timezone?: string;
 }
 
 /**

package/src/utils.test.ts

@@ -5,6 +5,8 @@ import {
   validateEventName,
   sanitizeProperties,
   resolveConfiguration,
+  getLocale,
+  getTimezone,
 } from './utils';
 import { Constraints, DefaultConfiguration, MGMError } from './types';
 
@@ -237,3 +239,32 @@ describe('resolveConfiguration', () => {
     expect(config.maxStoredEvents).toBe(Constraints.MIN_STORED_EVENTS);
   });
 });
+
+describe('getLocale', () => {
+  it('should return a non-empty string', () => {
+    const locale = getLocale();
+    expect(typeof locale).toBe('string');
+    expect(locale.length).toBeGreaterThan(0);
+  });
+
+  it('should return a locale-like string (e.g., en, en-US)', () => {
+    const locale = getLocale();
+    // Locale should be something like "en", "en-US", "fr-FR", etc.
+    expect(locale).toMatch(/^[a-z]{2}(-[A-Z]{2})?$/i);
+  });
+});
+
+describe('getTimezone', () => {
+  it('should return a string', () => {
+    const timezone = getTimezone();
+    expect(typeof timezone).toBe('string');
+  });
+
+  it('should return a valid IANA timezone or empty string', () => {
+    const timezone = getTimezone();
+    // Should be empty or a valid IANA timezone like "America/New_York" or "UTC"
+    if (timezone) {
+      expect(timezone).toMatch(/^([A-Za-z_]+\/[A-Za-z_]+|UTC)$/);
+    }
+  });
+});

package/src/utils.ts

@@ -310,3 +310,24 @@ export function getDeviceModel(): string {
 export function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/**
+ * Get the user's locale.
+ */
+export function getLocale(): string {
+  if (typeof navigator !== 'undefined') {
+    return navigator.language || 'en';
+  }
+  return 'en';
+}
+
+/**
+ * Get the user's timezone.
+ */
+export function getTimezone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || '';
+  } catch {
+    return '';
+  }
+}