@mostly-good-metrics/javascript 0.1.0 → 0.4.0

package/src/client.test.ts

@@ -144,6 +144,70 @@ describe('MostlyGoodMetrics', () => {
       expect(events[0].environment).toBe('production');
       expect(events[0].platform).toBeDefined();
     });
+
+    it('should include $sdk property defaulting to javascript', async () => {
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].properties?.$sdk).toBe('javascript');
+    });
+  });
+
+  describe('platform and sdk configuration', () => {
+    it('should use configured platform', async () => {
+      MostlyGoodMetrics.reset();
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        platform: 'ios',
+      });
+
+      MostlyGoodMetrics.track('test_event');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].platform).toBe('ios');
+    });
+
+    it('should use configured sdk', async () => {
+      MostlyGoodMetrics.reset();
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        sdk: 'react-native',
+      });
+
+      MostlyGoodMetrics.track('test_event');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].properties?.$sdk).toBe('react-native');
+    });
+
+    it('should allow both platform and sdk to be configured together', async () => {
+      MostlyGoodMetrics.reset();
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        platform: 'android',
+        sdk: 'react-native',
+      });
+
+      MostlyGoodMetrics.track('test_event');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].platform).toBe('android');
+      expect(events[0].properties?.$sdk).toBe('react-native');
+    });
   });
 
   describe('identify', () => {
@@ -342,5 +406,122 @@ describe('MostlyGoodMetrics', () => {
       await expect(MostlyGoodMetrics.clearPendingEvents()).resolves.not.toThrow();
       await expect(MostlyGoodMetrics.getPendingEventCount()).resolves.toBe(0);
     });
+
+    it('should not throw for super property methods when not configured', () => {
+      expect(() => MostlyGoodMetrics.setSuperProperty('key', 'value')).not.toThrow();
+      expect(() => MostlyGoodMetrics.setSuperProperties({ key: 'value' })).not.toThrow();
+      expect(() => MostlyGoodMetrics.removeSuperProperty('key')).not.toThrow();
+      expect(() => MostlyGoodMetrics.clearSuperProperties()).not.toThrow();
+      expect(MostlyGoodMetrics.getSuperProperties()).toEqual({});
+    });
+  });
+
+  describe('super properties', () => {
+    beforeEach(() => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+    });
+
+    afterEach(() => {
+      MostlyGoodMetrics.clearSuperProperties();
+    });
+
+    it('should set a single super property', () => {
+      MostlyGoodMetrics.setSuperProperty('plan', 'premium');
+
+      const props = MostlyGoodMetrics.getSuperProperties();
+      expect(props.plan).toBe('premium');
+    });
+
+    it('should set multiple super properties at once', () => {
+      MostlyGoodMetrics.setSuperProperties({
+        plan: 'enterprise',
+        role: 'admin',
+      });
+
+      const props = MostlyGoodMetrics.getSuperProperties();
+      expect(props.plan).toBe('enterprise');
+      expect(props.role).toBe('admin');
+    });
+
+    it('should merge with existing super properties', () => {
+      MostlyGoodMetrics.setSuperProperty('existing', 'value');
+      MostlyGoodMetrics.setSuperProperties({
+        new_prop: 'new_value',
+      });
+
+      const props = MostlyGoodMetrics.getSuperProperties();
+      expect(props.existing).toBe('value');
+      expect(props.new_prop).toBe('new_value');
+    });
+
+    it('should remove a single super property', () => {
+      MostlyGoodMetrics.setSuperProperties({
+        keep: 'this',
+        remove: 'this',
+      });
+
+      MostlyGoodMetrics.removeSuperProperty('remove');
+
+      const props = MostlyGoodMetrics.getSuperProperties();
+      expect(props.keep).toBe('this');
+      expect(props.remove).toBeUndefined();
+    });
+
+    it('should clear all super properties', () => {
+      MostlyGoodMetrics.setSuperProperties({
+        prop1: 'value1',
+        prop2: 'value2',
+      });
+
+      MostlyGoodMetrics.clearSuperProperties();
+
+      const props = MostlyGoodMetrics.getSuperProperties();
+      expect(Object.keys(props)).toHaveLength(0);
+    });
+
+    it('should include super properties in tracked events', async () => {
+      MostlyGoodMetrics.setSuperProperties({
+        user_tier: 'gold',
+        source: 'mobile',
+      });
+
+      MostlyGoodMetrics.track('purchase');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].properties?.user_tier).toBe('gold');
+      expect(events[0].properties?.source).toBe('mobile');
+    });
+
+    it('should allow event properties to override super properties', async () => {
+      MostlyGoodMetrics.setSuperProperty('source', 'default');
+
+      MostlyGoodMetrics.track('click', {
+        source: 'override',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].properties?.source).toBe('override');
+    });
+
+    it('should not allow super properties to override system properties', async () => {
+      MostlyGoodMetrics.setSuperProperty('$device_type', 'hacked');
+
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      // System properties should take precedence
+      expect(events[0].properties?.$device_type).not.toBe('hacked');
+    });
   });
 });

