achievements-engine 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1699 @@
+'use strict';
+
+/**
+ * Lightweight, type-safe event emitter for the achievements engine
+ * Zero dependencies, memory-leak safe implementation
+ */
+class EventEmitter {
+    constructor() {
+        this.listeners = new Map();
+        this.onceListeners = new Map();
+    }
+    /**
+     * Subscribe to an event
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     */
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
+        // Return unsubscribe function
+        return () => this.off(event, handler);
+    }
+    /**
+     * Subscribe to an event once (auto-unsubscribes after first emission)
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     */
+    once(event, handler) {
+        if (!this.onceListeners.has(event)) {
+            this.onceListeners.set(event, new Set());
+        }
+        this.onceListeners.get(event).add(handler);
+        // Return unsubscribe function
+        return () => {
+            const onceSet = this.onceListeners.get(event);
+            if (onceSet) {
+                onceSet.delete(handler);
+            }
+        };
+    }
+    /**
+     * Unsubscribe from an event
+     * @param event - Event name
+     * @param handler - Event handler function to remove
+     */
+    off(event, handler) {
+        const regularListeners = this.listeners.get(event);
+        if (regularListeners) {
+            regularListeners.delete(handler);
+            // Clean up empty sets to prevent memory leaks
+            if (regularListeners.size === 0) {
+                this.listeners.delete(event);
+            }
+        }
+        const onceSet = this.onceListeners.get(event);
+        if (onceSet) {
+            onceSet.delete(handler);
+            // Clean up empty sets
+            if (onceSet.size === 0) {
+                this.onceListeners.delete(event);
+            }
+        }
+    }
+    /**
+     * Emit an event to all subscribers
+     * @param event - Event name
+     * @param data - Event payload
+     */
+    emit(event, data) {
+        // Call regular listeners
+        const regularListeners = this.listeners.get(event);
+        if (regularListeners) {
+            // Create a copy to avoid issues if listeners modify the set during iteration
+            const listenersCopy = Array.from(regularListeners);
+            listenersCopy.forEach(handler => {
+                try {
+                    handler(data);
+                }
+                catch (error) {
+                    // Prevent one handler's error from stopping other handlers
+                    console.error(`Error in event handler for "${event}":`, error);
+                }
+            });
+        }
+        // Call once listeners and remove them
+        const onceSet = this.onceListeners.get(event);
+        if (onceSet) {
+            const onceListenersCopy = Array.from(onceSet);
+            // Clear the set before calling handlers to prevent re-entry issues
+            this.onceListeners.delete(event);
+            onceListenersCopy.forEach(handler => {
+                try {
+                    handler(data);
+                }
+                catch (error) {
+                    console.error(`Error in once event handler for "${event}":`, error);
+                }
+            });
+        }
+    }
+    /**
+     * Remove all listeners for a specific event, or all events if no event specified
+     * @param event - Optional event name. If not provided, removes all listeners.
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+            this.onceListeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+            this.onceListeners.clear();
+        }
+    }
+    /**
+     * Get the number of listeners for an event
+     * @param event - Event name
+     * @returns Number of listeners
+     */
+    listenerCount(event) {
+        var _a, _b;
+        const regularCount = ((_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.size) || 0;
+        const onceCount = ((_b = this.onceListeners.get(event)) === null || _b === void 0 ? void 0 : _b.size) || 0;
+        return regularCount + onceCount;
+    }
+    /**
+     * Get all event names that have listeners
+     * @returns Array of event names
+     */
+    eventNames() {
+        const regularEvents = Array.from(this.listeners.keys());
+        const onceEvents = Array.from(this.onceListeners.keys());
+        // Combine and deduplicate
+        return Array.from(new Set([...regularEvents, ...onceEvents]));
+    }
+}
+
+// Type guard to check if config is simple format
+function isSimpleConfig(config) {
+    if (!config || typeof config !== 'object')
+        return false;
+    const firstKey = Object.keys(config)[0];
+    if (!firstKey)
+        return true; // Empty config is considered simple
+    const firstValue = config[firstKey];
+    // Check if it's the current complex format (array of AchievementCondition)
+    if (Array.isArray(firstValue))
+        return false;
+    // Check if it's the simple format (object with string keys)
+    return typeof firstValue === 'object' && !Array.isArray(firstValue);
+}
+// Generate a unique ID for achievements
+function generateId() {
+    return Math.random().toString(36).substr(2, 9);
+}
+// Check if achievement details has a custom condition
+function hasCustomCondition(details) {
+    return 'condition' in details && typeof details.condition === 'function';
+}
+// Convert simple config to complex config format
+function normalizeAchievements(config) {
+    if (!isSimpleConfig(config)) {
+        // Already in complex format, return as-is
+        return config;
+    }
+    const normalized = {};
+    Object.entries(config).forEach(([metric, achievements]) => {
+        normalized[metric] = Object.entries(achievements).map(([key, achievement]) => {
+            if (hasCustomCondition(achievement)) {
+                // Custom condition function
+                return {
+                    isConditionMet: (_value, _state) => {
+                        // Convert internal metrics format (arrays) to simple format for custom conditions
+                        const simpleMetrics = {};
+                        Object.entries(_state.metrics).forEach(([key, val]) => {
+                            simpleMetrics[key] = Array.isArray(val) ? val[0] : val;
+                        });
+                        return achievement.condition(simpleMetrics);
+                    },
+                    achievementDetails: {
+                        achievementId: `${metric}_custom_${generateId()}`,
+                        achievementTitle: achievement.title,
+                        achievementDescription: achievement.description || '',
+                        achievementIconKey: achievement.icon || 'default'
+                    }
+                };
+            }
+            else {
+                // Threshold-based achievement
+                const threshold = parseFloat(key);
+                const isValidThreshold = !isNaN(threshold);
+                let conditionMet;
+                if (isValidThreshold) {
+                    // Numeric threshold
+                    conditionMet = (value) => {
+                        const numValue = Array.isArray(value) ? value[0] : value;
+                        return typeof numValue === 'number' && numValue >= threshold;
+                    };
+                }
+                else {
+                    // String or boolean threshold
+                    conditionMet = (value) => {
+                        const actualValue = Array.isArray(value) ? value[0] : value;
+                        // Handle boolean thresholds
+                        if (key === 'true')
+                            return actualValue === true;
+                        if (key === 'false')
+                            return actualValue === false;
+                        // Handle string thresholds
+                        return actualValue === key;
+                    };
+                }
+                return {
+                    isConditionMet: conditionMet,
+                    achievementDetails: {
+                        achievementId: `${metric}_${key}`,
+                        achievementTitle: achievement.title,
+                        achievementDescription: achievement.description || (isValidThreshold ? `Reach ${threshold} ${metric}` : `Achieve ${key} for ${metric}`),
+                        achievementIconKey: achievement.icon || 'default'
+                    }
+                };
+            }
+        });
+    });
+    return normalized;
+}
+
+/**
+ * Exports achievement data to a JSON string
+ *
+ * @param metrics - Current achievement metrics
+ * @param unlocked - Array of unlocked achievement IDs
+ * @param configHash - Optional hash of achievement configuration for validation
+ * @returns JSON string containing all achievement data
+ *
+ * @example
+ * ```typescript
+ * const json = exportAchievementData(_metrics, ['score_100', 'level_5']);
+ * // Save json to file or send to server
+ * ```
+ */
+function exportAchievementData(metrics, unlocked, configHash) {
+    const data = Object.assign({ version: '3.3.0', timestamp: Date.now(), metrics, unlockedAchievements: unlocked }, (configHash && { configHash }));
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Creates a simple hash of the achievement configuration
+ * Used to validate that imported data matches the current configuration
+ *
+ * @param config - Achievement configuration object
+ * @returns Simple hash string
+ */
+function createConfigHash(config) {
+    // Simple hash based on stringified config
+    // In production, you might want to use a more robust hashing algorithm
+    const str = JSON.stringify(config);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return hash.toString(36);
+}
+
+/**
+ * Imports achievement data from a JSON string
+ *
+ * @param jsonString - JSON string containing exported achievement data
+ * @param currentMetrics - Current metrics state
+ * @param currentUnlocked - Current unlocked achievements
+ * @param options - Import options
+ * @returns Import result with success status and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = importAchievementData(
+ *   jsonString,
+ *   currentMetrics,
+ *   currentUnlocked,
+ *   { mergeStrategy: 'merge', validate: true }
+ * );
+ *
+ * if (result.success) {
+ *   console.log(`Imported ${result.imported.achievements} achievements`);
+ * } else {
+ *   console.error('Import failed:', result.errors);
+ * }
+ * ```
+ */
+function importAchievementData(jsonString, currentMetrics, currentUnlocked, options = {}) {
+    const { mergeStrategy = 'replace', validate = true, expectedConfigHash } = options;
+    const warnings = [];
+    // Parse JSON
+    let data;
+    try {
+        data = JSON.parse(jsonString);
+    }
+    catch (_a) {
+        return {
+            success: false,
+            imported: { metrics: 0, achievements: 0 },
+            errors: ['Invalid JSON format']
+        };
+    }
+    // Validate structure
+    if (validate) {
+        const validationErrors = validateExportedData(data, expectedConfigHash);
+        if (validationErrors.length > 0) {
+            return {
+                success: false,
+                imported: { metrics: 0, achievements: 0 },
+                errors: validationErrors
+            };
+        }
+    }
+    // Version compatibility check
+    if (data.version && data.version !== '3.3.0') {
+        warnings.push(`Data exported from version ${data.version}, current version is 3.3.0`);
+    }
+    // Merge metrics based on strategy
+    let mergedMetrics;
+    let mergedUnlocked;
+    switch (mergeStrategy) {
+        case 'replace':
+            // Replace all existing data
+            mergedMetrics = data.metrics;
+            mergedUnlocked = data.unlockedAchievements;
+            break;
+        case 'merge':
+            // Union of both datasets, keeping higher metric values
+            mergedMetrics = mergeMetrics(currentMetrics, data.metrics);
+            mergedUnlocked = Array.from(new Set([...currentUnlocked, ...data.unlockedAchievements]));
+            break;
+        case 'preserve':
+            // Keep existing values, only add new ones
+            mergedMetrics = preserveMetrics(currentMetrics, data.metrics);
+            mergedUnlocked = Array.from(new Set([...currentUnlocked, ...data.unlockedAchievements]));
+            break;
+        default:
+            return {
+                success: false,
+                imported: { metrics: 0, achievements: 0 },
+                errors: [`Invalid merge strategy: ${mergeStrategy}`]
+            };
+    }
+    return Object.assign(Object.assign({ success: true, imported: {
+            metrics: Object.keys(mergedMetrics).length,
+            achievements: mergedUnlocked.length
+        } }, (warnings.length > 0 && { warnings })), { mergedMetrics,
+        mergedUnlocked });
+}
+/**
+ * Validates the structure and content of exported data
+ */
+function validateExportedData(data, expectedConfigHash) {
+    const errors = [];
+    // Check required fields
+    if (!data.version) {
+        errors.push('Missing version field');
+    }
+    if (!data.timestamp) {
+        errors.push('Missing timestamp field');
+    }
+    if (!data.metrics || typeof data.metrics !== 'object') {
+        errors.push('Missing or invalid metrics field');
+    }
+    if (!Array.isArray(data.unlockedAchievements)) {
+        errors.push('Missing or invalid unlockedAchievements field');
+    }
+    // Validate config hash if provided
+    if (expectedConfigHash && data.configHash && data.configHash !== expectedConfigHash) {
+        errors.push('Configuration mismatch: imported data may not be compatible with current achievement configuration');
+    }
+    // Validate metrics structure
+    if (data.metrics && typeof data.metrics === 'object') {
+        for (const [key, value] of Object.entries(data.metrics)) {
+            if (!Array.isArray(value)) {
+                errors.push(`Invalid metric format for "${key}": expected array, got ${typeof value}`);
+            }
+        }
+    }
+    // Validate achievement IDs are strings
+    if (Array.isArray(data.unlockedAchievements)) {
+        const invalidIds = data.unlockedAchievements.filter((id) => typeof id !== 'string');
+        if (invalidIds.length > 0) {
+            errors.push('All achievement IDs must be strings');
+        }
+    }
+    return errors;
+}
+/**
+ * Merges two metrics objects, keeping higher values for overlapping keys
+ */
+function mergeMetrics(current, imported) {
+    const merged = Object.assign({}, current);
+    for (const [key, importedValues] of Object.entries(imported)) {
+        if (!merged[key]) {
+            // New metric, add it
+            merged[key] = importedValues;
+        }
+        else {
+            // Existing metric, merge values
+            merged[key] = mergeMetricValues(merged[key], importedValues);
+        }
+    }
+    return merged;
+}
+/**
+ * Merges two metric value arrays, keeping higher numeric values
+ */
+function mergeMetricValues(current, imported) {
+    // For simplicity, we'll use the imported values if they're "higher"
+    // This works for numeric values; for other types, we prefer imported
+    const currentValue = current[0];
+    const importedValue = imported[0];
+    // If both are numbers, keep the higher one
+    if (typeof currentValue === 'number' && typeof importedValue === 'number') {
+        return currentValue >= importedValue ? current : imported;
+    }
+    // For non-numeric values, prefer imported (assume it's newer)
+    return imported;
+}
+/**
+ * Preserves existing metrics, only adding new ones from imported data
+ */
+function preserveMetrics(current, imported) {
+    const preserved = Object.assign({}, current);
+    for (const [key, value] of Object.entries(imported)) {
+        if (!preserved[key]) {
+            // Only add if it doesn't exist
+            preserved[key] = value;
+        }
+        // If it exists, keep current value (preserve strategy)
+    }
+    return preserved;
+}
+
+/**
+ * Type definitions for the achievements engine
+ * Framework-agnostic achievement system types
+ */
+const isDate = (value) => {
+    return value instanceof Date;
+};
+// Type guard to detect async storage
+function isAsyncStorage(storage) {
+    // Check if methods return Promises
+    const testResult = storage.getMetrics();
+    return testResult && typeof testResult.then === 'function';
+}
+exports.StorageType = void 0;
+(function (StorageType) {
+    StorageType["Local"] = "local";
+    StorageType["Memory"] = "memory";
+    StorageType["IndexedDB"] = "indexeddb";
+    StorageType["RestAPI"] = "restapi"; // Asynchronous REST API storage
+})(exports.StorageType || (exports.StorageType = {}));
+
+/**
+ * Base error class for all achievement-related errors
+ */
+class AchievementError extends Error {
+    constructor(message, code, recoverable, remedy) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.remedy = remedy;
+        this.name = 'AchievementError';
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AchievementError);
+        }
+    }
+}
+/**
+ * Error thrown when browser storage quota is exceeded
+ */
+class StorageQuotaError extends AchievementError {
+    constructor(bytesNeeded) {
+        super('Browser storage quota exceeded. Achievement data could not be saved.', 'STORAGE_QUOTA_EXCEEDED', true, 'Clear browser storage, reduce the number of achievements, or use an external database backend. You can export your current data using exportData() before clearing storage.');
+        this.bytesNeeded = bytesNeeded;
+        this.name = 'StorageQuotaError';
+    }
+}
+/**
+ * Error thrown when imported data fails validation
+ */
+class ImportValidationError extends AchievementError {
+    constructor(validationErrors) {
+        super(`Imported data failed validation: ${validationErrors.join(', ')}`, 'IMPORT_VALIDATION_ERROR', true, 'Check that the imported data was exported from a compatible version and matches your current achievement configuration.');
+        this.validationErrors = validationErrors;
+        this.name = 'ImportValidationError';
+    }
+}
+/**
+ * Error thrown when storage operations fail
+ */
+class StorageError extends AchievementError {
+    constructor(message, originalError) {
+        super(message, 'STORAGE_ERROR', true, 'Check browser storage permissions and available space. If using custom storage, verify the implementation is correct.');
+        this.originalError = originalError;
+        this.name = 'StorageError';
+    }
+}
+/**
+ * Error thrown when configuration is invalid
+ */
+class ConfigurationError extends AchievementError {
+    constructor(message) {
+        super(message, 'CONFIGURATION_ERROR', false, 'Review your achievement configuration and ensure it follows the correct format.');
+        this.name = 'ConfigurationError';
+    }
+}
+/**
+ * Error thrown when network sync operations fail
+ */
+class SyncError extends AchievementError {
+    constructor(message, details) {
+        super(message, 'SYNC_ERROR', true, // recoverable (can retry)
+        'Check your network connection and try again. If the problem persists, achievements will sync when connection is restored.');
+        this.name = 'SyncError';
+        this.statusCode = details === null || details === void 0 ? void 0 : details.statusCode;
+        this.timeout = details === null || details === void 0 ? void 0 : details.timeout;
+    }
+}
+/**
+ * Type guard to check if an error is an AchievementError
+ */
+function isAchievementError(error) {
+    return error instanceof AchievementError;
+}
+/**
+ * Type guard to check if an error is recoverable
+ */
+function isRecoverableError(error) {
+    return isAchievementError(error) && error.recoverable;
+}
+
+class LocalStorage {
+    constructor(storageKey) {
+        this.storageKey = storageKey;
+    }
+    serializeValue(value) {
+        if (isDate(value)) {
+            return { __type: 'Date', value: value.toISOString() };
+        }
+        return value;
+    }
+    deserializeValue(value) {
+        if (value && typeof value === 'object' && value.__type === 'Date') {
+            return new Date(value.value);
+        }
+        return value;
+    }
+    serializeMetrics(metrics) {
+        const serialized = {};
+        for (const [key, values] of Object.entries(metrics)) {
+            serialized[key] = values.map(this.serializeValue);
+        }
+        return serialized;
+    }
+    deserializeMetrics(metrics) {
+        if (!metrics)
+            return {};
+        const deserialized = {};
+        for (const [key, values] of Object.entries(metrics)) {
+            deserialized[key] = values.map(this.deserializeValue);
+        }
+        return deserialized;
+    }
+    getStorageData() {
+        const data = localStorage.getItem(this.storageKey);
+        if (!data)
+            return { metrics: {}, unlockedAchievements: [] };
+        try {
+            const parsed = JSON.parse(data);
+            return {
+                metrics: this.deserializeMetrics(parsed.metrics || {}),
+                unlockedAchievements: parsed.unlockedAchievements || []
+            };
+        }
+        catch (_a) {
+            return { metrics: {}, unlockedAchievements: [] };
+        }
+    }
+    setStorageData(data) {
+        try {
+            const serialized = {
+                metrics: this.serializeMetrics(data.metrics),
+                unlockedAchievements: data.unlockedAchievements
+            };
+            const jsonString = JSON.stringify(serialized);
+            localStorage.setItem(this.storageKey, jsonString);
+        }
+        catch (error) {
+            // Throw proper error instead of silently failing
+            if (error instanceof DOMException &&
+                (error.name === 'QuotaExceededError' ||
+                    error.name === 'NS_ERROR_DOM_QUOTA_REACHED')) {
+                const serialized = {
+                    metrics: this.serializeMetrics(data.metrics),
+                    unlockedAchievements: data.unlockedAchievements
+                };
+                const bytesNeeded = JSON.stringify(serialized).length;
+                throw new StorageQuotaError(bytesNeeded);
+            }
+            if (error instanceof Error) {
+                if (error.message && error.message.includes('QuotaExceeded')) {
+                    const serialized = {
+                        metrics: this.serializeMetrics(data.metrics),
+                        unlockedAchievements: data.unlockedAchievements
+                    };
+                    const bytesNeeded = JSON.stringify(serialized).length;
+                    throw new StorageQuotaError(bytesNeeded);
+                }
+                throw new StorageError(`Failed to save achievement data: ${error.message}`, error);
+            }
+            throw new StorageError('Failed to save achievement data');
+        }
+    }
+    getMetrics() {
+        return this.getStorageData().metrics;
+    }
+    setMetrics(metrics) {
+        const data = this.getStorageData();
+        this.setStorageData(Object.assign(Object.assign({}, data), { metrics }));
+    }
+    getUnlockedAchievements() {
+        return this.getStorageData().unlockedAchievements;
+    }
+    setUnlockedAchievements(achievements) {
+        const data = this.getStorageData();
+        this.setStorageData(Object.assign(Object.assign({}, data), { unlockedAchievements: achievements }));
+    }
+    clear() {
+        localStorage.removeItem(this.storageKey);
+    }
+}
+
+class MemoryStorage {
+    constructor() {
+        this.metrics = {};
+        this.unlockedAchievements = [];
+    }
+    getMetrics() {
+        return this.metrics;
+    }
+    setMetrics(metrics) {
+        this.metrics = metrics;
+    }
+    getUnlockedAchievements() {
+        return this.unlockedAchievements;
+    }
+    setUnlockedAchievements(achievements) {
+        this.unlockedAchievements = achievements;
+    }
+    clear() {
+        this.metrics = {};
+        this.unlockedAchievements = [];
+    }
+}
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+class IndexedDBStorage {
+    constructor(dbName = 'react-achievements') {
+        this.storeName = 'achievements';
+        this.db = null;
+        this.dbName = dbName;
+        this.initPromise = this.initDB();
+    }
+    /**
+     * Initialize IndexedDB database and object store
+     */
+    initDB() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                const request = indexedDB.open(this.dbName, 1);
+                request.onerror = () => {
+                    reject(new StorageError('Failed to open IndexedDB'));
+                };
+                request.onsuccess = () => {
+                    this.db = request.result;
+                    resolve();
+                };
+                request.onupgradeneeded = (event) => {
+                    const db = event.target.result;
+                    // Create object store if it doesn't exist
+                    if (!db.objectStoreNames.contains(this.storeName)) {
+                        db.createObjectStore(this.storeName);
+                    }
+                };
+            });
+        });
+    }
+    /**
+     * Generic get operation from IndexedDB
+     */
+    get(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.initPromise;
+            if (!this.db)
+                throw new StorageError('Database not initialized');
+            return new Promise((resolve, reject) => {
+                const transaction = this.db.transaction([this.storeName], 'readonly');
+                const store = transaction.objectStore(this.storeName);
+                const request = store.get(key);
+                request.onsuccess = () => {
+                    resolve(request.result || null);
+                };
+                request.onerror = () => {
+                    reject(new StorageError(`Failed to read from IndexedDB: ${key}`));
+                };
+                transaction.onerror = () => {
+                    reject(new StorageError(`Transaction failed for key: ${key}`));
+                };
+            });
+        });
+    }
+    /**
+     * Generic set operation to IndexedDB
+     */
+    set(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.initPromise;
+            if (!this.db)
+                throw new StorageError('Database not initialized');
+            return new Promise((resolve, reject) => {
+                const transaction = this.db.transaction([this.storeName], 'readwrite');
+                const store = transaction.objectStore(this.storeName);
+                const request = store.put(value, key);
+                request.onsuccess = () => {
+                    resolve();
+                };
+                request.onerror = () => {
+                    reject(new StorageError(`Failed to write to IndexedDB: ${key}`));
+                };
+                transaction.onerror = () => {
+                    reject(new StorageError(`Transaction failed for key: ${key}`));
+                };
+            });
+        });
+    }
+    /**
+     * Delete operation from IndexedDB
+     */
+    delete(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.initPromise;
+            if (!this.db)
+                throw new StorageError('Database not initialized');
+            return new Promise((resolve, reject) => {
+                const transaction = this.db.transaction([this.storeName], 'readwrite');
+                const store = transaction.objectStore(this.storeName);
+                const request = store.delete(key);
+                request.onsuccess = () => {
+                    resolve();
+                };
+                request.onerror = () => {
+                    reject(new StorageError(`Failed to delete from IndexedDB: ${key}`));
+                };
+                transaction.onerror = () => {
+                    reject(new StorageError(`Transaction failed while deleting key: ${key}`));
+                };
+            });
+        });
+    }
+    getMetrics() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const metrics = yield this.get('metrics');
+            return metrics || {};
+        });
+    }
+    setMetrics(metrics) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.set('metrics', metrics);
+        });
+    }
+    getUnlockedAchievements() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const unlocked = yield this.get('unlocked');
+            return unlocked || [];
+        });
+    }
+    setUnlockedAchievements(achievements) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.set('unlocked', achievements);
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all([
+                this.delete('metrics'),
+                this.delete('unlocked')
+            ]);
+        });
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
+}
+
+class RestApiStorage {
+    constructor(config) {
+        this.config = Object.assign({ timeout: 10000, headers: {} }, config);
+    }
+    /**
+     * Generic fetch wrapper with timeout and error handling
+     */
+    fetchWithTimeout(url, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+            try {
+                const response = yield fetch(url, Object.assign(Object.assign({}, options), { headers: Object.assign(Object.assign({ 'Content-Type': 'application/json' }, this.config.headers), options.headers), signal: controller.signal }));
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new SyncError(`HTTP ${response.status}: ${response.statusText}`, { statusCode: response.status });
+                }
+                return response;
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (error instanceof Error && error.name === 'AbortError') {
+                    throw new SyncError('Request timeout', { timeout: this.config.timeout });
+                }
+                throw error;
+            }
+        });
+    }
+    getMetrics() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const url = `${this.config.baseUrl}/users/${this.config.userId}/achievements/metrics`;
+                const response = yield this.fetchWithTimeout(url, { method: 'GET' });
+                const data = yield response.json();
+                return data.metrics || {};
+            }
+            catch (error) {
+                // Re-throw SyncError and other AchievementErrors (but not StorageError)
+                // Multiple checks for Jest compatibility
+                const err = error;
+                if (((_a = err === null || err === void 0 ? void 0 : err.constructor) === null || _a === void 0 ? void 0 : _a.name) === 'SyncError' || (err === null || err === void 0 ? void 0 : err.name) === 'SyncError') {
+                    throw error;
+                }
+                // Also check instanceof for normal cases
+                if (error instanceof AchievementError && !(error instanceof StorageError)) {
+                    throw error;
+                }
+                throw new StorageError('Failed to fetch metrics from API', error);
+            }
+        });
+    }
+    setMetrics(metrics) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const url = `${this.config.baseUrl}/users/${this.config.userId}/achievements/metrics`;
+                yield this.fetchWithTimeout(url, {
+                    method: 'PUT',
+                    body: JSON.stringify({ metrics })
+                });
+            }
+            catch (error) {
+                const err = error;
+                if (((_a = err === null || err === void 0 ? void 0 : err.constructor) === null || _a === void 0 ? void 0 : _a.name) === 'SyncError' || (err === null || err === void 0 ? void 0 : err.name) === 'SyncError')
+                    throw error;
+                if (error instanceof AchievementError && !(error instanceof StorageError))
+                    throw error;
+                throw new StorageError('Failed to save metrics to API', error);
+            }
+        });
+    }
+    getUnlockedAchievements() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const url = `${this.config.baseUrl}/users/${this.config.userId}/achievements/unlocked`;
+                const response = yield this.fetchWithTimeout(url, { method: 'GET' });
+                const data = yield response.json();
+                return data.unlocked || [];
+            }
+            catch (error) {
+                const err = error;
+                if (((_a = err === null || err === void 0 ? void 0 : err.constructor) === null || _a === void 0 ? void 0 : _a.name) === 'SyncError' || (err === null || err === void 0 ? void 0 : err.name) === 'SyncError')
+                    throw error;
+                if (error instanceof AchievementError && !(error instanceof StorageError))
+                    throw error;
+                throw new StorageError('Failed to fetch unlocked achievements from API', error);
+            }
+        });
+    }
+    setUnlockedAchievements(achievements) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const url = `${this.config.baseUrl}/users/${this.config.userId}/achievements/unlocked`;
+                yield this.fetchWithTimeout(url, {
+                    method: 'PUT',
+                    body: JSON.stringify({ unlocked: achievements })
+                });
+            }
+            catch (error) {
+                const err = error;
+                if (((_a = err === null || err === void 0 ? void 0 : err.constructor) === null || _a === void 0 ? void 0 : _a.name) === 'SyncError' || (err === null || err === void 0 ? void 0 : err.name) === 'SyncError')
+                    throw error;
+                if (error instanceof AchievementError && !(error instanceof StorageError))
+                    throw error;
+                throw new StorageError('Failed to save unlocked achievements to API', error);
+            }
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const url = `${this.config.baseUrl}/users/${this.config.userId}/achievements`;
+                yield this.fetchWithTimeout(url, { method: 'DELETE' });
+            }
+            catch (error) {
+                const err = error;
+                if (((_a = err === null || err === void 0 ? void 0 : err.constructor) === null || _a === void 0 ? void 0 : _a.name) === 'SyncError' || (err === null || err === void 0 ? void 0 : err.name) === 'SyncError')
+                    throw error;
+                if (error instanceof AchievementError && !(error instanceof StorageError))
+                    throw error;
+                throw new StorageError('Failed to clear achievements via API', error);
+            }
+        });
+    }
+}
+
+class AsyncStorageAdapter {
+    constructor(asyncStorage, options) {
+        this.pendingWrites = [];
+        this.asyncStorage = asyncStorage;
+        this.onError = options === null || options === void 0 ? void 0 : options.onError;
+        this.cache = {
+            metrics: {},
+            unlocked: [],
+            loaded: false
+        };
+        // Eagerly load data from async storage (non-blocking)
+        this.initializeCache();
+    }
+    /**
+     * Initialize cache by loading from async storage
+     * This happens in the background during construction
+     */
+    initializeCache() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const [metrics, unlocked] = yield Promise.all([
+                    this.asyncStorage.getMetrics(),
+                    this.asyncStorage.getUnlockedAchievements()
+                ]);
+                this.cache.metrics = metrics;
+                this.cache.unlocked = unlocked;
+                this.cache.loaded = true;
+            }
+            catch (error) {
+                // Handle initialization errors
+                console.error('Failed to initialize async storage:', error);
+                if (this.onError) {
+                    const storageError = error instanceof AchievementError
+                        ? error
+                        : new StorageError('Failed to initialize storage', error);
+                    this.onError(storageError);
+                }
+                // Set to empty state on error
+                this.cache.loaded = true; // Mark as loaded even on error to prevent blocking
+            }
+        });
+    }
+    /**
+     * Wait for cache to be loaded (used internally)
+     * Returns immediately if already loaded, otherwise waits
+     */
+    ensureCacheLoaded() {
+        return __awaiter(this, void 0, void 0, function* () {
+            while (!this.cache.loaded) {
+                yield new Promise(resolve => setTimeout(resolve, 10));
+            }
+        });
+    }
+    /**
+     * SYNC READ: Returns cached metrics immediately
+     * Cache is loaded eagerly during construction
+     */
+    getMetrics() {
+        return this.cache.metrics;
+    }
+    /**
+     * SYNC WRITE: Updates cache immediately, writes to storage in background
+     * Uses optimistic updates - assumes write will succeed
+     */
+    setMetrics(metrics) {
+        // Update cache immediately (optimistic update)
+        this.cache.metrics = metrics;
+        // Write to async storage in background
+        const writePromise = this.asyncStorage.setMetrics(metrics).catch(error => {
+            console.error('Failed to write metrics to async storage:', error);
+            if (this.onError) {
+                const storageError = error instanceof AchievementError
+                    ? error
+                    : new StorageError('Failed to write metrics', error);
+                this.onError(storageError);
+            }
+        });
+        // Track pending write for cleanup/testing
+        this.pendingWrites.push(writePromise);
+    }
+    /**
+     * SYNC READ: Returns cached unlocked achievements immediately
+     */
+    getUnlockedAchievements() {
+        return this.cache.unlocked;
+    }
+    /**
+     * SYNC WRITE: Updates cache immediately, writes to storage in background
+     */
+    setUnlockedAchievements(achievements) {
+        // Update cache immediately (optimistic update)
+        this.cache.unlocked = achievements;
+        // Write to async storage in background
+        const writePromise = this.asyncStorage.setUnlockedAchievements(achievements).catch(error => {
+            console.error('Failed to write unlocked achievements to async storage:', error);
+            if (this.onError) {
+                const storageError = error instanceof AchievementError
+                    ? error
+                    : new StorageError('Failed to write achievements', error);
+                this.onError(storageError);
+            }
+        });
+        // Track pending write
+        this.pendingWrites.push(writePromise);
+    }
+    /**
+     * SYNC CLEAR: Clears cache immediately, clears storage in background
+     */
+    clear() {
+        // Clear cache immediately
+        this.cache.metrics = {};
+        this.cache.unlocked = [];
+        // Clear async storage in background
+        const clearPromise = this.asyncStorage.clear().catch(error => {
+            console.error('Failed to clear async storage:', error);
+            if (this.onError) {
+                const storageError = error instanceof AchievementError
+                    ? error
+                    : new StorageError('Failed to clear storage', error);
+                this.onError(storageError);
+            }
+        });
+        // Track pending write
+        this.pendingWrites.push(clearPromise);
+    }
+    /**
+     * Wait for all pending writes to complete (useful for testing/cleanup)
+     * NOT part of AchievementStorage interface - utility method
+     */
+    flush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all(this.pendingWrites);
+            this.pendingWrites = [];
+        });
+    }
+}
+
+/**
+ * AchievementEngine - Framework-agnostic achievement system
+ * Event-based core with support for multiple storage backends
+ */
+class AchievementEngine extends EventEmitter {
+    constructor(config) {
+        super();
+        this.metrics = {};
+        this.unlockedAchievements = [];
+        this.config = config;
+        // Normalize achievements configuration
+        this.achievements = normalizeAchievements(config.achievements);
+        // Create config hash for export/import validation
+        this.configHash = createConfigHash(config.achievements);
+        // Initialize storage
+        this.storage = this.initializeStorage(config);
+        // Load initial state from storage
+        this.loadFromStorage();
+    }
+    /**
+     * Initialize storage based on configuration
+     */
+    initializeStorage(config) {
+        const { storage, onError, restApiConfig } = config;
+        // If no storage specified, use memory storage
+        if (!storage) {
+            return new MemoryStorage();
+        }
+        // Handle string storage types
+        if (typeof storage === 'string') {
+            switch (storage) {
+                case 'local':
+                    return new LocalStorage('achievements');
+                case 'memory':
+                    return new MemoryStorage();
+                case 'indexeddb': {
+                    const indexedDB = new IndexedDBStorage('achievements-engine');
+                    return new AsyncStorageAdapter(indexedDB, { onError });
+                }
+                case 'restapi': {
+                    if (!restApiConfig) {
+                        throw new Error('restApiConfig is required when using StorageType.RestAPI');
+                    }
+                    const restApi = new RestApiStorage(restApiConfig);
+                    return new AsyncStorageAdapter(restApi, { onError });
+                }
+                default:
+                    throw new Error(`Unsupported storage type: ${storage}`);
+            }
+        }
+        // Handle custom storage instances
+        const storageInstance = storage;
+        if (typeof storageInstance.getMetrics === 'function') {
+            // Check if async storage
+            const testResult = storageInstance.getMetrics();
+            if (testResult && typeof testResult.then === 'function') {
+                return new AsyncStorageAdapter(storageInstance, { onError });
+            }
+            return storageInstance;
+        }
+        throw new Error('Invalid storage configuration');
+    }
+    /**
+     * Load state from storage
+     */
+    loadFromStorage() {
+        try {
+            const savedMetrics = this.storage.getMetrics() || {};
+            const savedUnlocked = this.storage.getUnlockedAchievements() || [];
+            // Convert metrics from array format to simple format
+            Object.entries(savedMetrics).forEach(([key, value]) => {
+                this.metrics[key] = Array.isArray(value) ? value[0] : value;
+            });
+            this.unlockedAchievements = savedUnlocked;
+        }
+        catch (error) {
+            this.handleError(error, 'loadFromStorage');
+        }
+    }
+    /**
+     * Save state to storage
+     */
+    saveToStorage() {
+        try {
+            // Convert metrics to array format for storage
+            const metricsForStorage = {};
+            Object.entries(this.metrics).forEach(([key, value]) => {
+                metricsForStorage[key] = Array.isArray(value) ? value : [value];
+            });
+            this.storage.setMetrics(metricsForStorage);
+            this.storage.setUnlockedAchievements(this.unlockedAchievements);
+        }
+        catch (error) {
+            this.handleError(error, 'saveToStorage');
+        }
+    }
+    /**
+     * Handle errors with optional callback
+     */
+    handleError(error, context) {
+        const errorEvent = {
+            error,
+            context,
+            timestamp: Date.now()
+        };
+        // Emit error event
+        this.emit('error', errorEvent);
+        // Call config error handler if provided
+        if (this.config.onError) {
+            this.config.onError(error);
+        }
+        else {
+            // Fallback to console.error if no error handler provided
+            console.error('[AchievementEngine]', context ? `${context}:` : '', error);
+        }
+    }
+    /**
+     * Emit a custom event and optionally update metrics based on event mapping
+     * @param eventName - Name of the event
+     * @param data - Event data
+     */
+    emit(eventName, data) {
+        // If this is a mapped event, update metrics
+        if (this.config.eventMapping && eventName in this.config.eventMapping) {
+            const mapping = this.config.eventMapping[eventName];
+            if (typeof mapping === 'string') {
+                // Direct mapping: event name -> metric name
+                this.update({ [mapping]: data });
+            }
+            else if (typeof mapping === 'function') {
+                // Custom transformer function
+                const metricsUpdate = mapping(data, Object.assign({}, this.metrics));
+                this.update(metricsUpdate);
+            }
+        }
+        // Emit the event to listeners
+        super.emit(eventName, data);
+    }
+    /**
+     * Update metrics and evaluate achievements
+     * @param newMetrics - Metrics to update
+     */
+    update(newMetrics) {
+        Object.assign({}, this.metrics);
+        // Update metrics
+        Object.entries(newMetrics).forEach(([key, value]) => {
+            const oldValue = this.metrics[key];
+            this.metrics[key] = value;
+            // Emit metric updated event
+            if (oldValue !== value) {
+                const metricEvent = {
+                    metric: key,
+                    oldValue,
+                    newValue: value,
+                    timestamp: Date.now()
+                };
+                super.emit('metric:updated', metricEvent);
+            }
+        });
+        // Evaluate achievements
+        this.evaluateAchievements();
+        // Save to storage
+        this.saveToStorage();
+        // Emit state changed event
+        const stateEvent = {
+            metrics: this.getMetricsAsArray(),
+            unlocked: [...this.unlockedAchievements],
+            timestamp: Date.now()
+        };
+        super.emit('state:changed', stateEvent);
+    }
+    /**
+     * Evaluate all achievements and unlock any newly met conditions
+     * This is the core evaluation logic extracted from AchievementProvider
+     */
+    evaluateAchievements() {
+        const newlyUnlockedAchievements = [];
+        // Convert metrics to array format for condition checking
+        const metricsInArrayFormat = this.getMetricsAsArray();
+        // Iterate through all achievements
+        Object.entries(this.achievements).forEach(([metricName, metricAchievements]) => {
+            metricAchievements.forEach((achievement) => {
+                const state = {
+                    metrics: metricsInArrayFormat,
+                    unlockedAchievements: this.unlockedAchievements
+                };
+                const achievementId = achievement.achievementDetails.achievementId;
+                // Check if already unlocked
+                if (this.unlockedAchievements.includes(achievementId)) {
+                    return;
+                }
+                // Get current value for this metric
+                const currentValue = this.metrics[metricName];
+                // For custom conditions, we always check against all metrics
+                // For threshold-based conditions, we check against the specific metric
+                const shouldCheckAchievement = currentValue !== undefined ||
+                    achievementId.includes('_custom_');
+                if (shouldCheckAchievement) {
+                    const valueToCheck = currentValue;
+                    if (achievement.isConditionMet(valueToCheck, state)) {
+                        newlyUnlockedAchievements.push(achievementId);
+                        // Emit achievement unlocked event
+                        const unlockEvent = {
+                            achievementId,
+                            achievementTitle: achievement.achievementDetails.achievementTitle || 'Achievement Unlocked!',
+                            achievementDescription: achievement.achievementDetails.achievementDescription || '',
+                            achievementIconKey: achievement.achievementDetails.achievementIconKey,
+                            timestamp: Date.now()
+                        };
+                        super.emit('achievement:unlocked', unlockEvent);
+                    }
+                }
+            });
+        });
+        // Add newly unlocked achievements to the list
+        if (newlyUnlockedAchievements.length > 0) {
+            this.unlockedAchievements = [...this.unlockedAchievements, ...newlyUnlockedAchievements];
+        }
+    }
+    /**
+     * Get metrics in array format (for backward compatibility with storage)
+     */
+    getMetricsAsArray() {
+        const metricsInArrayFormat = {};
+        Object.entries(this.metrics).forEach(([key, value]) => {
+            metricsInArrayFormat[key] = Array.isArray(value) ? value : [value];
+        });
+        return metricsInArrayFormat;
+    }
+    /**
+     * Get current metrics (readonly to prevent external modification)
+     */
+    getMetrics() {
+        return Object.freeze(Object.assign({}, this.metrics));
+    }
+    /**
+     * Get unlocked achievement IDs (readonly)
+     */
+    getUnlocked() {
+        return Object.freeze([...this.unlockedAchievements]);
+    }
+    /**
+     * Get all achievements with their unlock status
+     */
+    getAllAchievements() {
+        const result = [];
+        Object.entries(this.achievements).forEach(([_metricName, metricAchievements]) => {
+            metricAchievements.forEach((achievement) => {
+                const { achievementDetails } = achievement;
+                const isUnlocked = this.unlockedAchievements.includes(achievementDetails.achievementId);
+                result.push({
+                    achievementId: achievementDetails.achievementId,
+                    achievementTitle: achievementDetails.achievementTitle || '',
+                    achievementDescription: achievementDetails.achievementDescription || '',
+                    achievementIconKey: achievementDetails.achievementIconKey,
+                    isUnlocked
+                });
+            });
+        });
+        return result;
+    }
+    /**
+     * Reset all achievement data
+     */
+    reset() {
+        this.metrics = {};
+        this.unlockedAchievements = [];
+        try {
+            this.storage.clear();
+        }
+        catch (error) {
+            this.handleError(error, 'reset');
+        }
+        // Emit state changed event
+        const stateEvent = {
+            metrics: {},
+            unlocked: [],
+            timestamp: Date.now()
+        };
+        super.emit('state:changed', stateEvent);
+    }
+    /**
+     * Clean up resources and event listeners
+     */
+    destroy() {
+        this.removeAllListeners();
+    }
+    /**
+     * Export achievement data as JSON string
+     */
+    export() {
+        const metricsInArrayFormat = this.getMetricsAsArray();
+        return exportAchievementData(metricsInArrayFormat, this.unlockedAchievements, this.configHash);
+    }
+    /**
+     * Import achievement data from JSON string
+     * @param jsonString - Exported achievement data
+     * @param options - Import options
+     */
+    import(jsonString, options) {
+        var _a;
+        const metricsInArrayFormat = this.getMetricsAsArray();
+        // Transform options from public API format to internal format
+        const internalOptions = {
+            mergeStrategy: (options === null || options === void 0 ? void 0 : options.merge) ? 'merge' :
+                (options === null || options === void 0 ? void 0 : options.overwrite) ? 'replace' :
+                    'replace',
+            validate: (_a = options === null || options === void 0 ? void 0 : options.validateConfig) !== null && _a !== void 0 ? _a : true,
+            expectedConfigHash: this.configHash
+        };
+        const result = importAchievementData(jsonString, metricsInArrayFormat, this.unlockedAchievements, internalOptions);
+        if (result.success && 'mergedMetrics' in result && 'mergedUnlocked' in result) {
+            // Convert metrics from array format to simple format
+            const mergedMetrics = {};
+            Object.entries(result.mergedMetrics).forEach(([key, value]) => {
+                mergedMetrics[key] = Array.isArray(value) ? value[0] : value;
+            });
+            this.metrics = mergedMetrics;
+            this.unlockedAchievements = result.mergedUnlocked || [];
+            // Save to storage
+            this.saveToStorage();
+            // Emit state changed event
+            const stateEvent = {
+                metrics: this.getMetricsAsArray(),
+                unlocked: [...this.unlockedAchievements],
+                timestamp: Date.now()
+            };
+            super.emit('state:changed', stateEvent);
+        }
+        return result;
+    }
+    /**
+     * Subscribe to engine events
+     * @param event - Event name
+     * @param handler - Event handler
+     */
+    on(event, handler) {
+        return super.on(event, handler);
+    }
+    /**
+     * Subscribe to an event once
+     * @param event - Event name
+     * @param handler - Event handler
+     */
+    once(event, handler) {
+        return super.once(event, handler);
+    }
+    /**
+     * Unsubscribe from an event
+     * @param event - Event name
+     * @param handler - Event handler
+     */
+    off(event, handler) {
+        return super.off(event, handler);
+    }
+}
+
+class OfflineQueueStorage {
+    constructor(innerStorage) {
+        this.queue = [];
+        this.isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
+        this.isSyncing = false;
+        this.queueStorageKey = 'achievements_offline_queue';
+        this.handleOnline = () => {
+            this.isOnline = true;
+            console.log('[OfflineQueue] Back online, processing queue...');
+            this.processQueue();
+        };
+        this.handleOffline = () => {
+            this.isOnline = false;
+            console.log('[OfflineQueue] Offline mode activated');
+        };
+        this.innerStorage = innerStorage;
+        // Load queued operations from localStorage
+        this.loadQueue();
+        // Listen for online/offline events (only in browser environment)
+        if (typeof window !== 'undefined') {
+            window.addEventListener('online', this.handleOnline);
+            window.addEventListener('offline', this.handleOffline);
+        }
+        // Process queue if already online
+        if (this.isOnline) {
+            this.processQueue();
+        }
+    }
+    loadQueue() {
+        try {
+            if (typeof localStorage !== 'undefined') {
+                const queueData = localStorage.getItem(this.queueStorageKey);
+                if (queueData) {
+                    this.queue = JSON.parse(queueData);
+                }
+            }
+        }
+        catch (error) {
+            console.error('Failed to load offline queue:', error);
+            this.queue = [];
+        }
+    }
+    saveQueue() {
+        try {
+            if (typeof localStorage !== 'undefined') {
+                localStorage.setItem(this.queueStorageKey, JSON.stringify(this.queue));
+            }
+        }
+        catch (error) {
+            console.error('Failed to save offline queue:', error);
+        }
+    }
+    processQueue() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isSyncing || this.queue.length === 0 || !this.isOnline) {
+                return;
+            }
+            this.isSyncing = true;
+            try {
+                // Process operations in order
+                while (this.queue.length > 0 && this.isOnline) {
+                    const operation = this.queue[0];
+                    try {
+                        switch (operation.type) {
+                            case 'setMetrics':
+                                yield this.innerStorage.setMetrics(operation.data);
+                                break;
+                            case 'setUnlockedAchievements':
+                                yield this.innerStorage.setUnlockedAchievements(operation.data);
+                                break;
+                            case 'clear':
+                                yield this.innerStorage.clear();
+                                break;
+                        }
+                        // Operation succeeded, remove from queue
+                        this.queue.shift();
+                        this.saveQueue();
+                    }
+                    catch (error) {
+                        console.error('Failed to sync queued operation:', error);
+                        // Stop processing on error, will retry later
+                        break;
+                    }
+                }
+            }
+            finally {
+                this.isSyncing = false;
+            }
+        });
+    }
+    queueOperation(type, data) {
+        const operation = {
+            id: `${Date.now()}_${Math.random()}`,
+            type,
+            data,
+            timestamp: Date.now()
+        };
+        this.queue.push(operation);
+        this.saveQueue();
+        // Try to process queue if online
+        if (this.isOnline) {
+            this.processQueue();
+        }
+    }
+    getMetrics() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Reads always try to hit the server first
+            try {
+                return yield this.innerStorage.getMetrics();
+            }
+            catch (error) {
+                if (!this.isOnline) {
+                    throw new StorageError('Cannot read metrics while offline');
+                }
+                throw error;
+            }
+        });
+    }
+    setMetrics(metrics) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isOnline) {
+                try {
+                    yield this.innerStorage.setMetrics(metrics);
+                    return;
+                }
+                catch (error) {
+                    // Failed while online, queue it
+                    console.warn('Failed to set metrics, queuing for later:', error);
+                }
+            }
+            // Queue operation if offline or if online operation failed
+            this.queueOperation('setMetrics', metrics);
+        });
+    }
+    getUnlockedAchievements() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Reads always try to hit the server first
+            try {
+                return yield this.innerStorage.getUnlockedAchievements();
+            }
+            catch (error) {
+                if (!this.isOnline) {
+                    throw new StorageError('Cannot read achievements while offline');
+                }
+                throw error;
+            }
+        });
+    }
+    setUnlockedAchievements(achievements) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isOnline) {
+                try {
+                    yield this.innerStorage.setUnlockedAchievements(achievements);
+                    return;
+                }
+                catch (error) {
+                    // Failed while online, queue it
+                    console.warn('Failed to set unlocked achievements, queuing for later:', error);
+                }
+            }
+            // Queue operation if offline or if online operation failed
+            this.queueOperation('setUnlockedAchievements', achievements);
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isOnline) {
+                try {
+                    yield this.innerStorage.clear();
+                    // Also clear the queue
+                    this.queue = [];
+                    this.saveQueue();
+                    return;
+                }
+                catch (error) {
+                    console.warn('Failed to clear, queuing for later:', error);
+                }
+            }
+            // Queue operation if offline or if online operation failed
+            this.queueOperation('clear');
+        });
+    }
+    /**
+     * Manually trigger queue processing (useful for testing)
+     */
+    sync() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.processQueue();
+        });
+    }
+    /**
+     * Get current queue status (useful for debugging)
+     */
+    getQueueStatus() {
+        return {
+            pending: this.queue.length,
+            operations: [...this.queue]
+        };
+    }
+    /**
+     * Cleanup listeners (call on unmount)
+     */
+    destroy() {
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('online', this.handleOnline);
+            window.removeEventListener('offline', this.handleOffline);
+        }
+    }
+}
+
+exports.AchievementEngine = AchievementEngine;
+exports.AchievementError = AchievementError;
+exports.AsyncStorageAdapter = AsyncStorageAdapter;
+exports.ConfigurationError = ConfigurationError;
+exports.EventEmitter = EventEmitter;
+exports.ImportValidationError = ImportValidationError;
+exports.IndexedDBStorage = IndexedDBStorage;
+exports.LocalStorage = LocalStorage;
+exports.MemoryStorage = MemoryStorage;
+exports.OfflineQueueStorage = OfflineQueueStorage;
+exports.RestApiStorage = RestApiStorage;
+exports.StorageError = StorageError;
+exports.StorageQuotaError = StorageQuotaError;
+exports.SyncError = SyncError;
+exports.createConfigHash = createConfigHash;
+exports.exportAchievementData = exportAchievementData;
+exports.importAchievementData = importAchievementData;
+exports.isAchievementError = isAchievementError;
+exports.isAsyncStorage = isAsyncStorage;
+exports.isRecoverableError = isRecoverableError;
+exports.normalizeAchievements = normalizeAchievements;
+//# sourceMappingURL=index.cjs.map