achievements-engine 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -1675,6 +1675,276 @@ class OfflineQueueStorage {
     }
 }
 
+/**
+ * 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;
@@ -1695,5 +1965,6 @@ exports.importAchievementData = importAchievementData;
 exports.isAchievementError = isAchievementError;
 exports.isAsyncStorage = isAsyncStorage;
 exports.isRecoverableError = isRecoverableError;
+exports.isSimpleConfig = isSimpleConfig;
 exports.normalizeAchievements = normalizeAchievements;
 //# sourceMappingURL=index.cjs.map