package/src/client.ts

@@ -16,11 +16,12 @@ import {
 import {
   delay,
   detectDeviceType,
-  detectPlatform,
   generateUUID,
   getDeviceModel,
   getISOTimestamp,
+  getLocale,
   getOSVersion,
+  getTimezone,
   resolveConfiguration,
   sanitizeProperties,
   validateEventName,
@@ -165,6 +166,41 @@ export class MostlyGoodMetrics {
     return MostlyGoodMetrics.instance?.getPendingEventCount() ?? Promise.resolve(0);
   }
 
+  /**
+   * Set a single super property that will be included with every event.
+   */
+  static setSuperProperty(key: string, value: EventProperties[string]): void {
+    MostlyGoodMetrics.instance?.setSuperProperty(key, value);
+  }
+
+  /**
+   * Set multiple super properties at once.
+   */
+  static setSuperProperties(properties: EventProperties): void {
+    MostlyGoodMetrics.instance?.setSuperProperties(properties);
+  }
+
+  /**
+   * Remove a single super property.
+   */
+  static removeSuperProperty(key: string): void {
+    MostlyGoodMetrics.instance?.removeSuperProperty(key);
+  }
+
+  /**
+   * Clear all super properties.
+   */
+  static clearSuperProperties(): void {
+    MostlyGoodMetrics.instance?.clearSuperProperties();
+  }
+
+  /**
+   * Get all current super properties.
+   */
+  static getSuperProperties(): EventProperties {
+    return MostlyGoodMetrics.instance?.getSuperProperties() ?? {};
+  }
+
   // ============================================================
   // Instance properties
   // ============================================================
@@ -213,12 +249,16 @@ export class MostlyGoodMetrics {
     }
 
     const sanitizedProperties = sanitizeProperties(properties);
+    const superProperties = persistence.getSuperProperties();
 
-    // Add system properties
+    // Merge properties: super properties < event properties < system properties
+    // Event properties override super properties, system properties are always added
     const mergedProperties: EventProperties = {
+      ...superProperties,
+      ...sanitizedProperties,
       [SystemProperties.DEVICE_TYPE]: detectDeviceType(),
       [SystemProperties.DEVICE_MODEL]: getDeviceModel(),
-      ...sanitizedProperties,
+      [SystemProperties.SDK]: this.config.sdk,
     };
 
     const event: MGMEvent = {
@@ -226,10 +266,12 @@ export class MostlyGoodMetrics {
       timestamp: getISOTimestamp(),
       userId: this.userId ?? undefined,
       sessionId: this.sessionIdValue,
-      platform: detectPlatform(),
+      platform: this.config.platform,
       appVersion: this.config.appVersion || undefined,
       osVersion: this.config.osVersion || getOSVersion() || undefined,
       environment: this.config.environment,
+      locale: getLocale(),
+      timezone: getTimezone(),
       properties: Object.keys(mergedProperties).length > 0 ? mergedProperties : undefined,
     };
 
@@ -307,6 +349,45 @@ export class MostlyGoodMetrics {
     return this.storage.eventCount();
   }
 
+  /**
+   * Set a single super property that will be included with every event.
+   */
+  setSuperProperty(key: string, value: EventProperties[string]): void {
+    logger.debug(`Setting super property: ${key}`);
+    persistence.setSuperProperty(key, value);
+  }
+
+  /**
+   * Set multiple super properties at once.
+   */
+  setSuperProperties(properties: EventProperties): void {
+    logger.debug(`Setting super properties: ${Object.keys(properties).join(', ')}`);
+    persistence.setSuperProperties(properties);
+  }
+
+  /**
+   * Remove a single super property.
+   */
+  removeSuperProperty(key: string): void {
+    logger.debug(`Removing super property: ${key}`);
+    persistence.removeSuperProperty(key);
+  }
+
+  /**
+   * Clear all super properties.
+   */
+  clearSuperProperties(): void {
+    logger.debug('Clearing all super properties');
+    persistence.clearSuperProperties();
+  }
+
+  /**
+   * Get all current super properties.
+   */
+  getSuperProperties(): EventProperties {
+    return persistence.getSuperProperties();
+  }
+
   /**
    * Clean up resources (stop timers, etc.).
    */
@@ -374,12 +455,14 @@ export class MostlyGoodMetrics {
 
   private buildPayload(events: MGMEvent[]): MGMEventsPayload {
     const context: MGMEventContext = {
-      platform: detectPlatform(),
+      platform: this.config.platform,
       appVersion: this.config.appVersion || undefined,
       osVersion: this.config.osVersion || getOSVersion() || undefined,
       userId: this.userId ?? undefined,
       sessionId: this.sessionIdValue,
       environment: this.config.environment,
+      locale: getLocale(),
+      timezone: getTimezone(),
     };
 
     return { events, context };

package/src/index.ts

@@ -37,6 +37,7 @@ export type {
   MGMEventContext,
   MGMEventsPayload,
   Platform,
+  SDK,
   DeviceType,
   MGMErrorType,
   SendResult,

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

@@ -73,6 +73,18 @@ export interface MGMConfiguration {
    */
   osVersion?: string;
 
+  /**
+   * Override the auto-detected platform.
+   * Use this when wrapping the SDK (e.g., React Native should pass 'ios' or 'android').
+   */
+  platform?: Platform;
+
+  /**
+   * The SDK identifier. Auto-set to 'javascript' but can be overridden by wrapper SDKs.
+   * @default "javascript"
+   */
+  sdk?: SDK;
+
   /**
    * Custom storage adapter. If not provided, uses localStorage in browsers
    * or in-memory storage in non-browser environments.
@@ -147,6 +159,11 @@ export interface MGMEvent {
    */
   appVersion?: string;
 
+  /**
+   * The app build number (separate from version).
+   */
+  appBuildNumber?: string;
+
   /**
    * The OS version string.
    */
@@ -157,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.
    */
@@ -170,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;
 }
 
 /**
@@ -185,9 +221,14 @@ export interface MGMEventsPayload {
 }
 
 /**
- * Supported platforms.
+ * Supported platforms (the actual OS/runtime).
+ */
+export type Platform = 'web' | 'ios' | 'android' | 'node';
+
+/**
+ * SDK identifiers.
  */
-export type Platform = 'web' | 'ios' | 'android' | 'react-native' | 'expo' | 'node';
+export type SDK = 'javascript' | 'react-native' | 'swift' | 'android';
 
 /**
  * Device types for automatic device detection.
@@ -310,6 +351,7 @@ export const SystemProperties = {
   DEVICE_MODEL: '$device_model',
   VERSION: '$version',
   PREVIOUS_VERSION: '$previous_version',
+  SDK: '$sdk',
 } as const;
 
 /**