@mostly-good-metrics/javascript 0.1.0

package/src/network.ts

@@ -0,0 +1,230 @@
+import { logger } from './logger';
+import {
+  Constraints,
+  INetworkClient,
+  MGMError,
+  MGMEventsPayload,
+  ResolvedConfiguration,
+  SendResult,
+} from './types';
+
+const EVENTS_ENDPOINT = '/v1/events';
+const REQUEST_TIMEOUT_MS = 60000; // 60 seconds
+
+/**
+ * Compress data using gzip if available (browser CompressionStream API).
+ * Falls back to uncompressed data if compression is not available.
+ */
+async function compressIfNeeded(data: string): Promise<{ data: BodyInit; compressed: boolean }> {
+  const bytes = new TextEncoder().encode(data);
+
+  // Only compress if payload exceeds threshold
+  if (bytes.length < Constraints.COMPRESSION_THRESHOLD_BYTES) {
+    return { data, compressed: false };
+  }
+
+  // Check if CompressionStream is available (modern browsers)
+  if (typeof CompressionStream === 'undefined') {
+    logger.debug('CompressionStream not available, sending uncompressed');
+    return { data, compressed: false };
+  }
+
+  try {
+    const stream = new Blob([bytes]).stream();
+    const compressedStream = stream.pipeThrough(new CompressionStream('gzip'));
+    const compressedBlob = await new Response(compressedStream).blob();
+
+    logger.debug(`Compressed payload from ${bytes.length} to ${compressedBlob.size} bytes`);
+
+    return { data: compressedBlob, compressed: true };
+  } catch (e) {
+    logger.warn('Failed to compress payload, sending uncompressed', e);
+    return { data, compressed: false };
+  }
+}
+
+/**
+ * Default network client using the Fetch API.
+ */
+export class FetchNetworkClient implements INetworkClient {
+  private retryAfterTime: Date | null = null;
+
+  /**
+   * Send events to the MostlyGoodMetrics API.
+   */
+  async sendEvents(payload: MGMEventsPayload, config: ResolvedConfiguration): Promise<SendResult> {
+    // Check rate limiting
+    if (this.isRateLimited()) {
+      const retryAfter = this.getRetryAfterTime();
+      const waitMs = retryAfter ? retryAfter.getTime() - Date.now() : 0;
+      logger.debug(`Rate limited, retry after ${Math.ceil(waitMs / 1000)}s`);
+
+      return {
+        success: false,
+        error: new MGMError('RATE_LIMITED', 'Rate limited, please retry later', {
+          retryAfter: Math.ceil(waitMs / 1000),
+        }),
+        shouldRetry: true,
+      };
+    }
+
+    const url = `${config.baseURL}${EVENTS_ENDPOINT}`;
+    const jsonBody = JSON.stringify(payload);
+    const { data, compressed } = await compressIfNeeded(jsonBody);
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-MGM-Key': config.apiKey,
+    };
+
+    if (config.bundleId) {
+      headers['X-MGM-Bundle-Id'] = config.bundleId;
+    }
+
+    if (compressed) {
+      headers['Content-Encoding'] = 'gzip';
+    }
+
+    logger.debug(`Sending ${payload.events.length} events to ${url}`);
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: data,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      return this.handleResponse(response);
+    } catch (e) {
+      if (e instanceof Error && e.name === 'AbortError') {
+        logger.warn('Request timed out');
+        return {
+          success: false,
+          error: new MGMError('NETWORK_ERROR', 'Request timed out'),
+          shouldRetry: true,
+        };
+      }
+
+      logger.error('Network error', e);
+      return {
+        success: false,
+        error: new MGMError(
+          'NETWORK_ERROR',
+          e instanceof Error ? e.message : 'Unknown network error'
+        ),
+        shouldRetry: true,
+      };
+    }
+  }
+
+  /**
+   * Handle the API response and return appropriate result.
+   */
+  private handleResponse(response: Response): SendResult {
+    const statusCode = response.status;
+
+    // Success
+    if (statusCode === 204 || statusCode === 200) {
+      logger.debug('Events sent successfully');
+      return { success: true };
+    }
+
+    // Rate limited
+    if (statusCode === 429) {
+      const retryAfterHeader = response.headers.get('Retry-After');
+      const retryAfterSeconds = retryAfterHeader ? parseInt(retryAfterHeader, 10) : 60;
+
+      this.retryAfterTime = new Date(Date.now() + retryAfterSeconds * 1000);
+
+      logger.warn(`Rate limited, retry after ${retryAfterSeconds}s`);
+
+      return {
+        success: false,
+        error: new MGMError('RATE_LIMITED', 'Rate limited by server', {
+          retryAfter: retryAfterSeconds,
+          statusCode,
+        }),
+        shouldRetry: true,
+      };
+    }
+
+    // Client errors (4xx) - don't retry, drop events
+    if (statusCode >= 400 && statusCode < 500) {
+      const errorType =
+        statusCode === 400
+          ? 'BAD_REQUEST'
+          : statusCode === 401
+            ? 'UNAUTHORIZED'
+            : statusCode === 403
+              ? 'FORBIDDEN'
+              : 'BAD_REQUEST';
+
+      const errorMessage = `Server returned ${statusCode}`;
+      logger.error(errorMessage);
+
+      return {
+        success: false,
+        error: new MGMError(errorType, errorMessage, { statusCode }),
+        shouldRetry: false, // Drop events on client errors
+      };
+    }
+
+    // Server errors (5xx) - retry later
+    if (statusCode >= 500) {
+      const errorMessage = `Server error: ${statusCode}`;
+      logger.warn(errorMessage);
+
+      return {
+        success: false,
+        error: new MGMError('SERVER_ERROR', errorMessage, { statusCode }),
+        shouldRetry: true,
+      };
+    }
+
+    // Unexpected status code
+    logger.warn(`Unexpected status code: ${statusCode}`);
+    return {
+      success: false,
+      error: new MGMError('UNKNOWN_ERROR', `Unexpected status code: ${statusCode}`, {
+        statusCode,
+      }),
+      shouldRetry: true,
+    };
+  }
+
+  /**
+   * Check if currently rate limited.
+   */
+  isRateLimited(): boolean {
+    if (!this.retryAfterTime) {
+      return false;
+    }
+
+    if (Date.now() >= this.retryAfterTime.getTime()) {
+      this.retryAfterTime = null;
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get the time when rate limiting expires.
+   */
+  getRetryAfterTime(): Date | null {
+    return this.retryAfterTime;
+  }
+}
+
+/**
+ * Create the default network client.
+ */
+export function createDefaultNetworkClient(): INetworkClient {
+  return new FetchNetworkClient();
+}

package/src/storage.test.ts

@@ -0,0 +1,175 @@
+import { InMemoryEventStorage, LocalStorageEventStorage } from './storage';
+import { MGMEvent } from './types';
+
+const createMockEvent = (name: string): MGMEvent => ({
+  name,
+  timestamp: new Date().toISOString(),
+  platform: 'web',
+  environment: 'test',
+});
+
+describe('InMemoryEventStorage', () => {
+  let storage: InMemoryEventStorage;
+
+  beforeEach(() => {
+    storage = new InMemoryEventStorage(100);
+  });
+
+  it('should store and retrieve events', async () => {
+    const event = createMockEvent('test_event');
+    await storage.store(event);
+
+    const events = await storage.fetchEvents(10);
+    expect(events).toHaveLength(1);
+    expect(events[0].name).toBe('test_event');
+  });
+
+  it('should return correct event count', async () => {
+    expect(await storage.eventCount()).toBe(0);
+
+    await storage.store(createMockEvent('event1'));
+    expect(await storage.eventCount()).toBe(1);
+
+    await storage.store(createMockEvent('event2'));
+    expect(await storage.eventCount()).toBe(2);
+  });
+
+  it('should fetch events in FIFO order', async () => {
+    await storage.store(createMockEvent('first'));
+    await storage.store(createMockEvent('second'));
+    await storage.store(createMockEvent('third'));
+
+    const events = await storage.fetchEvents(2);
+    expect(events).toHaveLength(2);
+    expect(events[0].name).toBe('first');
+    expect(events[1].name).toBe('second');
+  });
+
+  it('should remove events correctly', async () => {
+    await storage.store(createMockEvent('first'));
+    await storage.store(createMockEvent('second'));
+    await storage.store(createMockEvent('third'));
+
+    await storage.removeEvents(2);
+
+    const events = await storage.fetchEvents(10);
+    expect(events).toHaveLength(1);
+    expect(events[0].name).toBe('third');
+  });
+
+  it('should clear all events', async () => {
+    await storage.store(createMockEvent('event1'));
+    await storage.store(createMockEvent('event2'));
+
+    await storage.clear();
+
+    expect(await storage.eventCount()).toBe(0);
+  });
+
+  it('should drop oldest events when exceeding max', async () => {
+    // Note: minimum is 100, so we need to store more than 100 events
+    const storage = new InMemoryEventStorage(100);
+
+    // Store 105 events
+    for (let i = 0; i < 105; i++) {
+      await storage.store(createMockEvent(`event${i}`));
+    }
+
+    // Should have dropped to 100 (the max)
+    expect(await storage.eventCount()).toBe(100);
+
+    // First 5 events should have been dropped
+    const events = await storage.fetchEvents(3);
+    expect(events[0].name).toBe('event5');
+    expect(events[1].name).toBe('event6');
+    expect(events[2].name).toBe('event7');
+  });
+
+  it('should enforce minimum storage size', async () => {
+    // Even with 0 max, should use minimum (100)
+    const storage = new InMemoryEventStorage(0);
+
+    for (let i = 0; i < 150; i++) {
+      await storage.store(createMockEvent(`event${i}`));
+    }
+
+    // Should have dropped to 100 (minimum)
+    expect(await storage.eventCount()).toBe(100);
+  });
+});
+
+describe('LocalStorageEventStorage', () => {
+  let storage: LocalStorageEventStorage;
+
+  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,
+    });
+
+    storage = new LocalStorageEventStorage(100);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should store and retrieve events', async () => {
+    const event = createMockEvent('test_event');
+    await storage.store(event);
+
+    const events = await storage.fetchEvents(10);
+    expect(events).toHaveLength(1);
+    expect(events[0].name).toBe('test_event');
+  });
+
+  it('should persist events to localStorage', async () => {
+    const event = createMockEvent('persisted_event');
+    await storage.store(event);
+
+    expect(localStorage.setItem).toHaveBeenCalled();
+  });
+
+  it('should return correct event count', async () => {
+    expect(await storage.eventCount()).toBe(0);
+
+    await storage.store(createMockEvent('event1'));
+    expect(await storage.eventCount()).toBe(1);
+
+    await storage.store(createMockEvent('event2'));
+    expect(await storage.eventCount()).toBe(2);
+  });
+
+  it('should clear events', async () => {
+    await storage.store(createMockEvent('event1'));
+    await storage.clear();
+
+    expect(await storage.eventCount()).toBe(0);
+    expect(localStorage.removeItem).toHaveBeenCalled();
+  });
+
+  it('should handle JSON parse errors gracefully', async () => {
+    (localStorage.getItem as jest.Mock).mockReturnValueOnce('invalid json');
+
+    // Should not throw and should return empty array
+    const events = await storage.fetchEvents(10);
+    expect(events).toHaveLength(0);
+  });
+});

