react-achievements 4.4.1 → 5.0.0

package/dist/index.cjs

@@ -47,6 +47,16 @@ function __rest(s, e) {
     return t;
 }
 
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
 typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
@@ -68,18 +78,74 @@ const AchievementContext = React.createContext(undefined);
 const getAllAchievementRecord = (achievements) => {
     return Object.fromEntries(achievements.map((achievement) => [achievement.achievementId, achievement]));
 };
-const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'local', children, onError, useBuiltInUI, restApiConfig, engine: externalEngine, eventMapping, icons = {}, }) => {
+const emptySnapshot = () => ({
+    metrics: {},
+    unlockedIds: [],
+    unlockedAchievements: [],
+    allAchievements: [],
+    unlockedCount: 0,
+    totalCount: 0,
+});
+const normalizeAchievementDto = (achievement) => {
+    const source = achievement;
+    const achievementId = source.id || source.achievementId || '';
+    const achievementTitle = source.title || source.achievementTitle || achievementId;
+    const achievementDescription = source.description || source.achievementDescription || '';
+    const achievementIconKey = source.iconKey || source.icon || source.achievementIconKey;
+    return {
+        achievementId,
+        achievementTitle,
+        achievementDescription,
+        achievementIconKey,
+        confetti: source.confetti,
+        isUnlocked: Boolean(source.isUnlocked),
+        unlockedAt: source.unlockedAt,
+        progress: source.progress,
+        metadata: source.metadata,
+    };
+};
+const normalizeClientSnapshot = (snapshot) => {
+    var _a, _b, _c;
+    const allAchievements = (snapshot.achievements || []).map(normalizeAchievementDto);
+    const unlockedIds = snapshot.unlockedIds ||
+        allAchievements
+            .filter((achievement) => achievement.isUnlocked)
+            .map((achievement) => achievement.achievementId);
+    const unlockedIdSet = new Set(unlockedIds);
+    const unlockedAchievements = ((_a = snapshot.unlockedAchievements) === null || _a === void 0 ? void 0 : _a.length)
+        ? snapshot.unlockedAchievements.map(normalizeAchievementDto)
+        : allAchievements.filter((achievement) => unlockedIdSet.has(achievement.achievementId));
+    return {
+        metrics: Object.assign({}, (snapshot.metrics || {})),
+        unlockedIds,
+        unlockedAchievements,
+        allAchievements,
+        unlockedCount: (_b = snapshot.unlockedCount) !== null && _b !== void 0 ? _b : unlockedAchievements.length,
+        totalCount: (_c = snapshot.totalCount) !== null && _c !== void 0 ? _c : allAchievements.length,
+    };
+};
+const toError = (unknownError, fallbackMessage) => (unknownError instanceof Error ? unknownError : new Error(fallbackMessage));
+const AchievementProvider$1 = ({ client, achievements: achievementsConfig, storage = 'local', children, onError, useBuiltInUI, restApiConfig, engine: externalEngine, eventMapping, icons = {}, }) => {
     if (useBuiltInUI !== undefined) {
         warnDeprecation('`useBuiltInUI` is deprecated and is now a no-op because built-in UI is the default. It will be removed in 5.0.');
     }
+    if (client && (achievementsConfig || externalEngine)) {
+        throw new Error('Cannot provide "client" with "achievements" or "engine" props to AchievementProvider.\n\n' +
+            'Use one pattern:\n' +
+            '1. Server-backed display: <AchievementProvider client={achievementClient}>\n' +
+            '2. Legacy in-browser engine: <AchievementProvider achievements={config}>');
+    }
     if (achievementsConfig && externalEngine) {
         throw new Error('Cannot provide both "achievements" and "engine" props to AchievementProvider.\n\n' +
             'Choose one pattern:\n' +
             '1. Direct metric tracking: <AchievementProvider achievements={config}>\n' +
             '2. Event-based tracking: <AchievementProvider engine={myEngine}>');
     }
-    const isProviderCreatedEngine = Boolean(achievementsConfig);
+    const isProviderCreatedEngine = Boolean(achievementsConfig) && !client;
     const [engine] = React.useState(() => {
+        if (client) {
+            return undefined;
+        }
         if (externalEngine) {
             return externalEngine;
         }
@@ -96,18 +162,63 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
             eventMapping,
         });
     });
