react-achievements 4.4.0 → 5.0.0

package/README.md

@@ -1,19 +1,17 @@
 # React Achievements
 
-**Add gamification to your React app in minutes** - Track progress, unlock achievements, show badges, and celebrate milestones.
+**Display server-backed achievements in React** - fetch achievement state from your app server, track progress through REST calls, show badges, and celebrate unlocks.
 
 [📚 Documentation](https://dave-b-b.github.io/react-achievements/) | [📦 npm Package](https://www.npmjs.com/package/react-achievements)
 
 [![npm version](https://img.shields.io/npm/v/react-achievements.svg)](https://www.npmjs.com/package/react-achievements) [![License](https://img.shields.io/badge/license-Dual%20(MIT%20%2B%20Commercial)-blue.svg)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
 <p align="center">
-  <a href="https://github.com/dave-b-b/react-achievements/raw/main/assets/Demo-v4-3.mov">
-    <img
-      src="https://raw.githubusercontent.com/dave-b-b/react-achievements/main/assets/demo-v4-3.gif"
-      alt="React Achievements 4.3 demo showing achievement progress, unlock notifications, and a compact LearnQuest achievements modal"
-      width="900"
-    />
-  </a>
+  <img
+    src="https://raw.githubusercontent.com/dave-b-b/react-achievements/main/assets/demo-v4-4.gif"
+    alt="React Achievements 4.4 demo showing achievement progress, unlock notifications, configurable confetti, and a compact LearnQuest achievements modal"
+    width="900"
+  />
 </p>
 
 ## Installation
@@ -24,34 +22,38 @@ npm install react-achievements
 
 **Requirements:** React 16.8+, Node.js 16+
 
+If you want the official JavaScript backend engine, install `achievements-engine` in your server package. React Achievements can also display achievement data from Rails Merit or any backend that implements the same REST contract.
+
 ## Start Here
 
 ```tsx
 import {
   AchievementProvider,
   AchievementsWidget,
+  createRestAchievementClient,
   useSimpleAchievements,
 } from 'react-achievements';
 
-const achievements = {
-  score: {
-    100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
-  },
-};
+const achievementsClient = createRestAchievementClient({
+  baseUrl: '/api/achievements',
+});
 
 function Game() {
-  const { track } = useSimpleAchievements();
+  const { track, event } = useSimpleAchievements();
 
   return (
-    <button onClick={() => track('score', 100)}>
-      Score 100
-    </button>
+    <>
+      <button onClick={() => track('score', 100)}>Score 100</button>
+      <button onClick={() => event('lesson.completed', { lessonId: 'intro' })}>
+        Complete lesson
+      </button>
+    </>
   );
 }
 
 export default function App() {
   return (
-    <AchievementProvider achievements={achievements}>
+    <AchievementProvider client={achievementsClient}>
       <Game />
       <AchievementsWidget />
     </AchievementProvider>
@@ -61,6 +63,18 @@ export default function App() {
 
 `AchievementsWidget` reads from context, shows the unlocked count, and opens a modal with locked and unlocked achievements. Use `placement="inline"` to put it in a drawer, sidebar, or navigation area. For an exact visual match, pass `renderTrigger` and use your app's own drawer row, nav item, or profile menu button while the widget still controls the modal.
 
+Your server should expose this contract:
+
+```http
+GET  /api/achievements
+POST /api/achievements/track
+POST /api/achievements/increment
+POST /api/achievements/event
+POST /api/achievements/reset
+```
+
+The official `achievements-engine` package can run those routes on your server, but any backend can return the same snapshot shape.
+
 ```tsx
 <AchievementsWidget
   placement="inline"
@@ -122,7 +136,7 @@ Provider-level icons and UI options are shared across notifications, widgets, mo
 
 ```tsx
 <AchievementProvider
-  achievements={achievements}
+  client={achievementsClient}
   icons={{ login: '🔑', streak: '🔥' }}
   ui={{
     theme: 'minimal',
@@ -144,7 +158,7 @@ Provider-level icons and UI options are shared across notifications, widgets, mo
 
 Set `ui.enableConfetti` to `false` to disable the built-in celebration. Omit `ConfettiComponent` when you only want to tune the default `canvas-confetti` animation through `ui.confetti`.
 
-Rewards can optionally override the global confetti settings. Omit `confetti` to use the provider defaults, or set `confetti: false` for quieter rewards:
+Rewards returned by your server can optionally include `confetti` to override the global confetti settings. Omit `confetti` to use the provider defaults, or set `confetti: false` for quieter rewards:
 
 ```tsx
 const achievements = {
@@ -175,6 +189,7 @@ const achievements = {
 const {
   track,
   increment,
+  event,
   trackMultiple,
   unlockedIds,
   unlockedAchievements,
@@ -186,41 +201,34 @@ const {
 
 Deprecated aliases from v3, including `unlocked` and `all`, remain available until 5.0.
 
-## Event-Based Tracking
+## Server Engine Example
 
-For larger apps, create an engine and emit semantic events:
+Use `achievements-engine` on your server when you want JavaScript rule evaluation and persistence adapters:
 
-```tsx
+```ts
 import {
-  AchievementEngine,
-  AchievementProvider,
-  AchievementsWidget,
-  useAchievementEngine,
-} from 'react-achievements';
+  AchievementService,
+  MemoryAchievementRepository,
+  createAchievementFetchHandler,
+} from 'achievements-engine/server';
 
-const engine = new AchievementEngine({
+const service = new AchievementService({
   achievements,
+  repository: new MemoryAchievementRepository(),
   eventMapping: {
-    userScored: (data) => ({ score: data.points }),
+    'lesson.completed': () => ({ completedLesson: true }),
   },
-  storage: 'local',
 });
 
-function Game() {
-  const engine = useAchievementEngine();
-  return <button onClick={() => engine.emit('userScored', { points: 100 })}>Score</button>;
-}
-
-export default function App() {
-  return (
-    <AchievementProvider engine={engine}>
-      <Game />
-      <AchievementsWidget />
-    </AchievementProvider>
-  );
-}
+export const handleAchievementsRequest = createAchievementFetchHandler({
+  service,
+  basePath: '/api/achievements',
+  getSubjectId: (request) => getUserIdFromSession(request),
+});
 ```
 
+For Rails Merit or a custom backend, expose the same REST endpoints and return the same achievement snapshot fields.
+
 ## Headless Usage
 
 Use the DOM-free entry point when building custom UI or preparing a React Native integration:
@@ -252,7 +260,7 @@ function CustomAchievementsPanel() {
 
 export function App() {
   return (
-    <AchievementProvider achievements={achievements}>
+    <AchievementProvider client={achievementsClient}>
       <CustomAchievementsPanel />
     </AchievementProvider>
   );

package/dist/headless.cjs

@@ -17,6 +17,38 @@ var StorageType;
     StorageType["RestAPI"] = "restapi"; // Asynchronous REST API storage
 })(StorageType || (StorageType = {}));
 
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+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;
+};
+
 const warnedMessages = new Set();
 function warnDeprecation(message) {
     var _a, _b;
@@ -33,18 +65,74 @@ const AchievementContext = React.createContext(undefined);
 const getAllAchievementRecord = (achievements) => {
     return Object.fromEntries(achievements.map((achievement) => [achievement.achievementId, achievement]));
 };
-const AchievementProvider = ({ 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 = ({ 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;
         }
@@ -61,18 +149,63 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = 'loca
             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);
@@ -87,29 +220,84 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = 'loca
             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,
@@ -117,6 +305,9 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = 'loca
     };
     return (React.createElement(AchievementContext.Provider, { value: {
             update,
+            increment,
+            event,
+            refresh,
             achievements,
             snapshot: achievementSnapshot,
             reset,
@@ -125,7 +316,11 @@ const AchievementProvider = ({ achievements: achievementsConfig, storage = 'loca
             importData,
             getAllAchievements,
             engine,
+            client,
             icons,
+            recentlyUnlocked,
+            isLoading,
+            error,
             _isLegacyPattern: isProviderCreatedEngine,
         } }, children));
 };
@@ -155,11 +350,11 @@ const useAchievementState = () => {
  * 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 {
@@ -172,6 +367,11 @@ const useSimpleAchievements = () => {
         unlockedCount: achievementState.unlockedCount,
         totalCount: achievementState.totalCount,
         metrics: achievementState.metrics,
+        isLoading,
+        error,
+        event,
+        emit: event,
+        refresh,
         reset,
         getState,
         exportData,
@@ -203,9 +403,95 @@ const useAchievementEngine = () => {
             '  <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);
+
 Object.defineProperty(exports, 'AchievementBuilder', {
     enumerable: true,
     get: function () { return achievementsEngine.AchievementBuilder; }
@@ -296,6 +582,8 @@ Object.defineProperty(exports, 'normalizeAchievements', {
 });
 exports.AchievementContext = AchievementContext;
 exports.AchievementProvider = AchievementProvider;
+exports.RestAchievementClient = RestAchievementClient;
+exports.createRestAchievementClient = createRestAchievementClient;
 exports.isAsyncStorage = isAsyncStorage;
 exports.useAchievementEngine = useAchievementEngine;
 exports.useAchievementState = useAchievementState;