achievements-engine 1.0.0 → 1.1.0

package/dist/index.umd.js

@@ -1679,6 +1679,276 @@
         }
     }
 
+    /**
+     * 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;
+        }
+    }
+
+    exports.AchievementBuilder = AchievementBuilder;
     exports.AchievementEngine = AchievementEngine;
     exports.AchievementError = AchievementError;
     exports.AsyncStorageAdapter = AsyncStorageAdapter;
@@ -1699,6 +1969,7 @@
     exports.isAchievementError = isAchievementError;
     exports.isAsyncStorage = isAsyncStorage;
     exports.isRecoverableError = isRecoverableError;
+    exports.isSimpleConfig = isSimpleConfig;
     exports.normalizeAchievements = normalizeAchievements;
 
 }));