@mostly-good-metrics/javascript 0.4.3 → 0.5.0

package/dist/types/index.d.ts

@@ -29,6 +29,6 @@ export { MGMError } from './types';
 export { SystemEvents, SystemProperties, DefaultConfiguration, Constraints, EVENT_NAME_REGEX, } from './types';
 export { InMemoryEventStorage, LocalStorageEventStorage, createDefaultStorage } from './storage';
 export { FetchNetworkClient, createDefaultNetworkClient } from './network';
-export { generateUUID, getISOTimestamp, isValidEventName, validateEventName, sanitizeProperties, detectPlatform, detectDeviceType, getOSVersion, getDeviceModel, } from './utils';
+export { generateAnonymousId, generateUUID, getISOTimestamp, isValidEventName, validateEventName, sanitizeProperties, detectPlatform, detectDeviceType, getOSVersion, getDeviceModel, } from './utils';
 export { logger } from './logger';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,GAAG,EACH,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGjG,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAG3E,OAAO,EACL,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,GAAG,EACH,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGjG,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAG3E,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/storage.d.ts

@@ -44,12 +44,25 @@ export declare class LocalStorageEventStorage implements IEventStorage {
 export declare function createDefaultStorage(maxEvents: number): IEventStorage;
 /**
  * Persistence helpers for user ID and app version.
- * These use localStorage when available, otherwise fall back to in-memory.
+ * Uses cookies first (for cross-subdomain support), then localStorage as fallback.
  */
 declare class PersistenceManager {
     private inMemoryUserId;
+    private inMemoryAnonymousId;
     private inMemoryAppVersion;
     private inMemorySuperProperties;
+    private cookieDomain;
+    private disableCookies;
+    /**
+     * Configure cookie settings.
+     * @param cookieDomain Domain for cross-subdomain cookies (e.g., '.example.com')
+     * @param disableCookies If true, only use localStorage (no cookies)
+     */
+    configureCookies(cookieDomain?: string, disableCookies?: boolean): void;
+    /**
+     * Check if cookies should be used.
+     */
+    private shouldUseCookies;
     /**
      * Get the persisted user ID.
      */
@@ -58,6 +71,28 @@ declare class PersistenceManager {
      * Set the user ID (persists across sessions).
      */
     setUserId(userId: string | null): void;
+    /**
+     * Get the anonymous ID (auto-generated UUID).
+     * Checks cookies first, then localStorage, then in-memory.
+     */
+    getAnonymousId(): string | null;
+    /**
+     * Set the anonymous ID (persists across sessions).
+     * Saves to both cookies and localStorage for redundancy.
+     */
+    setAnonymousId(anonymousId: string): void;
+    /**
+     * Initialize the anonymous ID. If an override is provided, use it.
+     * Otherwise, use existing persisted ID or generate a new UUID.
+     * @param overrideId Optional ID from wrapper SDK (e.g., React Native device ID)
+     * @param generateUUID Function to generate a UUID
+     */
+    initializeAnonymousId(overrideId: string | undefined, generateUUID: () => string): string;
+    /**
+     * Reset the anonymous ID to a new UUID.
+     * @param generateUUID Function to generate a UUID
+     */
+    resetAnonymousId(generateUUID: () => string): string;
     /**
      * Get the persisted app version (for detecting updates).
      */

package/dist/types/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,eAAe,EAAE,aAAa,EAAY,QAAQ,EAAE,MAAM,SAAS,CAAC;AAwB1F;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,GAAE,MAAsC;IAIvD,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI/C,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAGtC;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,aAAa;IAC5D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAA2B;gBAE7B,SAAS,GAAE,MAAsC;IAI7D,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,UAAU;IASZ,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK/C,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAGtC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAQrE;AAED;;;GAGG;AACH,cAAM,kBAAkB;IACtB,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,uBAAuB,CAAuB;IAEtD;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAO1B;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAWtC;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAO9B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAW3C;;;OAGG;IACH,aAAa,IAAI,OAAO;IAexB;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAerC;;OAEG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,IAAI;IAMnE;;OAEG;IACH,kBAAkB,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAMrD;;OAEG;IACH,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMtC;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAI5B,OAAO,CAAC,mBAAmB;CAU5B;AAED,eAAO,MAAM,WAAW,oBAA2B,CAAC"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/types/types.d.ts

@@ -43,7 +43,7 @@ export interface MGMConfiguration {
     /**
      * Whether to automatically track app lifecycle events
      * ($app_opened, $app_backgrounded, $app_installed, $app_updated).
-     * @default true
+     * @default false
      */
     trackAppLifecycleEvents?: boolean;
     /**
@@ -77,6 +77,25 @@ export interface MGMConfiguration {
      * If not provided, uses the JS SDK's version.
      */
     sdkVersion?: string;
+    /**
+     * Override the auto-generated anonymous user ID.
+     * Wrapper SDKs (e.g., React Native) can pass a device-specific ID here.
+     * If not provided, a UUID will be auto-generated and persisted.
+     */
+    anonymousId?: string;
+    /**
+     * Cookie domain for cross-subdomain tracking.
+     * Set to '.yourdomain.com' to share anonymous ID across subdomains.
+     * Example: '.example.com' allows sharing between app.example.com and www.example.com
+     */
+    cookieDomain?: string;
+    /**
+     * Disable cookie storage entirely.
+     * When true, only localStorage will be used (no cross-subdomain tracking).
+     * Useful for GDPR compliance or privacy-focused applications.
+     * @default false
+     */
+    disableCookies?: boolean;
     /**
      * Custom storage adapter. If not provided, uses localStorage in browsers
      * or in-memory storage in non-browser environments.
@@ -86,13 +105,20 @@ export interface MGMConfiguration {
      * Custom network client. If not provided, uses fetch-based client.
      */
     networkClient?: INetworkClient;
+    /**
+     * Callback invoked when a network error occurs.
+     * Useful for reporting errors to external services like Sentry.
+     * @param error The error that occurred
+     */
+    onError?: (error: MGMError) => void;
 }
 /**
  * Internal resolved configuration with all defaults applied.
  */
-export interface ResolvedConfiguration extends Required<Omit<MGMConfiguration, 'storage' | 'networkClient'>> {
+export interface ResolvedConfiguration extends Required<Omit<MGMConfiguration, 'storage' | 'networkClient' | 'onError' | 'anonymousId' | 'cookieDomain' | 'disableCookies'>> {
     storage?: IEventStorage;
     networkClient?: INetworkClient;
+    onError?: (error: MGMError) => void;
 }
 /**
  * Properties that can be attached to an event.
@@ -124,12 +150,13 @@ export interface MGMEvent {
     timestamp: string;
     /**
      * The user ID associated with this event.
+     * Uses identified user if set, otherwise falls back to anonymous UUID.
      */
-    userId?: string;
+    user_id: string;
     /**
      * The session ID associated with this event.
      */
-    sessionId?: string;
+    session_id?: string;
     /**
      * The platform this event was generated from.
      */
@@ -137,15 +164,15 @@ export interface MGMEvent {
     /**
      * The app version string.
      */
-    appVersion?: string;
+    app_version?: string;
     /**
      * The app build number (separate from version).
      */
-    appBuildNumber?: string;
+    app_build_number?: string;
     /**
      * The OS version string.
      */
-    osVersion?: string;
+    os_version?: string;
     /**
      * The environment name.
      */
@@ -153,7 +180,7 @@ export interface MGMEvent {
     /**
      * The device manufacturer (e.g., "Apple", "Samsung").
      */
-    deviceManufacturer?: string;
+    device_manufacturer?: string;
     /**
      * The user's locale (e.g., "en-US").
      */
@@ -173,13 +200,13 @@ export interface MGMEvent {
  */
 export interface MGMEventContext {
     platform: Platform;
-    appVersion?: string;
-    appBuildNumber?: string;
-    osVersion?: string;
-    userId?: string;
-    sessionId?: string;
+    app_version?: string;
+    app_build_number?: string;
+    os_version?: string;
+    user_id: string;
+    session_id?: string;
     environment: string;
-    deviceManufacturer?: string;
+    device_manufacturer?: string;
     locale?: string;
     timezone?: string;
 }
@@ -299,7 +326,7 @@ export declare const DefaultConfiguration: {
     readonly flushInterval: 30;
     readonly maxStoredEvents: 10000;
     readonly enableDebugLogging: false;
-    readonly trackAppLifecycleEvents: true;
+    readonly trackAppLifecycleEvents: false;
 };
 /**
  * Validation constraints.

package/dist/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types/utils.d.ts

@@ -3,6 +3,11 @@ import { DeviceType, EventProperties, MGMConfiguration, Platform, ResolvedConfig
  * Generate a UUID v4 string.
  */
 export declare function generateUUID(): string;
+/**
+ * Generate an anonymous user ID with $anon_ prefix.
+ * Format: $anon_xxxxxxxxxxxx (12 random chars)
+ */
+export declare function generateAnonymousId(): string;
 /**
  * Get the current timestamp in ISO8601 format.
  */

package/dist/types/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,UAAU,EAEV,eAAe,EAEf,gBAAgB,EAEhB,QAAQ,EACR,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,QAAQ,GAAE,MAAuC,GAChD,eAAe,GAAG,SAAS,CAW7B;AA0DD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,qBAAqB,CAmCpF;AAeD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAQzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA0B7C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA0BrC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAyBvC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,UAAU,EAEV,eAAe,EAEf,gBAAgB,EAEhB,QAAQ,EACR,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAuBD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,QAAQ,GAAE,MAAuC,GAChD,eAAe,GAAG,SAAS,CAW7B;AA0DD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,qBAAqB,CAoCpF;AAeD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAQzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA0B7C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA0BrC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAyBvC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostly-good-metrics/javascript",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "JavaScript/TypeScript SDK for MostlyGoodMetrics - a lightweight analytics library for web applications",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/client.test.ts

@@ -258,7 +258,7 @@ describe('MostlyGoodMetrics', () => {
       await new Promise((resolve) => setTimeout(resolve, 10));
 
       const events = await storage.fetchEvents(1);
-      expect(events[0].userId).toBe('user_456');
+      expect(events[0].user_id).toBe('user_456');
     });
 
     it('should not set empty userId', () => {
@@ -283,6 +283,86 @@ describe('MostlyGoodMetrics', () => {
       MostlyGoodMetrics.resetIdentity();
       expect(MostlyGoodMetrics.shared?.userId).toBeNull();
     });
+
+    it('should keep anonymousId unchanged', () => {
+      const originalAnonymousId = MostlyGoodMetrics.shared?.anonymousId;
+      MostlyGoodMetrics.resetIdentity();
+      const newAnonymousId = MostlyGoodMetrics.shared?.anonymousId;
+      expect(newAnonymousId).toBe(originalAnonymousId);
+    });
+  });
+
+  describe('anonymousId', () => {
+    it('should auto-generate anonymousId on init', () => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+      expect(MostlyGoodMetrics.shared?.anonymousId).toBeDefined();
+      expect(MostlyGoodMetrics.shared?.anonymousId.length).toBeGreaterThan(0);
+    });
+
+    it('should include anonymousId as user_id in events when not identified', async () => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].user_id).toBe(MostlyGoodMetrics.shared?.anonymousId);
+    });
+
+    it('should allow wrapper SDK to override anonymousId', () => {
+      const customAnonymousId = 'react-native-device-id-12345';
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        anonymousId: customAnonymousId,
+      });
+      expect(MostlyGoodMetrics.shared?.anonymousId).toBe(customAnonymousId);
+    });
+
+    it('should include custom anonymousId as user_id in events', async () => {
+      const customAnonymousId = 'react-native-device-id-12345';
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        anonymousId: customAnonymousId,
+      });
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].user_id).toBe(customAnonymousId);
+    });
+
+    it('should use identified userId over anonymousId', async () => {
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+      });
+      MostlyGoodMetrics.identify('identified_user_123');
+      MostlyGoodMetrics.track('test_event');
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const events = await storage.fetchEvents(1);
+      expect(events[0].user_id).toBe('identified_user_123');
+    });
   });
 
   describe('flush', () => {
@@ -355,6 +435,78 @@ describe('MostlyGoodMetrics', () => {
       const count = await storage.eventCount();
       expect(count).toBe(0);
     });
+
+    it('should call onError callback when network error occurs', async () => {
+      const onError = jest.fn();
+      MostlyGoodMetrics.reset();
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        onError,
+      });
+
+      networkClient.sendResult = {
+        success: false,
+        error: { name: 'MGMError', message: 'Server error', type: 'SERVER_ERROR' } as never,
+        shouldRetry: true,
+      };
+
+      MostlyGoodMetrics.track('test_event');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      await MostlyGoodMetrics.flush();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(onError).toHaveBeenCalledWith(expect.objectContaining({ type: 'SERVER_ERROR' }));
+    });
+
+    it('should not call onError callback on success', async () => {
+      const onError = jest.fn();
+      MostlyGoodMetrics.reset();
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        onError,
+      });
+
+      networkClient.sendResult = { success: true };
+
+      MostlyGoodMetrics.track('test_event');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      await MostlyGoodMetrics.flush();
+
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it('should catch exceptions thrown by onError callback', async () => {
+      const onError = jest.fn().mockImplementation(() => {
+        throw new Error('Callback error');
+      });
+      MostlyGoodMetrics.reset();
+      MostlyGoodMetrics.configure({
+        apiKey: 'test-key',
+        storage,
+        networkClient,
+        trackAppLifecycleEvents: false,
+        onError,
+      });
+
+      networkClient.sendResult = {
+        success: false,
+        error: { name: 'MGMError', message: 'Server error', type: 'SERVER_ERROR' } as never,
+        shouldRetry: true,
+      };
+
+      MostlyGoodMetrics.track('test_event');
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Should not throw
+      await expect(MostlyGoodMetrics.flush()).resolves.not.toThrow();
+      expect(onError).toHaveBeenCalled();
+    });
   });
 
   describe('startNewSession', () => {

package/src/client.ts

@@ -16,6 +16,7 @@ import {
 import {
   delay,
   detectDeviceType,
+  generateAnonymousId,
   generateUUID,
   getDeviceModel,
   getISOTimestamp,
@@ -42,6 +43,7 @@ export class MostlyGoodMetrics {
   private flushTimer: ReturnType<typeof setInterval> | null = null;
   private isFlushingInternal = false;
   private sessionIdValue: string;
+  private anonymousIdValue: string;
   private lifecycleSetup = false;
 
   /**
@@ -51,6 +53,13 @@ export class MostlyGoodMetrics {
     this.config = resolveConfiguration(config);
     this.sessionIdValue = generateUUID();
 
+    // Configure cookie settings before initializing anonymous ID
+    persistence.configureCookies(config.cookieDomain, config.disableCookies);
+    this.anonymousIdValue = persistence.initializeAnonymousId(
+      config.anonymousId,
+      generateAnonymousId
+    );
+
     // Set up logging
     setDebugLogging(this.config.enableDebugLogging);
 
@@ -113,9 +122,9 @@ export class MostlyGoodMetrics {
     }
   }
 
-  // ============================================================
+  // =====================================================
   // Static convenience methods (delegate to shared instance)
-  // ============================================================
+  // =====================================================
 
   /**
    * Track an event with the given name and optional properties.
@@ -201,9 +210,9 @@ export class MostlyGoodMetrics {
     return MostlyGoodMetrics.instance?.getSuperProperties() ?? {};
   }
 
-  // ============================================================
+  // =====================================================
   // Instance properties
-  // ============================================================
+  // =====================================================
 
   /**
    * Get the current user ID.
@@ -219,6 +228,13 @@ export class MostlyGoodMetrics {
     return this.sessionIdValue;
   }
 
+  /**
+   * Get the anonymous ID (auto-generated UUID, persisted across sessions).
+   */
+  get anonymousId(): string {
+    return this.anonymousIdValue;
+  }
+
   /**
    * Check if a flush operation is in progress.
    */
@@ -233,9 +249,9 @@ export class MostlyGoodMetrics {
     return { ...this.config };
   }
 
-  // ============================================================
+  // =====================================================
   // Instance methods
-  // ============================================================
+  // =====================================================
 
   /**
    * Track an event with the given name and optional properties.
@@ -265,11 +281,13 @@ export class MostlyGoodMetrics {
       name,
       client_event_id: generateUUID(),
       timestamp: getISOTimestamp(),
-      userId: this.userId ?? undefined,
-      sessionId: this.sessionIdValue,
+
+      user_id: this.userId ?? this.anonymousIdValue,
+
+      session_id: this.sessionIdValue,
       platform: this.config.platform,
-      appVersion: this.config.appVersion || undefined,
-      osVersion: this.config.osVersion || getOSVersion() || undefined,
+      app_version: this.config.appVersion || undefined,
+      os_version: this.config.osVersion || getOSVersion() || undefined,
       environment: this.config.environment,
       locale: getLocale(),
       timezone: getTimezone(),
@@ -398,9 +416,9 @@ export class MostlyGoodMetrics {
     logger.debug('MostlyGoodMetrics instance destroyed');
   }
 
-  // ============================================================
+  // =====================================================
   // Private methods
-  // ============================================================
+  // =====================================================
 
   private async checkBatchSize(): Promise<void> {
     const count = await this.storage.eventCount();
@@ -439,6 +457,15 @@ export class MostlyGoodMetrics {
       } else {
         logger.warn(`Failed to send events: ${result.error.message}`);
 
+        // Call onError callback if configured
+        if (this.config.onError) {
+          try {
+            this.config.onError(result.error);
+          } catch (e) {
+            logger.error('Error in onError callback', e);
+          }
+        }
+
         if (!result.shouldRetry) {
           // Drop events on non-retryable errors (4xx)
           logger.warn('Dropping events due to non-retryable error');
@@ -457,10 +484,12 @@ export class MostlyGoodMetrics {
   private buildPayload(events: MGMEvent[]): MGMEventsPayload {
     const context: MGMEventContext = {
       platform: this.config.platform,
-      appVersion: this.config.appVersion || undefined,
-      osVersion: this.config.osVersion || getOSVersion() || undefined,
-      userId: this.userId ?? undefined,
-      sessionId: this.sessionIdValue,
+      app_version: this.config.appVersion || undefined,
+      os_version: this.config.osVersion || getOSVersion() || undefined,
+
+      user_id: this.userId ?? this.anonymousIdValue,
+
+      session_id: this.sessionIdValue,
       environment: this.config.environment,
       locale: getLocale(),
       timezone: getTimezone(),

package/src/index.ts

@@ -65,6 +65,7 @@ export { FetchNetworkClient, createDefaultNetworkClient } from './network';
 
 // Utilities (for advanced usage)
 export {
+  generateAnonymousId,
   generateUUID,
   getISOTimestamp,
   isValidEventName,

package/src/network.test.ts

@@ -93,11 +93,11 @@ describe('FetchNetworkClient', () => {
       expect(capturedHeaders['X-MGM-Platform-Version']).toBe('17.0');
     });
 
-    it('should include X-MGM-Key header with API key', async () => {
+    it('should include Authorization Bearer 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');
+      expect(capturedHeaders['Authorization']).toBe('Bearer my-secret-key');
     });
 
     it('should include X-MGM-Bundle-Id when bundleId is configured', async () => {
@@ -124,7 +124,7 @@ describe('FetchNetworkClient', () => {
       });
       await networkClient.sendEvents(createMockPayload(), config);
 
-      expect(capturedHeaders['X-MGM-Key']).toBe('test-key');
+      expect(capturedHeaders['Authorization']).toBe('Bearer test-key');
       expect(capturedHeaders['X-MGM-SDK']).toBe('javascript');
       expect(capturedHeaders['X-MGM-SDK-Version']).toBeDefined();
       expect(capturedHeaders['X-MGM-Platform']).toBe('web');

package/src/network.ts

@@ -78,7 +78,7 @@ export class FetchNetworkClient implements INetworkClient {
     const sdkVersion = config.sdkVersion || SDK_VERSION;
     const headers: Record<string, string> = {
       'Content-Type': 'application/json',
-      'X-MGM-Key': config.apiKey,
+      Authorization: `Bearer ${config.apiKey}`,
       'X-MGM-SDK': config.sdk,
       'X-MGM-SDK-Version': sdkVersion,
       'X-MGM-Platform': config.platform,