package/src/storage.ts

@@ -0,0 +1,249 @@
+import { logger } from './logger';
+import { Constraints, IEventStorage, MGMError, MGMEvent } from './types';
+
+const STORAGE_KEY = 'mostlygoodmetrics_events';
+const USER_ID_KEY = 'mostlygoodmetrics_user_id';
+const APP_VERSION_KEY = 'mostlygoodmetrics_app_version';
+
+/**
+ * Check if we're running in a browser environment with localStorage available.
+ */
+function isLocalStorageAvailable(): boolean {
+  try {
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+      return false;
+    }
+    const testKey = '__mgm_test__';
+    localStorage.setItem(testKey, 'test');
+    localStorage.removeItem(testKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * In-memory event storage implementation.
+ * Used as a fallback when localStorage is not available,
+ * or for testing purposes.
+ */
+export class InMemoryEventStorage implements IEventStorage {
+  private events: MGMEvent[] = [];
+  private maxEvents: number;
+
+  constructor(maxEvents: number = Constraints.MIN_STORED_EVENTS) {
+    this.maxEvents = Math.max(maxEvents, Constraints.MIN_STORED_EVENTS);
+  }
+
+  async store(event: MGMEvent): Promise<void> {
+    this.events.push(event);
+
+    // Trim oldest events if we exceed the limit
+    if (this.events.length > this.maxEvents) {
+      const excess = this.events.length - this.maxEvents;
+      this.events.splice(0, excess);
+      logger.debug(`Dropped ${excess} oldest events due to storage limit`);
+    }
+  }
+
+  async fetchEvents(limit: number): Promise<MGMEvent[]> {
+    return this.events.slice(0, limit);
+  }
+
+  async removeEvents(count: number): Promise<void> {
+    this.events.splice(0, count);
+  }
+
+  async eventCount(): Promise<number> {
+    return this.events.length;
+  }
+
+  async clear(): Promise<void> {
+    this.events = [];
+  }
+
+  /**
+   * Update the maximum number of stored events.
+   */
+  setMaxEvents(maxEvents: number): void {
+    this.maxEvents = Math.max(maxEvents, Constraints.MIN_STORED_EVENTS);
+  }
+}
+
+/**
+ * LocalStorage-based event storage implementation.
+ * Persists events across page reloads and browser restarts.
+ */
+export class LocalStorageEventStorage implements IEventStorage {
+  private maxEvents: number;
+  private events: MGMEvent[] | null = null;
+
+  constructor(maxEvents: number = Constraints.MIN_STORED_EVENTS) {
+    this.maxEvents = Math.max(maxEvents, Constraints.MIN_STORED_EVENTS);
+  }
+
+  private loadEvents(): MGMEvent[] {
+    if (this.events !== null) {
+      return this.events;
+    }
+
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        this.events = JSON.parse(stored) as MGMEvent[];
+      } else {
+        this.events = [];
+      }
+    } catch (e) {
+      logger.warn('Failed to load events from localStorage', e);
+      this.events = [];
+    }
+
+    return this.events;
+  }
+
+  private saveEvents(): void {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(this.events ?? []));
+    } catch (e) {
+      logger.error('Failed to save events to localStorage', e);
+      throw new MGMError('STORAGE_ERROR', 'Failed to save events to localStorage');
+    }
+  }
+
+  async store(event: MGMEvent): Promise<void> {
+    const events = this.loadEvents();
+    events.push(event);
+
+    // Trim oldest events if we exceed the limit
+    if (events.length > this.maxEvents) {
+      const excess = events.length - this.maxEvents;
+      events.splice(0, excess);
+      logger.debug(`Dropped ${excess} oldest events due to storage limit`);
+    }
+
+    this.saveEvents();
+  }
+
+  async fetchEvents(limit: number): Promise<MGMEvent[]> {
+    const events = this.loadEvents();
+    return events.slice(0, limit);
+  }
+
+  async removeEvents(count: number): Promise<void> {
+    const events = this.loadEvents();
+    events.splice(0, count);
+    this.saveEvents();
+  }
+
+  async eventCount(): Promise<number> {
+    return this.loadEvents().length;
+  }
+
+  async clear(): Promise<void> {
+    this.events = [];
+    try {
+      localStorage.removeItem(STORAGE_KEY);
+    } catch (e) {
+      logger.warn('Failed to clear events from localStorage', e);
+    }
+  }
+
+  /**
+   * Update the maximum number of stored events.
+   */
+  setMaxEvents(maxEvents: number): void {
+    this.maxEvents = Math.max(maxEvents, Constraints.MIN_STORED_EVENTS);
+  }
+}
+
+/**
+ * Create the appropriate storage implementation based on the environment.
+ */
+export function createDefaultStorage(maxEvents: number): IEventStorage {
+  if (isLocalStorageAvailable()) {
+    logger.debug('Using LocalStorage for event persistence');
+    return new LocalStorageEventStorage(maxEvents);
+  }
+
+  logger.debug('LocalStorage not available, using in-memory storage');
+  return new InMemoryEventStorage(maxEvents);
+}
+
+/**
+ * Persistence helpers for user ID and app version.
+ * These use localStorage when available, otherwise fall back to in-memory.
+ */
+class PersistenceManager {
+  private inMemoryUserId: string | null = null;
+  private inMemoryAppVersion: string | null = null;
+
+  /**
+   * Get the persisted user ID.
+   */
+  getUserId(): string | null {
+    if (isLocalStorageAvailable()) {
+      return localStorage.getItem(USER_ID_KEY);
+    }
+    return this.inMemoryUserId;
+  }
+
+  /**
+   * Set the user ID (persists across sessions).
+   */
+  setUserId(userId: string | null): void {
+    if (isLocalStorageAvailable()) {
+      if (userId) {
+        localStorage.setItem(USER_ID_KEY, userId);
+      } else {
+        localStorage.removeItem(USER_ID_KEY);
+      }
+    }
+    this.inMemoryUserId = userId;
+  }
+
+  /**
+   * Get the persisted app version (for detecting updates).
+   */
+  getAppVersion(): string | null {
+    if (isLocalStorageAvailable()) {
+      return localStorage.getItem(APP_VERSION_KEY);
+    }
+    return this.inMemoryAppVersion;
+  }
+
+  /**
+   * Set the app version.
+   */
+  setAppVersion(version: string | null): void {
+    if (isLocalStorageAvailable()) {
+      if (version) {
+        localStorage.setItem(APP_VERSION_KEY, version);
+      } else {
+        localStorage.removeItem(APP_VERSION_KEY);
+      }
+    }
+    this.inMemoryAppVersion = version;
+  }
+
+  /**
+   * Check if this is the first time the app has been opened.
+   * Uses localStorage to detect first-ever installation.
+   */
+  isFirstLaunch(): boolean {
+    const FIRST_LAUNCH_KEY = 'mostlygoodmetrics_installed';
+
+    if (!isLocalStorageAvailable()) {
+      return false; // Can't reliably detect without persistence
+    }
+
+    const hasLaunched = localStorage.getItem(FIRST_LAUNCH_KEY);
+    if (!hasLaunched) {
+      localStorage.setItem(FIRST_LAUNCH_KEY, 'true');
+      return true;
+    }
+    return false;
+  }
+}
+
+export const persistence = new PersistenceManager();