react-achievements 3.2.1 → 3.4.0

package/dist/index.d.ts

@@ -51,6 +51,15 @@ interface AchievementStorage {
     setUnlockedAchievements(achievements: string[]): void;
     clear(): void;
 }
+interface AsyncAchievementStorage {
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+type AnyAchievementStorage = AchievementStorage | AsyncAchievementStorage;
+declare function isAsyncStorage(storage: AnyAchievementStorage): storage is AsyncAchievementStorage;
 interface AchievementContextValue {
     updateMetrics: (metrics: AchievementMetrics | ((prev: AchievementMetrics) => AchievementMetrics)) => void;
     unlockedAchievements: string[];
@@ -84,8 +93,10 @@ interface AchievementProviderProps$1 {
     onAchievementUnlocked?: (achievement: AchievementDetails) => void;
 }
 declare enum StorageType {
-    Local = "local",
-    Memory = "memory"
+    Local = "local",// Synchronous localStorage
+    Memory = "memory",// Synchronous in-memory storage
+    IndexedDB = "indexeddb",// Asynchronous IndexedDB storage
+    RestAPI = "restapi"
 }
 
 declare class LocalStorage implements AchievementStorage {
@@ -115,6 +126,199 @@ declare class MemoryStorage implements AchievementStorage {
     clear(): void;
 }
 
+/**
+ * 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 network sync operations fail
+ */
+declare class SyncError extends AchievementError {
+    readonly statusCode?: number;
+    readonly timeout?: number;
+    constructor(message: string, details?: {
+        statusCode?: number;
+        timeout?: number;
+    });
+}
+/**
+ * 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;
+
+declare class AsyncStorageAdapter implements AchievementStorage {
+    private asyncStorage;
+    private cache;
+    private pendingWrites;
+    private onError?;
+    constructor(asyncStorage: AsyncAchievementStorage, options?: {
+        onError?: (error: AchievementError) => void;
+    });
+    /**
+     * Initialize cache by loading from async storage
+     * This happens in the background during construction
+     */
+    private initializeCache;
+    /**
+     * Wait for cache to be loaded (used internally)
+     * Returns immediately if already loaded, otherwise waits
+     */
+    private ensureCacheLoaded;
+    /**
+     * SYNC READ: Returns cached metrics immediately
+     * Cache is loaded eagerly during construction
+     */
+    getMetrics(): AchievementMetrics;
+    /**
+     * SYNC WRITE: Updates cache immediately, writes to storage in background
+     * Uses optimistic updates - assumes write will succeed
+     */
+    setMetrics(metrics: AchievementMetrics): void;
+    /**
+     * SYNC READ: Returns cached unlocked achievements immediately
+     */
+    getUnlockedAchievements(): string[];
+    /**
+     * SYNC WRITE: Updates cache immediately, writes to storage in background
+     */
+    setUnlockedAchievements(achievements: string[]): void;
+    /**
+     * SYNC CLEAR: Clears cache immediately, clears storage in background
+     */
+    clear(): void;
+    /**
+     * Wait for all pending writes to complete (useful for testing/cleanup)
+     * NOT part of AchievementStorage interface - utility method
+     */
+    flush(): Promise<void>;
+}
+
+declare class IndexedDBStorage implements AsyncAchievementStorage {
+    private dbName;
+    private storeName;
+    private db;
+    private initPromise;
+    constructor(dbName?: string);
+    /**
+     * Initialize IndexedDB database and object store
+     */
+    private initDB;
+    /**
+     * Generic get operation from IndexedDB
+     */
+    private get;
+    /**
+     * Generic set operation to IndexedDB
+     */
+    private set;
+    /**
+     * Delete operation from IndexedDB
+     */
+    private delete;
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+interface RestApiStorageConfig {
+    baseUrl: string;
+    userId: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+declare class RestApiStorage implements AsyncAchievementStorage {
+    private config;
+    constructor(config: RestApiStorageConfig);
+    /**
+     * Generic fetch wrapper with timeout and error handling
+     */
+    private fetchWithTimeout;
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+interface QueuedOperation {
+    id: string;
+    type: 'setMetrics' | 'setUnlockedAchievements' | 'clear';
+    data?: any;
+    timestamp: number;
+}
+declare class OfflineQueueStorage implements AsyncAchievementStorage {
+    private innerStorage;
+    private queue;
+    private isOnline;
+    private isSyncing;
+    private queueStorageKey;
+    constructor(innerStorage: AsyncAchievementStorage);
+    private loadQueue;
+    private saveQueue;
+    private handleOnline;
+    private handleOffline;
+    private processQueue;
+    private queueOperation;
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Manually trigger queue processing (useful for testing)
+     */
+    sync(): Promise<void>;
+    /**
+     * Get current queue status (useful for debugging)
+     */
+    getQueueStatus(): {
+        pending: number;
+        operations: QueuedOperation[];
+    };
+    /**
+     * Cleanup listeners (call on unmount)
+     */
+    destroy(): void;
+}
+
 interface BadgesButtonProps {
     onClick: () => void;
     position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -137,6 +341,56 @@ 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;
+
 interface AchievementContextType {
     update: (metrics: Record<string, any>) => void;
     achievements: {
@@ -148,13 +402,17 @@ interface AchievementContextType {
         metrics: AchievementMetrics;
         unlocked: string[];
     };
+    exportData: () => string;
+    importData: (jsonString: string, options?: ImportOptions) => ImportResult;
 }
 declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
 interface AchievementProviderProps {
     achievements: AchievementConfigurationType;
-    storage?: AchievementStorage | StorageType;
+    storage?: AchievementStorage | AsyncAchievementStorage | StorageType;
     children: React$1.ReactNode;
     icons?: Record<string, string>;
+    onError?: (error: AchievementError) => void;
+    restApiConfig?: RestApiStorageConfig;
 }
 declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
 
@@ -205,6 +463,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 +625,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, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };