@mostly-good-metrics/javascript 0.1.0

package/dist/esm/utils.js

@@ -0,0 +1,236 @@
+import { logger } from './logger';
+import { Constraints, DefaultConfiguration, EVENT_NAME_REGEX, MGMError, } from './types';
+/**
+ * Generate a UUID v4 string.
+ */
+export function generateUUID() {
+    // Use crypto.randomUUID if available (modern browsers and Node.js 19+)
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback implementation
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Get the current timestamp in ISO8601 format.
+ */
+export function getISOTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Validate an event name.
+ * Must match pattern: ^$?[a-zA-Z][a-zA-Z0-9_]*$
+ * Max 255 characters.
+ */
+export function isValidEventName(name) {
+    if (!name || name.length > Constraints.MAX_EVENT_NAME_LENGTH) {
+        return false;
+    }
+    return EVENT_NAME_REGEX.test(name);
+}
+/**
+ * Validate an event name and throw if invalid.
+ */
+export function validateEventName(name) {
+    if (!name) {
+        throw new MGMError('INVALID_EVENT_NAME', 'Event name is required');
+    }
+    if (name.length > Constraints.MAX_EVENT_NAME_LENGTH) {
+        throw new MGMError('INVALID_EVENT_NAME', `Event name must be ${Constraints.MAX_EVENT_NAME_LENGTH} characters or less`);
+    }
+    if (!EVENT_NAME_REGEX.test(name)) {
+        throw new MGMError('INVALID_EVENT_NAME', 'Event name must start with a letter (or $ for system events) and contain only alphanumeric characters and underscores');
+    }
+}
+/**
+ * Sanitize event properties by truncating strings and limiting depth.
+ */
+export function sanitizeProperties(properties, maxDepth = Constraints.MAX_PROPERTY_DEPTH) {
+    if (!properties || typeof properties !== 'object') {
+        return undefined;
+    }
+    const sanitized = sanitizeValue(properties, 0, maxDepth);
+    if (typeof sanitized === 'object' && sanitized !== null && !Array.isArray(sanitized)) {
+        return sanitized;
+    }
+    return undefined;
+}
+/**
+ * Recursively sanitize a property value.
+ */
+function sanitizeValue(value, depth, maxDepth) {
+    // Null is valid
+    if (value === null) {
+        return null;
+    }
+    // Primitives
+    if (typeof value === 'boolean' || typeof value === 'number') {
+        return value;
+    }
+    // Strings - truncate if needed
+    if (typeof value === 'string') {
+        if (value.length > Constraints.MAX_STRING_PROPERTY_LENGTH) {
+            logger.debug(`Truncating string property from ${value.length} to ${Constraints.MAX_STRING_PROPERTY_LENGTH} characters`);
+            return value.substring(0, Constraints.MAX_STRING_PROPERTY_LENGTH);
+        }
+        return value;
+    }
+    // Arrays
+    if (Array.isArray(value)) {
+        if (depth >= maxDepth) {
+            logger.debug(`Max property depth reached, omitting nested array`);
+            return null;
+        }
+        return value.map((item) => sanitizeValue(item, depth + 1, maxDepth));
+    }
+    // Objects
+    if (typeof value === 'object') {
+        if (depth >= maxDepth) {
+            logger.debug(`Max property depth reached, omitting nested object`);
+            return null;
+        }
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = sanitizeValue(val, depth + 1, maxDepth);
+        }
+        return result;
+    }
+    // Unknown type - convert to null
+    return null;
+}
+/**
+ * Resolve configuration with defaults.
+ */
+export function resolveConfiguration(config) {
+    const maxBatchSize = Math.min(Math.max(config.maxBatchSize ?? DefaultConfiguration.maxBatchSize, Constraints.MIN_BATCH_SIZE), Constraints.MAX_BATCH_SIZE);
+    const flushInterval = Math.max(config.flushInterval ?? DefaultConfiguration.flushInterval, Constraints.MIN_FLUSH_INTERVAL);
+    const maxStoredEvents = Math.max(config.maxStoredEvents ?? DefaultConfiguration.maxStoredEvents, Constraints.MIN_STORED_EVENTS);
+    return {
+        apiKey: config.apiKey,
+        baseURL: config.baseURL ?? DefaultConfiguration.baseURL,
+        environment: config.environment ?? DefaultConfiguration.environment,
+        maxBatchSize,
+        flushInterval,
+        maxStoredEvents,
+        enableDebugLogging: config.enableDebugLogging ?? DefaultConfiguration.enableDebugLogging,
+        trackAppLifecycleEvents: config.trackAppLifecycleEvents ?? DefaultConfiguration.trackAppLifecycleEvents,
+        bundleId: config.bundleId ?? detectBundleId(),
+        appVersion: config.appVersion ?? '',
+        osVersion: config.osVersion ?? '',
+        storage: config.storage,
+        networkClient: config.networkClient,
+    };
+}
+/**
+ * Detect the bundle ID from the current environment.
+ */
+function detectBundleId() {
+    // In browser, use the hostname
+    if (typeof window !== 'undefined' && window.location) {
+        return window.location.hostname;
+    }
+    // In Node.js, could use package.json name but that requires fs access
+    return '';
+}
+/**
+ * Detect the current platform.
+ */
+export function detectPlatform() {
+    // Check for React Native / Expo
+    if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+        // Could check for Expo-specific globals here
+        return 'react-native';
+    }
+    // Check for Node.js
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        return 'node';
+    }
+    // Default to web for browser environments
+    return 'web';
+}
+/**
+ * Detect the device type from user agent.
+ */
+export function detectDeviceType() {
+    if (typeof navigator === 'undefined' || !navigator.userAgent) {
+        return 'unknown';
+    }
+    const ua = navigator.userAgent.toLowerCase();
+    // Check for specific device types
+    if (/tablet|ipad|playbook|silk/i.test(ua)) {
+        return 'tablet';
+    }
+    if (/mobile|iphone|ipod|android.*mobile|blackberry|opera mini|opera mobi/i.test(ua)) {
+        return 'phone';
+    }
+    if (/smart-tv|smarttv|googletv|appletv|hbbtv|pov_tv|netcast.tv/i.test(ua)) {
+        return 'tv';
+    }
+    // Default to desktop for other browsers
+    if (typeof window !== 'undefined') {
+        return 'desktop';
+    }
+    return 'unknown';
+}
+/**
+ * Get the OS version string.
+ */
+export function getOSVersion() {
+    if (typeof navigator === 'undefined' || !navigator.userAgent) {
+        return '';
+    }
+    const ua = navigator.userAgent;
+    // Try to extract OS version from user agent
+    const patterns = [
+        [/Windows NT ([\d.]+)/i, 'Windows'],
+        [/Mac OS X ([\d_.]+)/i, 'macOS'],
+        [/iPhone OS ([\d_]+)/i, 'iOS'],
+        [/iPad.*OS ([\d_]+)/i, 'iPadOS'],
+        [/Android ([\d.]+)/i, 'Android'],
+        [/Linux/i, 'Linux'],
+    ];
+    for (const [pattern, osName] of patterns) {
+        const match = ua.match(pattern);
+        if (match) {
+            const version = match[1]?.replace(/_/g, '.') ?? '';
+            return version ? `${osName} ${version}` : osName;
+        }
+    }
+    return '';
+}
+/**
+ * Get the browser/device model.
+ */
+export function getDeviceModel() {
+    if (typeof navigator === 'undefined' || !navigator.userAgent) {
+        return '';
+    }
+    const ua = navigator.userAgent;
+    // Try to extract browser name and version
+    const patterns = [
+        [/Chrome\/([\d.]+)/i, 'Chrome'],
+        [/Firefox\/([\d.]+)/i, 'Firefox'],
+        [/Safari\/([\d.]+)/i, 'Safari'],
+        [/Edge\/([\d.]+)/i, 'Edge'],
+        [/MSIE ([\d.]+)/i, 'IE'],
+        [/Trident.*rv:([\d.]+)/i, 'IE'],
+    ];
+    for (const [pattern, browserName] of patterns) {
+        const match = ua.match(pattern);
+        if (match) {
+            return `${browserName} ${match[1]}`;
+        }
+    }
+    return '';
+}
+/**
+ * Delay execution for a specified number of milliseconds.
+ */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

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

