react-achievements 3.2.1 → 3.4.0

package/dist/index.js

@@ -8,12 +8,100 @@ import 'react-toastify/dist/ReactToastify.css';
 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';
+}
 var StorageType;
 (function (StorageType) {
     StorageType["Local"] = "local";
     StorageType["Memory"] = "memory";
+    StorageType["IndexedDB"] = "indexeddb";
+    StorageType["RestAPI"] = "restapi"; // Asynchronous REST API storage
 })(StorageType || (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;
@@ -67,17 +155,33 @@ class LocalStorage {
                 metrics: this.serializeMetrics(data.metrics),
                 unlockedAchievements: data.unlockedAchievements
             };
-            localStorage.setItem(this.storageKey, JSON.stringify(serialized));
+            const jsonString = JSON.stringify(serialized);
+            localStorage.setItem(this.storageKey, jsonString);
         }
         catch (error) {
-            // Silently fail on quota exceeded errors
-            if (error instanceof Error &&
+            // Throw proper error instead of silently failing
+            if (error instanceof DOMException &&
                 (error.name === 'QuotaExceededError' ||
-                    error.name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
-                    error.message.includes('QuotaExceeded'))) {
-                return;
+                    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 error;
+            throw new StorageError('Failed to save achievement data');
         }
     }
     getMetrics() {
@@ -122,6 +226,641 @@ class MemoryStorage {
     }
 }
 
+/******************************************************************************
+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 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 = [];
+        });
+    }
+}
+
+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}`));
+                };
+            });
+        });
+    }
+    /**
+     * 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}`));
+                };
+            });
+        });
+    }
+    /**
+     * 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}`));
+                };
+            });
+        });
+    }
+    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')
+            ]);
+        });
+    }
+}
+
+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 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);
+        }
+    }
+}
+
 const getPositionStyles = (position) => {
     const base = {
         position: 'fixed',
@@ -349,8 +1088,219 @@ function normalizeAchievements(config) {
     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 (error) {
+        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;
+}
+
 const AchievementContext = createContext(undefined);
-const AchievementProvider = ({ achievements: achievementsConfig, storage = StorageType.Local, children, icons = {}, }) => {
+const AchievementProvider = ({ achievements: achievementsConfig, storage = StorageType.Local, children, icons = {}, onError, restApiConfig, }) => {
     // Normalize the configuration to the complex format
     const achievements = normalizeAchievements(achievementsConfig);
     const [achievementState, setAchievementState] = useState({
@@ -366,19 +1316,41 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = Stora
     const [currentAchievement, setCurrentAchievement] = useState(null);
     if (!storageRef.current) {
         if (typeof storage === 'string') {
-            if (storage === StorageType.Local) {
-                storageRef.current = new LocalStorage('achievements');
+            // StorageType enum
+            switch (storage) {
+                case StorageType.Local:
+                    storageRef.current = new LocalStorage('achievements');
+                    break;
+                case StorageType.Memory:
+                    storageRef.current = new MemoryStorage();
+                    break;
+                case StorageType.IndexedDB:
+                    // Wrap async storage with adapter
+                    const indexedDB = new IndexedDBStorage('react-achievements');
+                    storageRef.current = new AsyncStorageAdapter(indexedDB, { onError });
+                    break;
+                case StorageType.RestAPI:
+                    if (!restApiConfig) {
+                        throw new ConfigurationError('restApiConfig is required when using StorageType.RestAPI');
+                    }
+                    // Wrap async storage with adapter
+                    const restApi = new RestApiStorage(restApiConfig);
+                    storageRef.current = new AsyncStorageAdapter(restApi, { onError });
+                    break;
+                default:
+                    throw new ConfigurationError(`Unsupported storage type: ${storage}`);
             }
-            else if (storage === StorageType.Memory) {
-                storageRef.current = new MemoryStorage();
+        }
+        else {
+            // Custom storage instance
+            // Check if it's async storage and wrap with adapter
+            if (isAsyncStorage(storage)) {
+                storageRef.current = new AsyncStorageAdapter(storage, { onError });
             }
             else {
-                throw new Error(`Unsupported storage type: ${storage}`);
+                storageRef.current = storage;
             }
         }
-        else {
-            storageRef.current = storage;
-        }
     }
     const storageImpl = storageRef.current;
     const getNotifiedAchievementsKey = () => {
@@ -520,7 +1492,22 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = Stora
         });
         setMetrics(updatedMetrics);
         const storageMetrics = Object.entries(updatedMetrics).reduce((acc, [key, value]) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(value) ? value : [value] })), {});
-        storageImpl.setMetrics(storageMetrics);
+        try {
+            storageImpl.setMetrics(storageMetrics);
+        }
+        catch (error) {
+            if (error instanceof AchievementError) {
+                if (onError) {
+                    onError(error);
+                }
+                else {
+                    console.error('Achievement storage error:', error.message, error.remedy);
+                }
+            }
+            else {
+                console.error('Unexpected error saving metrics:', error);
+            }
+        }
     };
     const reset = () => {
         var _a, _b;
@@ -547,11 +1534,41 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = Stora
             unlocked: achievementState.unlocked,
         };
     };
+    const exportData = () => {
+        const state = getState();
+        const configHash = createConfigHash(achievementsConfig);
+        return exportAchievementData(state.metrics, state.unlocked, configHash);
+    };
+    const importData = (jsonString, options) => {
+        const state = getState();
+        const configHash = createConfigHash(achievementsConfig);
+        const result = importAchievementData(jsonString, state.metrics, state.unlocked, Object.assign(Object.assign({}, options), { expectedConfigHash: configHash }));
+        if (result.success && 'mergedMetrics' in result && 'mergedUnlocked' in result) {
+            // Apply the imported data
+            const mergedResult = result;
+            // Update metrics state
+            const metricsFromArrayFormat = Object.entries(mergedResult.mergedMetrics).reduce((acc, [key, value]) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(value) ? value[0] : value })), {});
+            setMetrics(metricsFromArrayFormat);
+            // Update unlocked achievements state
+            setAchievementState(prev => (Object.assign(Object.assign({}, prev), { unlocked: mergedResult.mergedUnlocked })));
+            // Persist to storage
+            storageImpl.setMetrics(mergedResult.mergedMetrics);
+            storageImpl.setUnlockedAchievements(mergedResult.mergedUnlocked);
+            // Update seen achievements to prevent duplicate notifications
+            mergedResult.mergedUnlocked.forEach(id => {
+                seenAchievementsRef.current.add(id);
+            });
+            saveNotifiedAchievements(seenAchievementsRef.current);
+        }
+        return result;
+    };
     return (React.createElement(AchievementContext.Provider, { value: {
             update,
             achievements: achievementState,
             reset,
             getState,
+            exportData,
+            importData,
         } },
         children,
         React.createElement(ToastContainer, { position: "top-right", autoClose: 5000, hideProgressBar: false, newestOnTop: true, closeOnClick: true, rtl: false, pauseOnFocusLoss: true, draggable: true, pauseOnHover: true, theme: "light" }),
@@ -571,7 +1588,7 @@ const useAchievements = () => {
  * Provides an easier API for common use cases while maintaining access to advanced features.
  */
 const useSimpleAchievements = () => {
-    const { update, achievements, reset, getState } = useAchievements();
+    const { update, achievements, reset, getState, exportData, importData } = useAchievements();
     return {
         /**
          * Track a metric value for achievements
@@ -616,6 +1633,18 @@ const useSimpleAchievements = () => {
          * Get current state (advanced usage)
          */
         getState,
+        /**
+         * Export achievement data to JSON string
+         * @returns JSON string containing all achievement data
+         */
+        exportData,
+        /**
+         * Import achievement data from JSON string
+         * @param jsonString - JSON string containing exported achievement data
+         * @param options - Import options (merge strategy, validation)
+         * @returns Import result with success status and any errors
+         */
+        importData,
     };
 };
 
@@ -982,5 +2011,5 @@ class AchievementBuilder {
     }
 }
 
-export { AchievementBuilder, AchievementContext, AchievementProvider, BadgesButton, BadgesModal, ConfettiWrapper, LocalStorage, MemoryStorage, StorageType, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+export { AchievementBuilder, AchievementContext, AchievementError, AchievementProvider, AsyncStorageAdapter, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, ImportValidationError, IndexedDBStorage, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, StorageError, StorageQuotaError, StorageType, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
 //# sourceMappingURL=index.js.map