achievements-engine 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -226,6 +226,14 @@ interface ImportResult$1 {
     mergedMetrics?: AchievementMetrics;
     mergedUnlocked?: string[];
 }
+/**
+ * Helper interface for cleaner achievement award definitions
+ */
+interface AwardDetails {
+    title?: string;
+    description?: string;
+    icon?: string;
+}
 /**
  * Public API surface of the AchievementEngine
  * This type represents the stable, supported API for external consumers
@@ -272,7 +280,7 @@ declare class AchievementEngine extends EventEmitter {
      * Update metrics and evaluate achievements
      * @param newMetrics - Metrics to update
      */
-    update(newMetrics: Record<string, any>): void;
+    update<T extends Record<string, any>>(newMetrics: Partial<T>): void;
     /**
      * Evaluate all achievements and unlock any newly met conditions
      * This is the core evaluation logic extracted from AchievementProvider
@@ -285,7 +293,7 @@ declare class AchievementEngine extends EventEmitter {
     /**
      * Get current metrics (readonly to prevent external modification)
      */
-    getMetrics(): Readonly<Record<string, any>>;
+    getMetrics<T extends Record<string, any>>(): Readonly<Partial<T>>;
     /**
      * Get unlocked achievement IDs (readonly)
      */
@@ -556,8 +564,19 @@ declare class OfflineQueueStorage implements AsyncAchievementStorage {
     destroy(): void;
 }
 
+declare function isSimpleConfig(config: AchievementConfigurationType): config is SimpleAchievementConfig;
 declare function normalizeAchievements(config: AchievementConfigurationType): AchievementConfiguration;
 
+/**
+ * Structure of exported achievement data
+ */
+interface ExportedData {
+    version: string;
+    timestamp: number;
+    metrics: AchievementMetrics;
+    unlockedAchievements: string[];
+    configHash?: string;
+}
 /**
  * Exports achievement data to a JSON string
  *
@@ -632,4 +651,125 @@ interface ImportResult {
  */
 declare function importAchievementData(jsonString: string, currentMetrics: AchievementMetrics, currentUnlocked: string[], options?: ImportOptions): ImportResult;
 
