@mostly-good-metrics/javascript 0.1.0

package/dist/cjs/network.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchNetworkClient = void 0;
+exports.createDefaultNetworkClient = createDefaultNetworkClient;
+const logger_1 = require("./logger");
+const types_1 = require("./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) {
+    const bytes = new TextEncoder().encode(data);
+    // Only compress if payload exceeds threshold
+    if (bytes.length < types_1.Constraints.COMPRESSION_THRESHOLD_BYTES) {
+        return { data, compressed: false };
+    }
+    // Check if CompressionStream is available (modern browsers)
+    if (typeof CompressionStream === 'undefined') {
+        logger_1.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_1.logger.debug(`Compressed payload from ${bytes.length} to ${compressedBlob.size} bytes`);
+        return { data: compressedBlob, compressed: true };
+    }
+    catch (e) {
+        logger_1.logger.warn('Failed to compress payload, sending uncompressed', e);
+        return { data, compressed: false };
+    }
+}
+/**
+ * Default network client using the Fetch API.
+ */
+class FetchNetworkClient {
+    constructor() {
+        this.retryAfterTime = null;
+    }
+    /**
+     * Send events to the MostlyGoodMetrics API.
+     */
+    async sendEvents(payload, config) {
+        // Check rate limiting
+        if (this.isRateLimited()) {
+            const retryAfter = this.getRetryAfterTime();
+            const waitMs = retryAfter ? retryAfter.getTime() - Date.now() : 0;
+            logger_1.logger.debug(`Rate limited, retry after ${Math.ceil(waitMs / 1000)}s`);
+            return {
+                success: false,
+                error: new types_1.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 = {
+            '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_1.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_1.logger.warn('Request timed out');
+                return {
+                    success: false,
+                    error: new types_1.MGMError('NETWORK_ERROR', 'Request timed out'),
+                    shouldRetry: true,
+                };
+            }
+            logger_1.logger.error('Network error', e);
+            return {
+                success: false,
+                error: new types_1.MGMError('NETWORK_ERROR', e instanceof Error ? e.message : 'Unknown network error'),
+                shouldRetry: true,
+            };
+        }
+    }
+    /**
+     * Handle the API response and return appropriate result.
+     */
+    handleResponse(response) {
+        const statusCode = response.status;
+        // Success
+        if (statusCode === 204 || statusCode === 200) {
+            logger_1.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_1.logger.warn(`Rate limited, retry after ${retryAfterSeconds}s`);
+            return {
+                success: false,
+                error: new types_1.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_1.logger.error(errorMessage);
+            return {
+                success: false,
+                error: new types_1.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_1.logger.warn(errorMessage);
+            return {
+                success: false,
+                error: new types_1.MGMError('SERVER_ERROR', errorMessage, { statusCode }),
+                shouldRetry: true,
+            };
+        }
+        // Unexpected status code
+        logger_1.logger.warn(`Unexpected status code: ${statusCode}`);
+        return {
+            success: false,
+            error: new types_1.MGMError('UNKNOWN_ERROR', `Unexpected status code: ${statusCode}`, {
+                statusCode,
+            }),
+            shouldRetry: true,
+        };
+    }
+    /**
+     * Check if currently rate limited.
+     */
+    isRateLimited() {
+        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() {
+        return this.retryAfterTime;
+    }
+}
+exports.FetchNetworkClient = FetchNetworkClient;
+/**
+ * Create the default network client.
+ */
+function createDefaultNetworkClient() {
+    return new FetchNetworkClient();
+}
+//# sourceMappingURL=network.js.map

package/dist/cjs/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/network.ts"],"names":[],"mappings":";;;AAmOA,gEAEC;AArOD,qCAAkC;AAClC,mCAOiB;AAEjB,MAAM,eAAe,GAAG,YAAY,CAAC;AACrC,MAAM,kBAAkB,GAAG,KAAK,CAAC,CAAC,aAAa;AAE/C;;;GAGG;AACH,KAAK,UAAU,gBAAgB,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7C,6CAA6C;IAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,mBAAW,CAAC,2BAA2B,EAAE,CAAC;QAC3D,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,4DAA4D;IAC5D,IAAI,OAAO,iBAAiB,KAAK,WAAW,EAAE,CAAC;QAC7C,eAAM,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1C,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3E,MAAM,cAAc,GAAG,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC;QAEnE,eAAM,CAAC,KAAK,CAAC,2BAA2B,KAAK,CAAC,MAAM,OAAO,cAAc,CAAC,IAAI,QAAQ,CAAC,CAAC;QAExF,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,eAAM,CAAC,IAAI,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAa,kBAAkB;IAA/B;QACU,mBAAc,GAAgB,IAAI,CAAC;IA6K7C,CAAC;IA3KC;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,OAAyB,EAAE,MAA6B;QACvE,sBAAsB;QACtB,IAAI,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAClE,eAAM,CAAC,KAAK,CAAC,6BAA6B,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YAEvE,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,IAAI,gBAAQ,CAAC,cAAc,EAAE,kCAAkC,EAAE;oBACtE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;iBACrC,CAAC;gBACF,WAAW,EAAE,IAAI;aAClB,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,eAAe,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAE9D,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,WAAW,EAAE,MAAM,CAAC,MAAM;SAC3B,CAAC;QAEF,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,OAAO,CAAC,iBAAiB,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC;QAC/C,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,kBAAkB,CAAC,GAAG,MAAM,CAAC;QACvC,CAAC;QAED,eAAM,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC,CAAC;QAElE,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,kBAAkB,CAAC,CAAC;YAE3E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAChC,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI;gBACV,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAClD,eAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;gBACjC,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,IAAI,gBAAQ,CAAC,eAAe,EAAE,mBAAmB,CAAC;oBACzD,WAAW,EAAE,IAAI;iBAClB,CAAC;YACJ,CAAC;YAED,eAAM,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;YACjC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,IAAI,gBAAQ,CACjB,eAAe,EACf,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CACzD;gBACD,WAAW,EAAE,IAAI;aAClB,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,QAAkB;QACvC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;QAEnC,UAAU;QACV,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YAC7C,eAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;YACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,eAAe;QACf,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC7D,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAEjF,IAAI,CAAC,cAAc,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,iBAAiB,GAAG,IAAI,CAAC,CAAC;YAEtE,eAAM,CAAC,IAAI,CAAC,6BAA6B,iBAAiB,GAAG,CAAC,CAAC;YAE/D,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,IAAI,gBAAQ,CAAC,cAAc,EAAE,wBAAwB,EAAE;oBAC5D,UAAU,EAAE,iBAAiB;oBAC7B,UAAU;iBACX,CAAC;gBACF,WAAW,EAAE,IAAI;aAClB,CAAC;QACJ,CAAC;QAED,iDAAiD;QACjD,IAAI,UAAU,IAAI,GAAG,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;YAC1C,MAAM,SAAS,GACb,UAAU,KAAK,GAAG;gBAChB,CAAC,CAAC,aAAa;gBACf,CAAC,CAAC,UAAU,KAAK,GAAG;oBAClB,CAAC,CAAC,cAAc;oBAChB,CAAC,CAAC,UAAU,KAAK,GAAG;wBAClB,CAAC,CAAC,WAAW;wBACb,CAAC,CAAC,aAAa,CAAC;YAExB,MAAM,YAAY,GAAG,mBAAmB,UAAU,EAAE,CAAC;YACrD,eAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAE3B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,IAAI,gBAAQ,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,CAAC;gBAC5D,WAAW,EAAE,KAAK,EAAE,+BAA+B;aACpD,CAAC;QACJ,CAAC;QAED,oCAAoC;QACpC,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;YACtB,MAAM,YAAY,GAAG,iBAAiB,UAAU,EAAE,CAAC;YACnD,eAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAE1B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,IAAI,gBAAQ,CAAC,cAAc,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,CAAC;gBACjE,WAAW,EAAE,IAAI;aAClB,CAAC;QACJ,CAAC;QAED,yBAAyB;QACzB,eAAM,CAAC,IAAI,CAAC,2BAA2B,UAAU,EAAE,CAAC,CAAC;QACrD,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,IAAI,gBAAQ,CAAC,eAAe,EAAE,2BAA2B,UAAU,EAAE,EAAE;gBAC5E,UAAU;aACX,CAAC;YACF,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,aAAa;QACX,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;CACF;AA9KD,gDA8KC;AAED;;GAEG;AACH,SAAgB,0BAA0B;IACxC,OAAO,IAAI,kBAAkB,EAAE,CAAC;AAClC,CAAC"}

package/dist/cjs/storage.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistence = exports.LocalStorageEventStorage = exports.InMemoryEventStorage = void 0;
+exports.createDefaultStorage = createDefaultStorage;
+const logger_1 = require("./logger");
+const types_1 = require("./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() {
+    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.
+ */
+class InMemoryEventStorage {
+    constructor(maxEvents = types_1.Constraints.MIN_STORED_EVENTS) {
+        this.events = [];
+        this.maxEvents = Math.max(maxEvents, types_1.Constraints.MIN_STORED_EVENTS);
+    }
+    async store(event) {
+        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_1.logger.debug(`Dropped ${excess} oldest events due to storage limit`);
+        }
+    }
+    async fetchEvents(limit) {
+        return this.events.slice(0, limit);
+    }
+    async removeEvents(count) {
+        this.events.splice(0, count);
+    }
+    async eventCount() {
+        return this.events.length;
+    }
+    async clear() {
+        this.events = [];
+    }
+    /**
+     * Update the maximum number of stored events.
+     */
+    setMaxEvents(maxEvents) {
+        this.maxEvents = Math.max(maxEvents, types_1.Constraints.MIN_STORED_EVENTS);
+    }
+}
+exports.InMemoryEventStorage = InMemoryEventStorage;
+/**
+ * LocalStorage-based event storage implementation.
+ * Persists events across page reloads and browser restarts.
+ */
+class LocalStorageEventStorage {
+    constructor(maxEvents = types_1.Constraints.MIN_STORED_EVENTS) {
+        this.events = null;
+        this.maxEvents = Math.max(maxEvents, types_1.Constraints.MIN_STORED_EVENTS);
+    }
+    loadEvents() {
+        if (this.events !== null) {
+            return this.events;
+        }
+        try {
+            const stored = localStorage.getItem(STORAGE_KEY);
+            if (stored) {
+                this.events = JSON.parse(stored);
+            }
+            else {
+                this.events = [];
+            }
+        }
+        catch (e) {
+            logger_1.logger.warn('Failed to load events from localStorage', e);
+            this.events = [];
+        }
+        return this.events;
+    }
+    saveEvents() {
+        try {
+            localStorage.setItem(STORAGE_KEY, JSON.stringify(this.events ?? []));
+        }
+        catch (e) {
+            logger_1.logger.error('Failed to save events to localStorage', e);
+            throw new types_1.MGMError('STORAGE_ERROR', 'Failed to save events to localStorage');
+        }
+    }
+    async store(event) {
+        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_1.logger.debug(`Dropped ${excess} oldest events due to storage limit`);
+        }
+        this.saveEvents();
+    }
+    async fetchEvents(limit) {
+        const events = this.loadEvents();
+        return events.slice(0, limit);
+    }
+    async removeEvents(count) {
+        const events = this.loadEvents();
+        events.splice(0, count);
+        this.saveEvents();
+    }
+    async eventCount() {
+        return this.loadEvents().length;
+    }
+    async clear() {
+        this.events = [];
+        try {
+            localStorage.removeItem(STORAGE_KEY);
+        }
+        catch (e) {
+            logger_1.logger.warn('Failed to clear events from localStorage', e);
+        }
+    }
+    /**
+     * Update the maximum number of stored events.
+     */
+    setMaxEvents(maxEvents) {
+        this.maxEvents = Math.max(maxEvents, types_1.Constraints.MIN_STORED_EVENTS);
+    }
+}
+exports.LocalStorageEventStorage = LocalStorageEventStorage;
+/**
+ * Create the appropriate storage implementation based on the environment.
+ */
+function createDefaultStorage(maxEvents) {
+    if (isLocalStorageAvailable()) {
+        logger_1.logger.debug('Using LocalStorage for event persistence');
+        return new LocalStorageEventStorage(maxEvents);
+    }
+    logger_1.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 {
+    constructor() {
+        this.inMemoryUserId = null;
+        this.inMemoryAppVersion = null;
+    }
+    /**
+     * Get the persisted user ID.
+     */
+    getUserId() {
+        if (isLocalStorageAvailable()) {
+            return localStorage.getItem(USER_ID_KEY);
+        }
+        return this.inMemoryUserId;
+    }
+    /**
+     * Set the user ID (persists across sessions).
+     */
+    setUserId(userId) {
+        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() {
+        if (isLocalStorageAvailable()) {
+            return localStorage.getItem(APP_VERSION_KEY);
+        }
+        return this.inMemoryAppVersion;
+    }
+    /**
+     * Set the app version.
+     */
+    setAppVersion(version) {
+        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() {
+        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;
+    }
+}
+exports.persistence = new PersistenceManager();
+//# sourceMappingURL=storage.js.map

package/dist/cjs/storage.js.map

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

package/dist/cjs/types.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_NAME_REGEX = exports.Constraints = exports.DefaultConfiguration = exports.SystemProperties = exports.SystemEvents = exports.MGMError = void 0;
+/**
+ * Custom error class for SDK errors.
+ */
+class MGMError extends Error {
+    constructor(type, message, options) {
+        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);
+        }
+    }
+}
+exports.MGMError = MGMError;
+/**
+ * System event names (prefixed with $).
+ */
+exports.SystemEvents = {
+    APP_INSTALLED: '$app_installed',
+    APP_UPDATED: '$app_updated',
+    APP_OPENED: '$app_opened',
+    APP_BACKGROUNDED: '$app_backgrounded',
+};
+/**
+ * System property keys (prefixed with $).
+ */
+exports.SystemProperties = {
+    DEVICE_TYPE: '$device_type',
+    DEVICE_MODEL: '$device_model',
+    VERSION: '$version',
+    PREVIOUS_VERSION: '$previous_version',
+};
+/**
+ * Default configuration values.
+ */
+exports.DefaultConfiguration = {
+    baseURL: 'https://mostlygoodmetrics.com',
+    environment: 'production',
+    maxBatchSize: 100,
+    flushInterval: 30,
+    maxStoredEvents: 10000,
+    enableDebugLogging: false,
+    trackAppLifecycleEvents: true,
+};
+/**
+ * Validation constraints.
+ */
+exports.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
+};
+/**
+ * Regular expression for validating event names.
+ * Must start with a letter (or $ for system events) followed by alphanumeric and underscores.
+ */
+exports.EVENT_NAME_REGEX = /^\$?[a-zA-Z][a-zA-Z0-9_]*$/;
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";;;AA4QA;;GAEG;AACH,MAAa,QAAS,SAAQ,KAAK;IAKjC,YACE,IAAkB,EAClB,OAAe,EACf,OAAsD;QAEtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;QAEtC,uEAAuE;QACvE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF;AArBD,4BAqBC;AAED;;GAEG;AACU,QAAA,YAAY,GAAG;IAC1B,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,UAAU,EAAE,aAAa;IACzB,gBAAgB,EAAE,mBAAmB;CAC7B,CAAC;AAEX;;GAEG;AACU,QAAA,gBAAgB,GAAG;IAC9B,WAAW,EAAE,cAAc;IAC3B,YAAY,EAAE,eAAe;IAC7B,OAAO,EAAE,UAAU;IACnB,gBAAgB,EAAE,mBAAmB;CAC7B,CAAC;AAEX;;GAEG;AACU,QAAA,oBAAoB,GAAG;IAClC,OAAO,EAAE,+BAA+B;IACxC,WAAW,EAAE,YAAY;IACzB,YAAY,EAAE,GAAG;IACjB,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,KAAK;IACtB,kBAAkB,EAAE,KAAK;IACzB,uBAAuB,EAAE,IAAI;CACrB,CAAC;AAEX;;GAEG;AACU,QAAA,WAAW,GAAG;IACzB,qBAAqB,EAAE,GAAG;IAC1B,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,CAAC;IACjB,kBAAkB,EAAE,CAAC;IACrB,iBAAiB,EAAE,GAAG;IACtB,0BAA0B,EAAE,IAAI;IAChC,kBAAkB,EAAE,CAAC;IACrB,uBAAuB,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO;IAC3C,2BAA2B,EAAE,IAAI,EAAE,MAAM;CACjC,CAAC;AAEX;;;GAGG;AACU,QAAA,gBAAgB,GAAG,4BAA4B,CAAC"}