@mostly-good-metrics/javascript 0.1.0

package/src/types.ts

@@ -0,0 +1,347 @@
+/**
+ * Configuration options for the MostlyGoodMetrics SDK.
+ */
+export interface MGMConfiguration {
+  /**
+   * The API key for authenticating with MostlyGoodMetrics.
+   * Required.
+   */
+  apiKey: string;
+
+  /**
+   * The base URL for the MostlyGoodMetrics API.
+   * @default "https://mostlygoodmetrics.com"
+   */
+  baseURL?: string;
+
+  /**
+   * The environment name (e.g., "production", "staging", "development").
+   * @default "production"
+   */
+  environment?: string;
+
+  /**
+   * Maximum number of events to send in a single batch.
+   * Must be between 1 and 1000.
+   * @default 100
+   */
+  maxBatchSize?: number;
+
+  /**
+   * Interval in seconds between automatic flush attempts.
+   * Must be at least 1 second.
+   * @default 30
+   */
+  flushInterval?: number;
+
+  /**
+   * Maximum number of events to store locally before dropping oldest events.
+   * Must be at least 100.
+   * @default 10000
+   */
+  maxStoredEvents?: number;
+
+  /**
+   * Whether to enable debug logging to the console.
+   * @default false
+   */
+  enableDebugLogging?: boolean;
+
+  /**
+   * Whether to automatically track app lifecycle events
+   * ($app_opened, $app_backgrounded, $app_installed, $app_updated).
+   * @default true
+   */
+  trackAppLifecycleEvents?: boolean;
+
+  /**
+   * Custom bundle identifier to use instead of auto-detection.
+   * Useful for multi-tenant applications.
+   */
+  bundleId?: string;
+
+  /**
+   * The app version string to include with events.
+   * If not provided, will attempt to auto-detect from the environment.
+   */
+  appVersion?: string;
+
+  /**
+   * The OS version string to include with events.
+   * If not provided, will attempt to auto-detect from the environment.
+   * For React Native, pass Platform.Version.toString().
+   */
+  osVersion?: string;
+
+  /**
+   * Custom storage adapter. If not provided, uses localStorage in browsers
+   * or in-memory storage in non-browser environments.
+   */
+  storage?: IEventStorage;
+
+  /**
+   * Custom network client. If not provided, uses fetch-based client.
+   */
+  networkClient?: INetworkClient;
+}
+
+/**
+ * Internal resolved configuration with all defaults applied.
+ */
+export interface ResolvedConfiguration extends Required<
+  Omit<MGMConfiguration, 'storage' | 'networkClient'>
+> {
+  storage?: IEventStorage;
+  networkClient?: INetworkClient;
+}
+
+/**
+ * Properties that can be attached to an event.
+ * Supports nested objects up to 3 levels deep.
+ */
+export type EventProperties = Record<string, EventPropertyValue>;
+
+/**
+ * Valid types for event property values.
+ */
+export type EventPropertyValue =
+  | null
+  | boolean
+  | number
+  | string
+  | EventPropertyValue[]
+  | { [key: string]: EventPropertyValue };
+
+/**
+ * An analytics event to be tracked.
+ */
+export interface MGMEvent {
+  /**
+   * The name of the event. Must match pattern: ^$?[a-zA-Z][a-zA-Z0-9_]*$
+   * Max 255 characters.
+   */
+  name: string;
+
+  /**
+   * ISO8601 timestamp when the event occurred.
+   */
+  timestamp: string;
+
+  /**
+   * The user ID associated with this event.
+   */
+  userId?: string;
+
+  /**
+   * The session ID associated with this event.
+   */
+  sessionId?: string;
+
+  /**
+   * The platform this event was generated from.
+   */
+  platform: Platform;
+
+  /**
+   * The app version string.
+   */
+  appVersion?: string;
+
+  /**
+   * The OS version string.
+   */
+  osVersion?: string;
+
+  /**
+   * The environment name.
+   */
+  environment: string;
+
+  /**
+   * Custom properties attached to this event.
+   */
+  properties?: EventProperties;
+}
+
+/**
+ * Context sent with each batch of events.
+ * Applied to all events in the batch server-side.
+ */
+export interface MGMEventContext {
+  platform: Platform;
+  appVersion?: string;
+  osVersion?: string;
+  userId?: string;
+  sessionId?: string;
+  environment: string;
+}
+
+/**
+ * The payload sent to the events API.
+ */
+export interface MGMEventsPayload {
+  events: MGMEvent[];
+  context: MGMEventContext;
+}
+
+/**
+ * Supported platforms.
+ */
+export type Platform = 'web' | 'ios' | 'android' | 'react-native' | 'expo' | 'node';
+
+/**
+ * Device types for automatic device detection.
+ */
+export type DeviceType = 'phone' | 'tablet' | 'desktop' | 'tv' | 'watch' | 'unknown';
+
+/**
+ * Error types that can occur in the SDK.
+ */
+export type MGMErrorType =
+  | 'NETWORK_ERROR'
+  | 'ENCODING_ERROR'
+  | 'BAD_REQUEST'
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'RATE_LIMITED'
+  | 'SERVER_ERROR'
+  | 'INVALID_EVENT_NAME'
+  | 'STORAGE_ERROR'
+  | 'UNKNOWN_ERROR';
+
+/**
+ * Result of a network send operation.
+ */
+export type SendResult =
+  | { success: true }
+  | { success: false; error: MGMError; shouldRetry: boolean };
+
+/**
+ * Interface for event storage implementations.
+ */
+export interface IEventStorage {
+  /**
+   * Store an event for later sending.
+   */
+  store(event: MGMEvent): Promise<void>;
+
+  /**
+   * Fetch up to `limit` events from storage (FIFO order).
+   */
+  fetchEvents(limit: number): Promise<MGMEvent[]>;
+
+  /**
+   * Remove events from storage after successful send.
+   */
+  removeEvents(count: number): Promise<void>;
+
+  /**
+   * Get the current count of stored events.
+   */
+  eventCount(): Promise<number>;
+
+  /**
+   * Clear all stored events.
+   */
+  clear(): Promise<void>;
+}
+
+/**
+ * Interface for network client implementations.
+ */
+export interface INetworkClient {
+  /**
+   * Send a batch of events to the server.
+   */
+  sendEvents(payload: MGMEventsPayload, config: ResolvedConfiguration): Promise<SendResult>;
+
+  /**
+   * Check if the client is currently rate-limited.
+   */
+  isRateLimited(): boolean;
+
+  /**
+   * Get the retry-after time if rate-limited, or null if not.
+   */
+  getRetryAfterTime(): Date | null;
+}
+
+/**
+ * Custom error class for SDK errors.
+ */
+export class MGMError extends Error {
+  public readonly type: MGMErrorType;
+  public readonly retryAfter?: number;
+  public readonly statusCode?: number;
+
+  constructor(
+    type: MGMErrorType,
+    message: string,
+    options?: { retryAfter?: number; statusCode?: number }
+  ) {
+    super(message);
+    this.name = 'MGMError';
+    this.type = type;
+    this.retryAfter = options?.retryAfter;
+    this.statusCode = options?.statusCode;
+
+    // Maintains proper stack trace for where error was thrown (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, MGMError);
+    }
+  }
+}
+
+/**
+ * System event names (prefixed with $).
+ */
+export const SystemEvents = {
+  APP_INSTALLED: '$app_installed',
+  APP_UPDATED: '$app_updated',
+  APP_OPENED: '$app_opened',
+  APP_BACKGROUNDED: '$app_backgrounded',
+} as const;
+
+/**
+ * System property keys (prefixed with $).
+ */
+export const SystemProperties = {
+  DEVICE_TYPE: '$device_type',
+  DEVICE_MODEL: '$device_model',
+  VERSION: '$version',
+  PREVIOUS_VERSION: '$previous_version',
+} as const;
+
+/**
+ * Default configuration values.
+ */
+export const DefaultConfiguration = {
+  baseURL: 'https://mostlygoodmetrics.com',
+  environment: 'production',
+  maxBatchSize: 100,
+  flushInterval: 30,
+  maxStoredEvents: 10000,
+  enableDebugLogging: false,
+  trackAppLifecycleEvents: true,
+} as const;
+
+/**
+ * Validation constraints.
+ */
+export const Constraints = {
+  MAX_EVENT_NAME_LENGTH: 255,
+  MAX_BATCH_SIZE: 1000,
+  MIN_BATCH_SIZE: 1,
+  MIN_FLUSH_INTERVAL: 1,
+  MIN_STORED_EVENTS: 100,
+  MAX_STRING_PROPERTY_LENGTH: 1000,
+  MAX_PROPERTY_DEPTH: 3,
+  MAX_PROPERTY_SIZE_BYTES: 10 * 1024, // 10KB
+  COMPRESSION_THRESHOLD_BYTES: 1024, // 1KB
+} as const;
+
+/**
+ * Regular expression for validating event names.
+ * Must start with a letter (or $ for system events) followed by alphanumeric and underscores.
+ */
+export const EVENT_NAME_REGEX = /^\$?[a-zA-Z][a-zA-Z0-9_]*$/;