-export { AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementDetails, AchievementEngine, AchievementEngineApi, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementState, AchievementStorage, AchievementUnlockedEvent, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, ConfigurationError, CustomAchievementDetails, EngineConfig, EngineEvent, ErrorEvent, EventEmitter, EventHandler, EventMapping, ImportOptions$1 as ImportOptions, ImportResult$1 as ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, MetricUpdatedEvent, MetricUpdater, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig$1 as RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StateChangedEvent, StorageError, StorageQuotaError, StorageType, SyncError, UnsubscribeFn, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, normalizeAchievements };
+/**
+ * Base class for chainable achievement configuration (Tier 2)
+ */
+declare abstract class Achievement {
+    protected metric: string;
+    protected award: AwardDetails;
+    constructor(metric: string, defaultAward: AwardDetails);
+    /**
+     * Customize the award details for this achievement
+     * @param award - Custom award details
+     * @returns This achievement for chaining
+     */
+    withAward(award: AwardDetails): Achievement;
+    /**
+     * Convert this achievement to a SimpleAchievementConfig
+     */
+    abstract toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Threshold-based achievement (score, level, etc.)
+ */
+declare class ThresholdAchievement extends Achievement {
+    private threshold;
+    constructor(metric: string, threshold: number, defaultAward: AwardDetails);
+    toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Boolean achievement (tutorial completion, first login, etc.)
+ */
+declare class BooleanAchievement extends Achievement {
+    toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Value-based achievement (character class, difficulty, etc.)
+ */
+declare class ValueAchievement extends Achievement {
+    private value;
+    constructor(metric: string, value: string, defaultAward: AwardDetails);
+    toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Complex achievement builder for power users (Tier 3)
+ */
+declare class ComplexAchievementBuilder {
+    private metric;
+    private condition;
+    private award;
+    /**
+     * Set the metric this achievement tracks
+     */
+    withMetric(metric: string): ComplexAchievementBuilder;
+    /**
+     * Set the condition function that determines if achievement is unlocked
+     */
+    withCondition(fn: (metrics: Record<string, any>) => boolean): ComplexAchievementBuilder;
+    /**
+     * Set the award details for this achievement
+     */
+    withAward(award: AwardDetails): ComplexAchievementBuilder;
+    /**
+     * Build the final achievement configuration
+     */
+    build(): SimpleAchievementConfig;
+}
+/**
+ * Main AchievementBuilder with three-tier API
+ * Tier 1: Simple static methods with smart defaults
+ * Tier 2: Chainable customization
+ * Tier 3: Full builder for complex logic
+ */
+declare class AchievementBuilder {
+    /**
+     * Create a single score achievement with smart defaults
+     * @param threshold - Score threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createScoreAchievement(threshold: number): ThresholdAchievement;
+    /**
+     * Create multiple score achievements
+     * @param thresholds - Array of thresholds or [threshold, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createScoreAchievements(thresholds: (number | [number, AwardDetails])[]): SimpleAchievementConfig;
+    /**
+     * Create a single level achievement with smart defaults
+     * @param level - Level threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createLevelAchievement(level: number): ThresholdAchievement;
+    /**
+     * Create multiple level achievements
+     * @param levels - Array of levels or [level, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createLevelAchievements(levels: (number | [number, AwardDetails])[]): SimpleAchievementConfig;
+    /**
+     * Create a boolean achievement with smart defaults
+     * @param metric - The metric name (e.g., 'completedTutorial')
+     * @returns Chainable BooleanAchievement
+     */
+    static createBooleanAchievement(metric: string): BooleanAchievement;
+    /**
+     * Create a value-based achievement with smart defaults
+     * @param metric - The metric name (e.g., 'characterClass')
+     * @param value - The value to match (e.g., 'wizard')
+     * @returns Chainable ValueAchievement
+     */
+    static createValueAchievement(metric: string, value: string): ValueAchievement;
+    /**
+     * Create a complex achievement builder for power users
+     * @returns ComplexAchievementBuilder for full control
+     */
+    static create(): ComplexAchievementBuilder;
+    /**
+     * Combine multiple achievement configurations
+     * @param achievements - Array of SimpleAchievementConfig objects or Achievement instances
+     * @returns Combined SimpleAchievementConfig
+     */
+    static combine(achievements: (SimpleAchievementConfig | Achievement)[]): SimpleAchievementConfig;
+}
+
+export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementDetails, AchievementEngine, AchievementEngineApi, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementState, AchievementStorage, AchievementUnlockedEvent, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, ConfigurationError, CustomAchievementDetails, EngineConfig, EngineEvent, ErrorEvent, EventEmitter, EventHandler, EventMapping, ExportedData, ImportOptions$1 as ImportOptions, ImportResult$1 as ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, MetricUpdatedEvent, MetricUpdater, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig$1 as RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StateChangedEvent, StorageError, StorageQuotaError, StorageType, SyncError, UnsubscribeFn, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements };

package/dist/index.esm.js

@@ -1673,5 +1673,274 @@ class OfflineQueueStorage {
     }
 }
 
-export { AchievementEngine, AchievementError, AsyncStorageAdapter, ConfigurationError, EventEmitter, ImportValidationError, IndexedDBStorage, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, StorageError, StorageQuotaError, StorageType, SyncError, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, normalizeAchievements };
+/**
+ * Base class for chainable achievement configuration (Tier 2)
+ */
+class Achievement {
+    constructor(metric, defaultAward) {
+        this.metric = metric;
+        this.award = defaultAward;
+    }
+    /**
+     * Customize the award details for this achievement
+     * @param award - Custom award details
+     * @returns This achievement for chaining
+     */
+    withAward(award) {
+        this.award = Object.assign(Object.assign({}, this.award), award);
+        return this;
+    }
+}
+/**
+ * Threshold-based achievement (score, level, etc.)
+ */
+class ThresholdAchievement extends Achievement {
+    constructor(metric, threshold, defaultAward) {
+        super(metric, defaultAward);
+        this.threshold = threshold;
+    }
+    toConfig() {
+        return {
+            [this.metric]: {
+                [this.threshold]: {
+                    title: this.award.title,
+                    description: this.award.description,
+                    icon: this.award.icon
+                }
+            }
+        };
+    }
+}
+/**
+ * Boolean achievement (tutorial completion, first login, etc.)
+ */
+class BooleanAchievement extends Achievement {
+    toConfig() {
+        return {
+            [this.metric]: {
+                true: {
+                    title: this.award.title,
+                    description: this.award.description,
+                    icon: this.award.icon
+                }
+            }
+        };
+    }
+}
+/**
+ * Value-based achievement (character class, difficulty, etc.)
+ */
+class ValueAchievement extends Achievement {
+    constructor(metric, value, defaultAward) {
+        super(metric, defaultAward);
+        this.value = value;
+    }
+    toConfig() {
+        return {
+            [this.metric]: {
+                [this.value]: {
+                    title: this.award.title,
+                    description: this.award.description,
+                    icon: this.award.icon
+                }
+            }
+        };
+    }
+}
+/**
+ * Complex achievement builder for power users (Tier 3)
+ */
+class ComplexAchievementBuilder {
+    constructor() {
+        this.metric = '';
+        this.condition = null;
+        this.award = {};
+    }
+    /**
+     * Set the metric this achievement tracks
+     */
+    withMetric(metric) {
+        this.metric = metric;
+        return this;
+    }
+    /**
+     * Set the condition function that determines if achievement is unlocked
+     */
+    withCondition(fn) {
+        this.condition = fn;
+        return this;
+    }
+    /**
+     * Set the award details for this achievement
+     */
+    withAward(award) {
+        this.award = Object.assign(Object.assign({}, this.award), award);
+        return this;
+    }
+    /**
+     * Build the final achievement configuration
+     */
+    build() {
+        if (!this.metric || !this.condition) {
+            throw new Error('Complex achievement requires metric and condition');
+        }
+        return {
+            [this.metric]: {
+                custom: {
+                    title: this.award.title || this.metric,
+                    description: this.award.description || `Achieve ${this.award.title || this.metric}`,
+                    icon: this.award.icon || '💎',
+                    condition: this.condition
+                }
+            }
+        };
+    }
+}
+/**
+ * Main AchievementBuilder with three-tier API
+ * Tier 1: Simple static methods with smart defaults
+ * Tier 2: Chainable customization
+ * Tier 3: Full builder for complex logic
+ */
+class AchievementBuilder {
+    // TIER 1: Simple Static Methods (90% of use cases)
+    /**
+     * Create a single score achievement with smart defaults
+     * @param threshold - Score threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createScoreAchievement(threshold) {
+        return new ThresholdAchievement('score', threshold, {
+            title: `Score ${threshold}!`,
+            description: `Score ${threshold} points`,
+            icon: '🏆'
+        });
+    }
+    /**
+     * Create multiple score achievements
+     * @param thresholds - Array of thresholds or [threshold, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createScoreAchievements(thresholds) {
+        const config = { score: {} };
+        thresholds.forEach(item => {
+            if (typeof item === 'number') {
+                // Use default award
+                config.score[item] = {
+                    title: `Score ${item}!`,
+                    description: `Score ${item} points`,
+                    icon: '🏆'
+                };
+            }
+            else {
+                // Custom award
+                const [threshold, award] = item;
+                config.score[threshold] = {
+                    title: award.title || `Score ${threshold}!`,
+                    description: award.description || `Score ${threshold} points`,
+                    icon: award.icon || '🏆'
+                };
+            }
+        });
+        return config;
+    }
+    /**
+     * Create a single level achievement with smart defaults
+     * @param level - Level threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createLevelAchievement(level) {
+        return new ThresholdAchievement('level', level, {
+            title: `Level ${level}!`,
+            description: `Reach level ${level}`,
+            icon: '📈'
+        });
+    }
+    /**
+     * Create multiple level achievements
+     * @param levels - Array of levels or [level, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createLevelAchievements(levels) {
+        const config = { level: {} };
+        levels.forEach(item => {
+            if (typeof item === 'number') {
+                // Use default award
+                config.level[item] = {
+                    title: `Level ${item}!`,
+                    description: `Reach level ${item}`,
+                    icon: '📈'
+                };
+            }
+            else {
+                // Custom award
+                const [level, award] = item;
+                config.level[level] = {
+                    title: award.title || `Level ${level}!`,
+                    description: award.description || `Reach level ${level}`,
+                    icon: award.icon || '📈'
+                };
+            }
+        });
+        return config;
+    }
+    /**
+     * Create a boolean achievement with smart defaults
+     * @param metric - The metric name (e.g., 'completedTutorial')
+     * @returns Chainable BooleanAchievement
+     */
+    static createBooleanAchievement(metric) {
+        // Convert camelCase to Title Case
+        const formattedMetric = metric.replace(/([A-Z])/g, ' $1').toLowerCase();
+        const titleCase = formattedMetric.charAt(0).toUpperCase() + formattedMetric.slice(1);
+        return new BooleanAchievement(metric, {
+            title: `${titleCase}!`,
+            description: `Complete ${formattedMetric}`,
+            icon: '✅'
+        });
+    }
+    /**
+     * Create a value-based achievement with smart defaults
+     * @param metric - The metric name (e.g., 'characterClass')
+     * @param value - The value to match (e.g., 'wizard')
+     * @returns Chainable ValueAchievement
+     */
+    static createValueAchievement(metric, value) {
+        const formattedValue = value.charAt(0).toUpperCase() + value.slice(1);
+        return new ValueAchievement(metric, value, {
+            title: `${formattedValue}!`,
+            description: `Choose ${formattedValue.toLowerCase()} for ${metric}`,
+            icon: '🎯'
+        });
+    }
+    // TIER 3: Full Builder for Complex Logic
+    /**
+     * Create a complex achievement builder for power users
+     * @returns ComplexAchievementBuilder for full control
+     */
+    static create() {
+        return new ComplexAchievementBuilder();
+    }
+    // UTILITY METHODS
+    /**
+     * Combine multiple achievement configurations
+     * @param achievements - Array of SimpleAchievementConfig objects or Achievement instances
+     * @returns Combined SimpleAchievementConfig
+     */
+    static combine(achievements) {
+        const combined = {};
+        achievements.forEach(achievement => {
+            const config = achievement instanceof Achievement ? achievement.toConfig() : achievement;
+            Object.keys(config).forEach(key => {
+                if (!combined[key]) {
+                    combined[key] = {};
+                }
+                Object.assign(combined[key], config[key]);
+            });
+        });
+        return combined;
+    }
+}
+
+export { AchievementBuilder, AchievementEngine, AchievementError, AsyncStorageAdapter, ConfigurationError, EventEmitter, ImportValidationError, IndexedDBStorage, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, StorageError, StorageQuotaError, StorageType, SyncError, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements };
 //# sourceMappingURL=index.esm.js.map