package/dist/types/client.d.ts

@@ -0,0 +1,126 @@
+import { EventProperties, MGMConfiguration, ResolvedConfiguration } from './types';
+/**
+ * Main client for MostlyGoodMetrics.
+ * Use the static `configure` method to initialize, then use static methods or the instance.
+ */
+export declare class MostlyGoodMetrics {
+    private static instance;
+    private config;
+    private storage;
+    private networkClient;
+    private flushTimer;
+    private isFlushingInternal;
+    private sessionIdValue;
+    private lifecycleSetup;
+    /**
+     * Private constructor - use `configure` to create an instance.
+     */
+    private constructor();
+    /**
+     * Configure and initialize the SDK.
+     * Returns the singleton instance.
+     */
+    static configure(config: MGMConfiguration): MostlyGoodMetrics;
+    /**
+     * Get the shared instance, or null if not configured.
+     */
+    static get shared(): MostlyGoodMetrics | null;
+    /**
+     * Check if the SDK has been configured.
+     */
+    static get isConfigured(): boolean;
+    /**
+     * Reset the SDK (primarily for testing).
+     */
+    static reset(): void;
+    /**
+     * Track an event with the given name and optional properties.
+     */
+    static track(name: string, properties?: EventProperties): void;
+    /**
+     * Identify the current user.
+     */
+    static identify(userId: string): void;
+    /**
+     * Reset user identity.
+     */
+    static resetIdentity(): void;
+    /**
+     * Flush pending events to the server.
+     */
+    static flush(): Promise<void>;
+    /**
+     * Start a new session.
+     */
+    static startNewSession(): void;
+    /**
+     * Clear all pending events.
+     */
+    static clearPendingEvents(): Promise<void>;
+    /**
+     * Get the count of pending events.
+     */
+    static getPendingEventCount(): Promise<number>;
+    /**
+     * Get the current user ID.
+     */
+    get userId(): string | null;
+    /**
+     * Get the current session ID.
+     */
+    get sessionId(): string;
+    /**
+     * Check if a flush operation is in progress.
+     */
+    get isFlushing(): boolean;
+    /**
+     * Get the resolved configuration.
+     */
+    get configuration(): ResolvedConfiguration;
+    /**
+     * Track an event with the given name and optional properties.
+     */
+    track(name: string, properties?: EventProperties): void;
+    /**
+     * Identify the current user.
+     */
+    identify(userId: string): void;
+    /**
+     * Reset user identity.
+     */
+    resetIdentity(): void;
+    /**
+     * Start a new session.
+     */
+    startNewSession(): void;
+    /**
+     * Flush pending events to the server.
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear all pending events.
+     */
+    clearPendingEvents(): Promise<void>;
+    /**
+     * Get the count of pending events.
+     */
+    getPendingEventCount(): Promise<number>;
+    /**
+     * Clean up resources (stop timers, etc.).
+     */
+    destroy(): void;
+    private checkBatchSize;
+    private performFlush;
+    private buildPayload;
+    private startFlushTimer;
+    private stopFlushTimer;
+    private setupLifecycleTracking;
+    private removeLifecycleListeners;
+    private trackInstallOrUpdate;
+    private trackAppOpened;
+    private handleVisibilityChange;
+    private handleBeforeUnload;
+    private handlePageHide;
+    private flushWithBeacon;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,eAAe,EAGf,gBAAgB,EAIhB,qBAAqB,EAGtB,MAAM,SAAS,CAAC;AAgBjB;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IAEzD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAS;IAE/B;;OAEG;IACH,OAAO;IAwBP;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB;IAc7D;;OAEG;IACH,MAAM,KAAK,MAAM,IAAI,iBAAiB,GAAG,IAAI,CAE5C;IAED;;OAEG;IACH,MAAM,KAAK,YAAY,IAAI,OAAO,CAEjC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAWpB;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI;IAI9D;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;OAEG;IACH,MAAM,CAAC,eAAe,IAAI,IAAI;IAI9B;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1C;;OAEG;IACH,MAAM,CAAC,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC;IAQ9C;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,qBAAqB,CAEzC;IAMD;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI;IAwCvD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAU9B;;OAEG;IACH,aAAa,IAAI,IAAI;IAKrB;;OAEG;IACH,eAAe,IAAI,IAAI;IAKvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5B;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKzC;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7C;;OAEG;IACH,OAAO,IAAI,IAAI;YAUD,cAAc;YAQd,YAAY;IA4C1B,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,sBAAsB;IA4B9B,OAAO,CAAC,wBAAwB;IAUhC,OAAO,CAAC,oBAAoB;IA4B5B,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,sBAAsB,CAS5B;IAEF,OAAO,CAAC,kBAAkB,CAGxB;IAEF,OAAO,CAAC,cAAc,CAGpB;IAEF,OAAO,CAAC,eAAe;CAWxB"}

package/dist/types/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MostlyGoodMetrics JavaScript SDK
+ *
+ * A lightweight, framework-agnostic analytics library for web applications.
+ *
+ * @example
+ * ```typescript
+ * import { MostlyGoodMetrics } from '@mostly-good-metrics/javascript';
+ *
+ * // Initialize the SDK
+ * MostlyGoodMetrics.configure({
+ *   apiKey: 'mgm_proj_your_api_key',
+ *   environment: 'production',
+ * });
+ *
+ * // Track events
+ * MostlyGoodMetrics.track('button_clicked', {
+ *   button_id: 'submit',
+ *   page: '/checkout',
+ * });
+ *
+ * // Identify users
+ * MostlyGoodMetrics.identify('user_123');
+ * ```
+ */
+export { MostlyGoodMetrics } from './client';
+export type { MGMConfiguration, ResolvedConfiguration, EventProperties, EventPropertyValue, MGMEvent, MGMEventContext, MGMEventsPayload, Platform, DeviceType, MGMErrorType, SendResult, IEventStorage, INetworkClient, } from './types';
+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 { logger } from './logger';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,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"}

package/dist/types/logger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Internal logger for the MostlyGoodMetrics SDK.
+ * Only outputs when debug logging is enabled.
+ */
+/**
+ * Enable or disable debug logging.
+ */
+export declare function setDebugLogging(enabled: boolean): void;
+/**
+ * Check if debug logging is enabled.
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Log a debug message (only when debug logging is enabled).
+ */
+export declare function debug(message: string, ...args: unknown[]): void;
+/**
+ * Log an info message (only when debug logging is enabled).
+ */
+export declare function info(message: string, ...args: unknown[]): void;
+/**
+ * Log a warning message (always shown).
+ */
+export declare function warn(message: string, ...args: unknown[]): void;
+/**
+ * Log an error message (always shown).
+ */
+export declare function error(message: string, ...args: unknown[]): void;
+export declare const logger: {
+    setDebugLogging: typeof setDebugLogging;
+    isDebugEnabled: typeof isDebugEnabled;
+    debug: typeof debug;
+    info: typeof info;
+    warn: typeof warn;
+    error: typeof error;
+};
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAI/D;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAI9D;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE9D;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE/D;AAED,eAAO,MAAM,MAAM;;;;;;;CAOlB,CAAC"}

package/dist/types/network.d.ts

@@ -0,0 +1,28 @@
+import { INetworkClient, MGMEventsPayload, ResolvedConfiguration, SendResult } from './types';
+/**
+ * Default network client using the Fetch API.
+ */
+export declare class FetchNetworkClient implements INetworkClient {
+    private retryAfterTime;
+    /**
+     * Send events to the MostlyGoodMetrics API.
+     */
+    sendEvents(payload: MGMEventsPayload, config: ResolvedConfiguration): Promise<SendResult>;
+    /**
+     * Handle the API response and return appropriate result.
+     */
+    private handleResponse;
+    /**
+     * Check if currently rate limited.
+     */
+    isRateLimited(): boolean;
+    /**
+     * Get the time when rate limiting expires.
+     */
+    getRetryAfterTime(): Date | null;
+}
+/**
+ * Create the default network client.
+ */
+export declare function createDefaultNetworkClient(): INetworkClient;
+//# sourceMappingURL=network.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/network.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,cAAc,EAEd,gBAAgB,EAChB,qBAAqB,EACrB,UAAU,EACX,MAAM,SAAS,CAAC;AAqCjB;;GAEG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,cAAc,CAAqB;IAE3C;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;IAuE/F;;OAEG;IACH,OAAO,CAAC,cAAc;IAwEtB;;OAEG;IACH,aAAa,IAAI,OAAO;IAaxB;;OAEG;IACH,iBAAiB,IAAI,IAAI,GAAG,IAAI;CAGjC;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,cAAc,CAE3D"}

package/dist/types/storage.d.ts

@@ -0,0 +1,76 @@
+import { IEventStorage, MGMEvent } from './types';
+/**
+ * In-memory event storage implementation.
+ * Used as a fallback when localStorage is not available,
+ * or for testing purposes.
+ */
+export declare class InMemoryEventStorage implements IEventStorage {
+    private events;
+    private maxEvents;
+    constructor(maxEvents?: number);
+    store(event: MGMEvent): Promise<void>;
+    fetchEvents(limit: number): Promise<MGMEvent[]>;
+    removeEvents(count: number): Promise<void>;
+    eventCount(): Promise<number>;
+    clear(): Promise<void>;
+    /**
+     * Update the maximum number of stored events.
+     */
+    setMaxEvents(maxEvents: number): void;
+}
+/**
+ * LocalStorage-based event storage implementation.
+ * Persists events across page reloads and browser restarts.
+ */
+export declare class LocalStorageEventStorage implements IEventStorage {
+    private maxEvents;
+    private events;
+    constructor(maxEvents?: number);
+    private loadEvents;
+    private saveEvents;
+    store(event: MGMEvent): Promise<void>;
+    fetchEvents(limit: number): Promise<MGMEvent[]>;
+    removeEvents(count: number): Promise<void>;
+    eventCount(): Promise<number>;
+    clear(): Promise<void>;
+    /**
+     * Update the maximum number of stored events.
+     */
+    setMaxEvents(maxEvents: number): void;
+}
+/**
+ * Create the appropriate storage implementation based on the environment.
+ */
+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.
+ */
+declare class PersistenceManager {
+    private inMemoryUserId;
+    private inMemoryAppVersion;
+    /**
+     * Get the persisted user ID.
+     */
+    getUserId(): string | null;
+    /**
+     * Set the user ID (persists across sessions).
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Get the persisted app version (for detecting updates).
+     */
+    getAppVersion(): string | null;
+    /**
+     * Set the app version.
+     */
+    setAppVersion(version: string | null): void;
+    /**
+     * Check if this is the first time the app has been opened.
+     * Uses localStorage to detect first-ever installation.
+     */
+    isFirstLaunch(): boolean;
+}
+export declare const persistence: PersistenceManager;
+export {};
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,aAAa,EAAY,QAAQ,EAAE,MAAM,SAAS,CAAC;AAuBzE;;;;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;IAEjD;;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;CAczB;AAED,eAAO,MAAM,WAAW,oBAA2B,CAAC"}