package/src/utils.test.ts

@@ -0,0 +1,239 @@
+import {
+  generateUUID,
+  getISOTimestamp,
+  isValidEventName,
+  validateEventName,
+  sanitizeProperties,
+  resolveConfiguration,
+} from './utils';
+import { Constraints, DefaultConfiguration, MGMError } from './types';
+
+describe('generateUUID', () => {
+  it('should generate a valid UUID v4 format', () => {
+    const uuid = generateUUID();
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    expect(uuid).toMatch(uuidRegex);
+  });
+
+  it('should generate unique UUIDs', () => {
+    const uuids = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      uuids.add(generateUUID());
+    }
+    expect(uuids.size).toBe(100);
+  });
+});
+
+describe('getISOTimestamp', () => {
+  it('should return a valid ISO8601 timestamp', () => {
+    const timestamp = getISOTimestamp();
+    const parsed = new Date(timestamp);
+    expect(parsed.toISOString()).toBe(timestamp);
+  });
+
+  it('should return current time', () => {
+    const before = Date.now();
+    const timestamp = getISOTimestamp();
+    const after = Date.now();
+
+    const timestampMs = new Date(timestamp).getTime();
+    expect(timestampMs).toBeGreaterThanOrEqual(before);
+    expect(timestampMs).toBeLessThanOrEqual(after);
+  });
+});
+
+describe('isValidEventName', () => {
+  it('should accept valid event names', () => {
+    expect(isValidEventName('button_clicked')).toBe(true);
+    expect(isValidEventName('PageView')).toBe(true);
+    expect(isValidEventName('event123')).toBe(true);
+    expect(isValidEventName('a')).toBe(true);
+    expect(isValidEventName('ABC_123_xyz')).toBe(true);
+  });
+
+  it('should accept system event names (starting with $)', () => {
+    expect(isValidEventName('$app_opened')).toBe(true);
+    expect(isValidEventName('$app_installed')).toBe(true);
+    expect(isValidEventName('$custom_system_event')).toBe(true);
+  });
+
+  it('should reject invalid event names', () => {
+    expect(isValidEventName('')).toBe(false);
+    expect(isValidEventName('123_event')).toBe(false); // starts with number
+    expect(isValidEventName('_event')).toBe(false); // starts with underscore
+    expect(isValidEventName('event-name')).toBe(false); // contains hyphen
+    expect(isValidEventName('event.name')).toBe(false); // contains dot
+    expect(isValidEventName('event name')).toBe(false); // contains space
+    expect(isValidEventName('event@name')).toBe(false); // contains @
+  });
+
+  it('should reject event names exceeding max length', () => {
+    const longName = 'a'.repeat(Constraints.MAX_EVENT_NAME_LENGTH + 1);
+    expect(isValidEventName(longName)).toBe(false);
+
+    const maxLengthName = 'a'.repeat(Constraints.MAX_EVENT_NAME_LENGTH);
+    expect(isValidEventName(maxLengthName)).toBe(true);
+  });
+});
+
+describe('validateEventName', () => {
+  it('should not throw for valid event names', () => {
+    expect(() => validateEventName('valid_event')).not.toThrow();
+    expect(() => validateEventName('$system_event')).not.toThrow();
+  });
+
+  it('should throw MGMError for empty event names', () => {
+    expect(() => validateEventName('')).toThrow(MGMError);
+    try {
+      validateEventName('');
+    } catch (e) {
+      expect(e).toBeInstanceOf(MGMError);
+      expect((e as MGMError).type).toBe('INVALID_EVENT_NAME');
+    }
+  });
+
+  it('should throw MGMError for invalid event names', () => {
+    expect(() => validateEventName('123invalid')).toThrow(MGMError);
+    try {
+      validateEventName('invalid-name');
+    } catch (e) {
+      expect(e).toBeInstanceOf(MGMError);
+      expect((e as MGMError).type).toBe('INVALID_EVENT_NAME');
+    }
+  });
+});
+
+describe('sanitizeProperties', () => {
+  it('should return undefined for undefined input', () => {
+    expect(sanitizeProperties(undefined)).toBeUndefined();
+  });
+
+  it('should pass through valid properties unchanged', () => {
+    const props = {
+      string: 'value',
+      number: 42,
+      boolean: true,
+      null: null,
+    };
+    expect(sanitizeProperties(props)).toEqual(props);
+  });
+
+  it('should truncate long strings', () => {
+    const longString = 'a'.repeat(Constraints.MAX_STRING_PROPERTY_LENGTH + 100);
+    const props = { text: longString };
+
+    const sanitized = sanitizeProperties(props);
+    expect(sanitized?.text).toHaveLength(Constraints.MAX_STRING_PROPERTY_LENGTH);
+  });
+
+  it('should handle nested objects within depth limit', () => {
+    const props = {
+      level1: {
+        level2: {
+          level3: 'value',
+        },
+      },
+    };
+
+    const sanitized = sanitizeProperties(props);
+    expect(sanitized).toEqual(props);
+  });
+
+  it('should truncate objects exceeding max depth', () => {
+    const props = {
+      level1: {
+        level2: {
+          level3: {
+            level4: 'too deep',
+          },
+        },
+      },
+    };
+
+    const sanitized = sanitizeProperties(props);
+    expect(sanitized?.level1).toBeDefined();
+    expect((sanitized?.level1 as Record<string, unknown>).level2).toBeDefined();
+    expect(
+      ((sanitized?.level1 as Record<string, unknown>).level2 as Record<string, unknown>).level3
+    ).toBeNull();
+  });
+
+  it('should handle arrays', () => {
+    const props = {
+      items: ['a', 'b', 'c'],
+      numbers: [1, 2, 3],
+    };
+
+    expect(sanitizeProperties(props)).toEqual(props);
+  });
+
+  it('should handle mixed content', () => {
+    const props = {
+      user: {
+        name: 'John',
+        age: 30,
+        tags: ['premium', 'active'],
+      },
+      active: true,
+      score: null,
+    };
+
+    expect(sanitizeProperties(props)).toEqual(props);
+  });
+});
+
+describe('resolveConfiguration', () => {
+  it('should apply default values', () => {
+    const config = resolveConfiguration({ apiKey: 'test-key' });
+
+    expect(config.apiKey).toBe('test-key');
+    expect(config.baseURL).toBe(DefaultConfiguration.baseURL);
+    expect(config.environment).toBe(DefaultConfiguration.environment);
+    expect(config.maxBatchSize).toBe(DefaultConfiguration.maxBatchSize);
+    expect(config.flushInterval).toBe(DefaultConfiguration.flushInterval);
+    expect(config.maxStoredEvents).toBe(DefaultConfiguration.maxStoredEvents);
+    expect(config.enableDebugLogging).toBe(DefaultConfiguration.enableDebugLogging);
+    expect(config.trackAppLifecycleEvents).toBe(DefaultConfiguration.trackAppLifecycleEvents);
+  });
+
+  it('should use provided values', () => {
+    const config = resolveConfiguration({
+      apiKey: 'test-key',
+      baseURL: 'https://custom.api.com',
+      environment: 'staging',
+      maxBatchSize: 50,
+      flushInterval: 60,
+      maxStoredEvents: 5000,
+      enableDebugLogging: true,
+      trackAppLifecycleEvents: false,
+    });
+
+    expect(config.baseURL).toBe('https://custom.api.com');
+    expect(config.environment).toBe('staging');
+    expect(config.maxBatchSize).toBe(50);
+    expect(config.flushInterval).toBe(60);
+    expect(config.maxStoredEvents).toBe(5000);
+    expect(config.enableDebugLogging).toBe(true);
+    expect(config.trackAppLifecycleEvents).toBe(false);
+  });
+
+  it('should enforce maxBatchSize constraints', () => {
+    // Too high
+    let config = resolveConfiguration({ apiKey: 'test', maxBatchSize: 2000 });
+    expect(config.maxBatchSize).toBe(Constraints.MAX_BATCH_SIZE);
+
+    // Too low
+    config = resolveConfiguration({ apiKey: 'test', maxBatchSize: 0 });
+    expect(config.maxBatchSize).toBe(Constraints.MIN_BATCH_SIZE);
+  });
+
+  it('should enforce flushInterval minimum', () => {
+    const config = resolveConfiguration({ apiKey: 'test', flushInterval: 0 });
+    expect(config.flushInterval).toBe(Constraints.MIN_FLUSH_INTERVAL);
+  });
+
+  it('should enforce maxStoredEvents minimum', () => {
+    const config = resolveConfiguration({ apiKey: 'test', maxStoredEvents: 10 });
+    expect(config.maxStoredEvents).toBe(Constraints.MIN_STORED_EVENTS);
+  });
+});