-    const [achievementSnapshot, setAchievementSnapshot] = React.useState(() => engine.getSnapshot());
+    const [achievementSnapshot, setAchievementSnapshot] = React.useState(() => engine ? engine.getSnapshot() : emptySnapshot());
+    const [recentlyUnlocked, setRecentlyUnlocked] = React.useState([]);
+    const [isLoading, setIsLoading] = React.useState(Boolean(client));
+    const [error, setError] = React.useState(null);
     const syncAchievementState = React.useCallback((snapshot) => {
-        setAchievementSnapshot(snapshot || engine.getSnapshot());
+        if (snapshot) {
+            setAchievementSnapshot(snapshot);
+            return;
+        }
+        if (engine) {
+            setAchievementSnapshot(engine.getSnapshot());
+        }
     }, [engine]);
+    const applyClientMutationResult = React.useCallback((result) => {
+        setRecentlyUnlocked((result.newlyUnlocked || []).map(normalizeAchievementDto));
+        const normalizedSnapshot = normalizeClientSnapshot(result.snapshot);
+        setAchievementSnapshot(normalizedSnapshot);
+        return result;
+    }, []);
+    const refresh = React.useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
+        if (!client) {
+            const snapshot = engine ? engine.getSnapshot() : emptySnapshot();
+            setAchievementSnapshot(snapshot);
+            return snapshot;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const snapshot = normalizeClientSnapshot(yield client.getSnapshot());
+            setAchievementSnapshot(snapshot);
+            return snapshot;
+        }
+        catch (unknownError) {
+            const nextError = toError(unknownError, 'Failed to load achievements');
+            setError(nextError);
+            throw nextError;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }), [client, engine]);
+    const handleClientMutationFailure = React.useCallback((unknownError) => {
+        const nextError = toError(unknownError, 'Failed to update achievements');
+        setError(nextError);
+        throw nextError;
+    }, []);
     React.useEffect(() => {
         return () => {
-            if (!externalEngine) {
+            if (engine && !externalEngine) {
                 engine.destroy();
             }
         };
     }, [engine, externalEngine]);
     React.useEffect(() => {
+        if (!engine) {
+            return;
+        }
         let isMounted = true;
         const unsubscribeStateChanged = engine.on('state:changed', (event) => {
             syncAchievementState(event);
@@ -122,29 +233,84 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
             unsubscribeStateChanged();
         };
     }, [engine, syncAchievementState]);
+    React.useEffect(() => {
+        if (!client) {
+            return;
+        }
+        refresh().catch(() => {
+        });
+        return () => {
+        };
+    }, [client, refresh]);
     const update = (newMetrics) => {
-        engine.update(newMetrics);
+        if (client) {
+            setError(null);
+            const mutation = client.trackMany
+                ? client.trackMany(newMetrics)
+                : Promise.all(Object.entries(newMetrics).map(([metric, value]) => client.track(metric, value))).then((results) => results[results.length - 1]);
+            return mutation.then((result) => {
+                if (result) {
+                    applyClientMutationResult(result);
+                }
+                return result;
+            }).catch(handleClientMutationFailure);
+        }
+        return engine === null || engine === void 0 ? void 0 : engine.update(newMetrics);
+    };
+    const increment = (metric, amount = 1) => {
+        if (client) {
+            setError(null);
+            return client.increment(metric, amount)
+                .then(applyClientMutationResult)
+                .catch(handleClientMutationFailure);
+        }
+        return engine === null || engine === void 0 ? void 0 : engine.increment(metric, amount);
+    };
+    const event = (name, payload) => {
+        if (client) {
+            setError(null);
+            return client.event(name, payload)
+                .then(applyClientMutationResult)
+                .catch(handleClientMutationFailure);
+        }
+        engine === null || engine === void 0 ? void 0 : engine.emit(name, payload);
     };
     const reset = () => {
-        engine.reset();
+        if (client === null || client === void 0 ? void 0 : client.reset) {
+            setError(null);
+            return client.reset().then((snapshot) => {
+                setRecentlyUnlocked([]);
+                setAchievementSnapshot(normalizeClientSnapshot(snapshot));
+            }).catch(handleClientMutationFailure);
+        }
+        if (client) {
+            return refresh().then(() => undefined);
+        }
+        engine === null || engine === void 0 ? void 0 : engine.reset();
     };
     const getState = () => {
-        const snapshot = engine.getSnapshot();
+        const snapshot = engine ? engine.getSnapshot() : achievementSnapshot;
         return {
             metrics: snapshot.metrics,
             unlocked: snapshot.unlockedIds,
         };
     };
     const exportData = () => {
-        return engine.export();
+        return engine ? engine.export() : JSON.stringify(achievementSnapshot);
     };
     const importData = (jsonString, options) => {
+        if (!engine) {
+            return {
+                success: false,
+                errors: ['importData is not supported by remote achievement clients. Import on the server instead.'],
+            };
+        }
         const result = engine.import(jsonString, options);
         syncAchievementState();
         return result;
     };
     const getAllAchievements = () => {
-        return engine.getSnapshot().allAchievements;
+        return engine ? engine.getSnapshot().allAchievements : achievementSnapshot.allAchievements;
     };
     const achievements = {
         unlocked: achievementSnapshot.unlockedIds,
@@ -152,6 +318,9 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
     };
     return (React.createElement(AchievementContext.Provider, { value: {
             update,
+            increment,
+            event,
+            refresh,
             achievements,
             snapshot: achievementSnapshot,
             reset,
@@ -160,27 +329,21 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
             importData,
             getAllAchievements,
             engine,
+            client,
             icons,
+            recentlyUnlocked,
+            isLoading,
+            error,
             _isLegacyPattern: isProviderCreatedEngine,
         } }, children));
 };
 
-/**
- * Access the active AchievementEngine instance.
- *
- * In v4 this works with both provider-created engines (`achievements` prop) and
- * injected engines (`engine` prop).
- */
-const useAchievementEngine = () => {
+const useAchievements = () => {
     const context = React.useContext(AchievementContext);
     if (!context) {
-        throw new Error('useAchievementEngine must be used within an AchievementProvider.\n\n' +
-            'Wrap your component tree:\n' +
-            '<AchievementProvider achievements={achievements}>\n' +
-            '  <YourComponent />\n' +
-            '</AchievementProvider>');
+        throw new Error('useAchievements must be used within an AchievementProvider');
     }
-    return context.engine;
+    return context;
 };
 
 /**
@@ -558,8 +721,9 @@ const AchievementUIContext = React.createContext({
 });
 const AchievementEffects = ({ icons, ui, achievementConfetti }) => {
     var _a, _b;
-    const engine = useAchievementEngine();
-    const seenAchievementsRef = React.useRef(new Set(engine.getUnlocked()));
+    const achievementContext = useAchievements();
+    const engine = achievementContext.engine;
+    const seenAchievementsRef = React.useRef(new Set(achievementContext.snapshot.unlockedIds));
     const confettiTimerRef = React.useRef(null);
     const achievementConfettiRef = React.useRef(achievementConfetti);
     const [showConfetti, setShowConfetti] = React.useState(false);
@@ -588,42 +752,47 @@ const AchievementEffects = ({ icons, ui, achievementConfetti }) => {
             setActiveConfettiConfig(null);
         }
     }, [ui.enableConfetti]);
+    const showUnlockedAchievement = React.useCallback((unlockedAchievement) => {
+        var _a, _b;
+        if (seenAchievementsRef.current.has(unlockedAchievement.achievementId)) {
+            return;
+        }
+        seenAchievementsRef.current.add(unlockedAchievement.achievementId);
+        if (ui.enableNotifications !== false) {
+            setNotifications((currentNotifications) => {
+                if (currentNotifications.some((notification) => notification.achievementId === unlockedAchievement.achievementId)) {
+                    return currentNotifications;
+                }
+                return [...currentNotifications, unlockedAchievement];
+            });
+        }
+        const rewardConfetti = (_a = unlockedAchievement.confetti) !== null && _a !== void 0 ? _a : achievementConfettiRef.current.get(unlockedAchievement.achievementId);
+        if (ui.enableConfetti !== false && rewardConfetti !== false) {
+            if (confettiTimerRef.current) {
+                clearTimeout(confettiTimerRef.current);
+            }
+            const resolvedConfettiConfig = Object.assign(Object.assign({}, globalConfettiConfigRef.current), (rewardConfetti || {}));
+            const resolvedConfettiDuration = (_b = resolvedConfettiConfig.duration) !== null && _b !== void 0 ? _b : CONFETTI_DURATION_MS;
+            setActiveConfettiConfig(resolvedConfettiConfig);
+            setShowConfetti(true);
+            confettiTimerRef.current = setTimeout(() => {
+                setShowConfetti(false);
+                confettiTimerRef.current = null;
+            }, resolvedConfettiDuration);
+        }
+    }, [ui.enableConfetti, ui.enableNotifications]);
     React.useEffect(() => {
+        if (!engine) {
+            return;
+        }
         const unsubscribeUnlocked = engine.on('achievement:unlocked', (event) => {
-            var _a;
-            if (seenAchievementsRef.current.has(event.achievementId)) {
-                return;
-            }
-            seenAchievementsRef.current.add(event.achievementId);
-            const unlockedAchievement = {
+            showUnlockedAchievement({
                 achievementId: event.achievementId,
                 achievementTitle: event.achievementTitle,
                 achievementDescription: event.achievementDescription,
                 achievementIconKey: event.achievementIconKey,
                 isUnlocked: true,
-            };
-            if (ui.enableNotifications !== false) {
-                setNotifications((currentNotifications) => {
-                    if (currentNotifications.some((notification) => notification.achievementId === unlockedAchievement.achievementId)) {
-                        return currentNotifications;
-                    }
-                    return [...currentNotifications, unlockedAchievement];
-                });
-            }
-            const rewardConfetti = achievementConfettiRef.current.get(event.achievementId);
-            if (ui.enableConfetti !== false && rewardConfetti !== false) {
-                if (confettiTimerRef.current) {
-                    clearTimeout(confettiTimerRef.current);
-                }
-                const resolvedConfettiConfig = Object.assign(Object.assign({}, globalConfettiConfigRef.current), (rewardConfetti || {}));
-                const resolvedConfettiDuration = (_a = resolvedConfettiConfig.duration) !== null && _a !== void 0 ? _a : CONFETTI_DURATION_MS;
-                setActiveConfettiConfig(resolvedConfettiConfig);
-                setShowConfetti(true);
-                confettiTimerRef.current = setTimeout(() => {
-                    setShowConfetti(false);
-                    confettiTimerRef.current = null;
-                }, resolvedConfettiDuration);
-            }
+            });
         });
         const unsubscribeStateChanged = engine.on('state:changed', () => {
             const unlocked = new Set(engine.getUnlocked());
@@ -640,7 +809,18 @@ const AchievementEffects = ({ icons, ui, achievementConfetti }) => {
                 clearTimeout(confettiTimerRef.current);
             }
         };
-    }, [engine, ui.enableConfetti, ui.enableNotifications]);
+    }, [engine, showUnlockedAchievement]);
+    React.useEffect(() => {
+        achievementContext.recentlyUnlocked.forEach(showUnlockedAchievement);
+    }, [achievementContext.recentlyUnlocked, showUnlockedAchievement]);
+    React.useEffect(() => {
+        const unlocked = new Set(achievementContext.snapshot.unlockedIds);
+        seenAchievementsRef.current.forEach((achievementId) => {
+            if (!unlocked.has(achievementId)) {
+                seenAchievementsRef.current.delete(achievementId);
+            }
+        });
+    }, [achievementContext.snapshot.unlockedIds]);
     const NotificationComponent = ui.NotificationComponent || BuiltInNotification;
     const ConfettiComponentResolved = ui.ConfettiComponent || BuiltInConfetti;
     return (React.createElement(React.Fragment, null,
@@ -661,14 +841,6 @@ const AchievementProvider = (_a) => {
             React.createElement(AchievementEffects, { achievementConfetti: confettiByAchievementId, icons: icons, ui: ui }))));
 };
 
-const useAchievements = () => {
-    const context = React.useContext(AchievementContext);
-    if (!context) {
-        throw new Error('useAchievements must be used within an AchievementProvider');
-    }
-    return context;
-};
-
 const useAchievementState = () => {
     const { snapshot } = useAchievements();
     return {
@@ -1188,11 +1360,11 @@ const LevelProgress = ({ level, currentXP, nextLevelXP, label = 'Level', valueLa
  * Provides the v4 happy path for direct metric updates plus explicit state names.
  */
 const useSimpleAchievements = () => {
-    const { update, reset, getState, exportData, importData, engine } = useAchievements();
+    const { update, increment: incrementMetric, event, refresh, reset, getState, exportData, importData, isLoading, error, } = useAchievements();
     const achievementState = useAchievementState();
     const track = (metric, value) => update({ [metric]: value });
     const increment = (metric, amount = 1) => {
-        return engine.increment(metric, amount);
+        return incrementMetric(metric, amount);
     };
     const trackMultiple = (metrics) => update(metrics);
     return {
@@ -1205,6 +1377,11 @@ const useSimpleAchievements = () => {
         unlockedCount: achievementState.unlockedCount,
         totalCount: achievementState.totalCount,
         metrics: achievementState.metrics,
+        isLoading,
+        error,
+        event,
+        emit: event,
+        refresh,
         reset,
         getState,
         exportData,
@@ -1221,6 +1398,110 @@ const useSimpleAchievements = () => {
     };
 };
 
+/**
+ * Access the active AchievementEngine instance.
+ *
+ * In v4 this works with both provider-created engines (`achievements` prop) and
+ * injected engines (`engine` prop).
+ */
+const useAchievementEngine = () => {
+    const context = React.useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievementEngine must be used within an AchievementProvider.\n\n' +
+            'Wrap your component tree:\n' +
+            '<AchievementProvider achievements={achievements}>\n' +
+            '  <YourComponent />\n' +
+            '</AchievementProvider>');
+    }
+    if (!context.engine) {
+        throw new Error('useAchievementEngine is only available when AchievementProvider is using the legacy in-browser engine. ' +
+            'For server-backed achievements, use useSimpleAchievements().event(), track(), or increment().');
+    }
+    return context.engine;
+};
+
+const trimTrailingSlash = (value) => value.replace(/\/$/, '');
+class RestAchievementClient {
+    constructor(config) {
+        this.baseUrl = trimTrailingSlash(config.baseUrl);
+        this.fetcher = config.fetcher || fetch.bind(globalThis);
+        this.headers = config.headers;
+        this.credentials = config.credentials;
+        this.timeout = config.timeout;
+    }
+    getSnapshot() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request('', { method: 'GET' });
+        });
+    }
+    track(metric, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request('/track', {
+                method: 'POST',
+                body: JSON.stringify({ metric, value }),
+            });
+        });
+    }
+    trackMany(metrics) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request('/track', {
+                method: 'POST',
+                body: JSON.stringify({ metrics }),
+            });
+        });
+    }
+    increment(metric_1) {
+        return __awaiter(this, arguments, void 0, function* (metric, amount = 1) {
+            return this.request('/increment', {
+                method: 'POST',
+                body: JSON.stringify({ metric, amount }),
+            });
+        });
+    }
+    event(name, payload) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request('/event', {
+                method: 'POST',
+                body: JSON.stringify({ name, payload }),
+            });
+        });
+    }
+    reset() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request('/reset', { method: 'POST' });
+        });
+    }
+    request(path, init) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const controller = this.timeout ? new AbortController() : undefined;
+            const timeoutId = controller
+                ? setTimeout(() => controller.abort(), this.timeout)
+                : undefined;
+            try {
+                const response = yield this.fetcher(`${this.baseUrl}${path}`, Object.assign(Object.assign({}, init), { credentials: this.credentials, headers: Object.assign(Object.assign({ 'Content-Type': 'application/json' }, (yield this.resolveHeaders())), init.headers), signal: controller === null || controller === void 0 ? void 0 : controller.signal }));
+                if (!response.ok) {
+                    throw new Error(`Achievement request failed: HTTP ${response.status}`);
+                }
+                return yield response.json();
+            }
+            finally {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+            }
+        });
+    }
+    resolveHeaders() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.headers) {
+                return {};
+            }
+            return typeof this.headers === 'function' ? this.headers() : this.headers;
+        });
+    }
+}
+const createRestAchievementClient = (config) => new RestAchievementClient(config);
+
 /**
  * Built-in modal component
  * Modern, theme-aware achievement modal with smooth animations
@@ -1576,6 +1857,8 @@ exports.BuiltInNotification = BuiltInNotification;
 exports.ConfettiWrapper = ConfettiWrapper;
 exports.HeadlessAchievementProvider = AchievementProvider$1;
 exports.LevelProgress = LevelProgress;
+exports.RestAchievementClient = RestAchievementClient;
+exports.createRestAchievementClient = createRestAchievementClient;
 exports.defaultAchievementIcons = defaultAchievementIcons;
 exports.defaultStyles = defaultStyles;
 exports.isAsyncStorage = isAsyncStorage;