react-achievements 3.2.1 → 3.3.0

package/dist/index.d.ts

@@ -137,6 +137,108 @@ interface ConfettiWrapperProps {
 }
 declare const ConfettiWrapper: React$1.FC<ConfettiWrapperProps>;
 
+/**
+ * Options for importing achievement data
+ */
+interface ImportOptions {
+    /** Strategy for merging imported data with existing data */
+    mergeStrategy?: 'replace' | 'merge' | 'preserve';
+    /** Whether to validate the imported data */
+    validate?: boolean;
+    /** Optional config hash to validate against */
+    expectedConfigHash?: string;
+}
+/**
+ * Result of an import operation
+ */
+interface ImportResult {
+    success: boolean;
+    imported: {
+        metrics: number;
+        achievements: number;
+    };
+    errors?: string[];
+    warnings?: string[];
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function importAchievementData(jsonString: string, currentMetrics: AchievementMetrics, currentUnlocked: string[], options?: ImportOptions): ImportResult;
+
+/**
+ * Base error class for all achievement-related errors
+ */
+declare class AchievementError extends Error {
+    code: string;
+    recoverable: boolean;
+    remedy?: string | undefined;
+    constructor(message: string, code: string, recoverable: boolean, remedy?: string | undefined);
+}
+/**
+ * Error thrown when browser storage quota is exceeded
+ */
+declare class StorageQuotaError extends AchievementError {
+    bytesNeeded: number;
+    constructor(bytesNeeded: number);
+}
+/**
+ * Error thrown when imported data fails validation
+ */
+declare class ImportValidationError extends AchievementError {
+    validationErrors: string[];
+    constructor(validationErrors: string[]);
+}
+/**
+ * Error thrown when storage operations fail
+ */
+declare class StorageError extends AchievementError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Error thrown when configuration is invalid
+ */
+declare class ConfigurationError extends AchievementError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when sync operations fail (for async storage backends)
+ */
+declare class SyncError extends AchievementError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Type guard to check if an error is an AchievementError
+ */
+declare function isAchievementError(error: unknown): error is AchievementError;
+/**
+ * Type guard to check if an error is recoverable
+ */
+declare function isRecoverableError(error: unknown): boolean;
+
 interface AchievementContextType {
     update: (metrics: Record<string, any>) => void;
     achievements: {
@@ -148,6 +250,8 @@ interface AchievementContextType {
         metrics: AchievementMetrics;
         unlocked: string[];
     };
+    exportData: () => string;
+    importData: (jsonString: string, options?: ImportOptions) => ImportResult;
 }
 declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
 interface AchievementProviderProps {
@@ -155,6 +259,7 @@ interface AchievementProviderProps {
     storage?: AchievementStorage | StorageType;
     children: React$1.ReactNode;
     icons?: Record<string, string>;
+    onError?: (error: AchievementError) => void;
 }
 declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
 
@@ -205,6 +310,18 @@ declare const useSimpleAchievements: () => {
         metrics: AchievementMetrics;
         unlocked: string[];
     };
+    /**
+     * Export achievement data to JSON string
+     * @returns JSON string containing all achievement data
+     */
+    exportData: () => string;
+    /**
+     * 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: (jsonString: string, options?: ImportOptions) => ImportResult;
 };
 
 declare const defaultStyles: Required<StylesProps>;
@@ -355,4 +472,38 @@ declare class AchievementBuilder {
     static combine(achievements: (SimpleAchievementConfig | Achievement)[]): SimpleAchievementConfig;
 }
 
-export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, CustomAchievementDetails, InitialAchievementMetrics, LocalStorage, MemoryStorage, SimpleAchievementConfig, SimpleAchievementDetails, StorageType, StylesProps, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+/**
+ * Structure of exported achievement data
+ */
+interface ExportedData {
+    version: string;
+    timestamp: number;
+    metrics: AchievementMetrics;
+    unlockedAchievements: string[];
+    configHash?: string;
+}
+/**
+ * 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
+ * ```
+ */
+declare function exportAchievementData(metrics: AchievementMetrics, unlocked: string[], configHash?: string): string;
+/**
+ * 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
+ */
+declare function createConfigHash(config: any): string;
+
+export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, InitialAchievementMetrics, LocalStorage, MemoryStorage, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };

package/dist/index.js

@@ -14,6 +14,84 @@ var StorageType;
     StorageType["Memory"] = "memory";
 })(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 sync operations fail (for async storage backends)
+ */
+class SyncError extends AchievementError {
+    constructor(message, originalError) {
+        super(message, 'SYNC_ERROR', true, 'Check your network connection and backend server status. The operation will be retried automatically.');
+        this.originalError = originalError;
+        this.name = 'SyncError';
+    }
+}
+/**
+ * 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 +145,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() {
@@ -349,8 +443,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, }) => {
     // Normalize the configuration to the complex format
     const achievements = normalizeAchievements(achievementsConfig);
     const [achievementState, setAchievementState] = useState({
@@ -520,7 +825,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 +867,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 +921,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 +966,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 +1344,5 @@ class AchievementBuilder {
     }
 }
 
-export { AchievementBuilder, AchievementContext, AchievementProvider, BadgesButton, BadgesModal, ConfettiWrapper, LocalStorage, MemoryStorage, StorageType, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+export { AchievementBuilder, AchievementContext, AchievementError, AchievementProvider, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, ImportValidationError, LocalStorage, MemoryStorage, StorageError, StorageQuotaError, StorageType, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
 //# sourceMappingURL=index.js.map