@mostly-good-metrics/javascript 0.2.0 → 0.4.1

package/src/client.ts

@@ -19,7 +19,9 @@ import {
   generateUUID,
   getDeviceModel,
   getISOTimestamp,
+  getLocale,
   getOSVersion,
+  getTimezone,
   resolveConfiguration,
   sanitizeProperties,
   validateEventName,
@@ -164,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
   // ============================================================
@@ -212,17 +249,21 @@ 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(),
       [SystemProperties.SDK]: this.config.sdk,
-      ...sanitizedProperties,
     };
 
     const event: MGMEvent = {
       name,
+      client_event_id: generateUUID(),
       timestamp: getISOTimestamp(),
       userId: this.userId ?? undefined,
       sessionId: this.sessionIdValue,
@@ -230,6 +271,8 @@ export class MostlyGoodMetrics {
       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 +350,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.).
    */
@@ -380,6 +462,8 @@ export class MostlyGoodMetrics {
       userId: this.userId ?? undefined,
       sessionId: this.sessionIdValue,
       environment: this.config.environment,
+      locale: getLocale(),
+      timezone: getTimezone(),
     };
 
     return { events, context };

package/src/network.test.ts

@@ -0,0 +1,244 @@
+import { TextEncoder } from 'util';
+import { FetchNetworkClient } from './network';
+import { MGMEventsPayload, ResolvedConfiguration } from './types';
+
+// Polyfill TextEncoder for Jest environment
+global.TextEncoder = TextEncoder;
+
+describe('FetchNetworkClient', () => {
+  let networkClient: FetchNetworkClient;
+  let mockFetch: jest.Mock;
+  let capturedHeaders: Record<string, string>;
+
+  const createMockConfig = (
+    overrides: Partial<ResolvedConfiguration> = {}
+  ): ResolvedConfiguration => ({
+    apiKey: 'test-api-key',
+    baseURL: 'https://api.example.com',
+    maxStoredEvents: 1000,
+    flushIntervalMs: 30000,
+    maxBatchSize: 100,
+    environment: 'production',
+    platform: 'web',
+    sdk: 'javascript',
+    trackAppLifecycleEvents: false,
+    ...overrides,
+  });
+
+  const createMockPayload = (): MGMEventsPayload => ({
+    events: [
+      {
+        name: 'test_event',
+        client_event_id: '123e4567-e89b-12d3-a456-426614174000',
+        timestamp: new Date().toISOString(),
+        platform: 'web',
+        environment: 'production',
+      },
+    ],
+  });
+
+  beforeEach(() => {
+    networkClient = new FetchNetworkClient();
+    capturedHeaders = {};
+
+    mockFetch = jest.fn().mockImplementation((_url: string, options: RequestInit) => {
+      capturedHeaders = options.headers as Record<string, string>;
+      return Promise.resolve({
+        status: 204,
+        headers: new Headers(),
+      });
+    });
+
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('SDK identification headers', () => {
+    it('should include X-MGM-SDK header from config', async () => {
+      const config = createMockConfig({ sdk: 'react-native' });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-SDK']).toBe('react-native');
+    });
+
+    it('should include X-MGM-SDK-Version header', async () => {
+      const config = createMockConfig();
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-SDK-Version']).toBeDefined();
+      expect(capturedHeaders['X-MGM-SDK-Version']).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+
+    it('should include X-MGM-Platform header from config', async () => {
+      const config = createMockConfig({ platform: 'ios' });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-Platform']).toBe('ios');
+    });
+
+    it('should include X-MGM-Platform-Version when osVersion is configured', async () => {
+      const config = createMockConfig({ osVersion: '17.0' });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-Platform-Version']).toBe('17.0');
+    });
+
+    it('should include X-MGM-Key header with API key', async () => {
+      const config = createMockConfig({ apiKey: 'my-secret-key' });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-Key']).toBe('my-secret-key');
+    });
+
+    it('should include X-MGM-Bundle-Id when bundleId is configured', async () => {
+      const config = createMockConfig({ bundleId: 'com.example.app' });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-Bundle-Id']).toBe('com.example.app');
+    });
+
+    it('should not include X-MGM-Bundle-Id when bundleId is not configured', async () => {
+      const config = createMockConfig();
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-Bundle-Id']).toBeUndefined();
+    });
+
+    it('should include all SDK headers together', async () => {
+      const config = createMockConfig({
+        apiKey: 'test-key',
+        sdk: 'javascript',
+        platform: 'web',
+        osVersion: '14.0',
+        bundleId: 'com.test.app',
+      });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(capturedHeaders['X-MGM-Key']).toBe('test-key');
+      expect(capturedHeaders['X-MGM-SDK']).toBe('javascript');
+      expect(capturedHeaders['X-MGM-SDK-Version']).toBeDefined();
+      expect(capturedHeaders['X-MGM-Platform']).toBe('web');
+      expect(capturedHeaders['X-MGM-Platform-Version']).toBe('14.0');
+      expect(capturedHeaders['X-MGM-Bundle-Id']).toBe('com.test.app');
+    });
+  });
+
+  describe('sendEvents', () => {
+    it('should return success on 204 response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        status: 204,
+        headers: new Headers(),
+      });
+
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should return success on 200 response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        status: 200,
+        headers: new Headers(),
+      });
+
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should handle rate limiting (429) with Retry-After header', async () => {
+      mockFetch.mockResolvedValueOnce({
+        status: 429,
+        headers: new Headers({ 'Retry-After': '120' }),
+      });
+
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(false);
+      expect(result.shouldRetry).toBe(true);
+      expect(result.error?.type).toBe('RATE_LIMITED');
+    });
+
+    it('should handle client errors (4xx) without retry', async () => {
+      mockFetch.mockResolvedValueOnce({
+        status: 400,
+        headers: new Headers(),
+      });
+
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(false);
+      expect(result.shouldRetry).toBe(false);
+      expect(result.error?.type).toBe('BAD_REQUEST');
+    });
+
+    it('should handle server errors (5xx) with retry', async () => {
+      mockFetch.mockResolvedValueOnce({
+        status: 500,
+        headers: new Headers(),
+      });
+
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(false);
+      expect(result.shouldRetry).toBe(true);
+      expect(result.error?.type).toBe('SERVER_ERROR');
+    });
+
+    it('should handle network errors with retry', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Network failure'));
+
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(false);
+      expect(result.shouldRetry).toBe(true);
+      expect(result.error?.type).toBe('NETWORK_ERROR');
+    });
+
+    it('should send to correct endpoint', async () => {
+      const config = createMockConfig({ baseURL: 'https://api.test.com' });
+      await networkClient.sendEvents(createMockPayload(), config);
+
+      expect(mockFetch).toHaveBeenCalledWith('https://api.test.com/v1/events', expect.any(Object));
+    });
+
+    it('should use POST method', async () => {
+      await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ method: 'POST' })
+      );
+    });
+  });
+
+  describe('rate limiting', () => {
+    it('should not be rate limited initially', () => {
+      expect(networkClient.isRateLimited()).toBe(false);
+    });
+
+    it('should return null for retry time initially', () => {
+      expect(networkClient.getRetryAfterTime()).toBeNull();
+    });
+
+    it('should skip requests when rate limited', async () => {
+      // First request gets rate limited
+      mockFetch.mockResolvedValueOnce({
+        status: 429,
+        headers: new Headers({ 'Retry-After': '60' }),
+      });
+
+      await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      // Second request should be skipped
+      const result = await networkClient.sendEvents(createMockPayload(), createMockConfig());
+
+      expect(result.success).toBe(false);
+      expect(result.error?.type).toBe('RATE_LIMITED');
+      expect(mockFetch).toHaveBeenCalledTimes(1); // Only first request was made
+    });
+  });
+});

package/src/network.ts

@@ -7,9 +7,11 @@ import {
   ResolvedConfiguration,
   SendResult,
 } from './types';
+import { getOSVersion } from './utils';
 
 const EVENTS_ENDPOINT = '/v1/events';
 const REQUEST_TIMEOUT_MS = 60000; // 60 seconds
+const SDK_VERSION = '0.4.0';
 
 /**
  * Compress data using gzip if available (browser CompressionStream API).
@@ -72,9 +74,14 @@ export class FetchNetworkClient implements INetworkClient {
     const jsonBody = JSON.stringify(payload);
     const { data, compressed } = await compressIfNeeded(jsonBody);
 
+    const osVersion = config.osVersion || getOSVersion();
     const headers: Record<string, string> = {
       'Content-Type': 'application/json',
       'X-MGM-Key': config.apiKey,
+      'X-MGM-SDK': config.sdk,
+      'X-MGM-SDK-Version': SDK_VERSION,
+      'X-MGM-Platform': config.platform,
+      ...(osVersion && { 'X-MGM-Platform-Version': osVersion }),
     };
 
     if (config.bundleId) {

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();