react-achievements 4.4.1 → 5.0.1

package/LICENSE

@@ -1,18 +1,13 @@
-# Dual License
-
-React Achievements is dual-licensed under the MIT License for non-commercial use and a Commercial License for commercial use.
-
-## MIT License (Non-Commercial Use)
+MIT License
 
 Copyright (c) 2025 Dave B
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction for **non-commercial purposes**, including
-without limitation the rights to use, copy, modify, merge, publish, distribute,
-sublicense, and/or sell copies of the Software for non-commercial purposes,
-and to permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
@@ -24,66 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-### Non-Commercial Use Includes:
-
-- Personal projects (no revenue generation)
-- Educational and academic institutions
-- Non-profit organizations with 501(c)(3) or equivalent status
-- Open source projects (with OSI-approved license)
-- Evaluation, development, and testing purposes
-- Government agencies and public sector organizations
-
----
-
-## Commercial License
-
-**Commercial use requires a paid license via GitHub Sponsors.**
-
-### What Constitutes Commercial Use:
-
-Commercial use includes, but is not limited to:
-
-- Companies or organizations using this library in products/services that generate revenue
-- SaaS (Software as a Service) applications
-- Commercial websites, web applications, or mobile apps
-- Enterprise software or internal business applications
-- Freelancers or contractors building paid projects for clients
-- Any use where the library contributes to revenue-generating activities
-
-### How to Obtain a Commercial License:
-
-Visit our **[GitHub Sponsors page](https://github.com/sponsors/dave-b-b)** to select a tier that matches your organization's size and revenue.
-
-**Pricing Tiers:**
-
-- **Indie Developer** ($19/month): For small businesses, freelancers, and startups with annual revenue < $100,000
-- **Professional** ($49/month): For growing companies with annual revenue < $1,000,000, includes priority support
-- **Enterprise** ($199/month): For large companies with unlimited revenue, includes private support channel and feature requests
-
-For custom licensing arrangements or questions, please contact: dave.b.business@gmail.com
-
-See [COMMERCIAL-LICENSE.md](./COMMERCIAL-LICENSE.md) for detailed commercial licensing terms.
-
----
-
-## Frequently Asked Questions
-
-**Q: I'm a freelancer building a website for a client. Do I need a commercial license?**
-A: Yes, if the client is paying you or if the website generates revenue, you need a commercial license.
-
-**Q: I'm using this in an open-source project. Do I need a commercial license?**
-A: No, open-source projects with an OSI-approved license can use the MIT license.
-
-**Q: Can I try the library before committing to a commercial license?**
-A: Yes, evaluation and testing fall under non-commercial use.
-
-**Q: What if my startup grows and exceeds the Indie Developer tier revenue?**
-A: Please upgrade to the appropriate tier when your revenue grows. We operate on an honor system and trust our users.
-
-**Q: Do non-profits need a commercial license?**
-A: No, registered non-profit organizations (501(c)(3) or equivalent) can use the MIT license for free.
-
----
-
-For questions about licensing, please email dave.b.business@gmail.com or open a discussion on GitHub.

package/README.md

@@ -1,10 +1,10 @@
 # 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/)
+[![npm version](https://img.shields.io/npm/v/react-achievements.svg)](https://www.npmjs.com/package/react-achievements) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
 <p align="center">
   <img
@@ -22,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>
@@ -59,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"
@@ -120,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',
@@ -142,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 = {
@@ -173,6 +189,7 @@ const achievements = {
 const {
   track,
   increment,
+  event,
   trackMultiple,
   unlockedIds,
   unlockedAchievements,
@@ -184,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:
@@ -250,7 +260,7 @@ function CustomAchievementsPanel() {
 
 export function App() {
   return (
-    <AchievementProvider achievements={achievements}>
+    <AchievementProvider client={achievementsClient}>
       <CustomAchievementsPanel />
     </AchievementProvider>
   );
@@ -275,12 +285,9 @@ React Native UI components are not included in the web package; use `achievement
 
 ## License
 
-React Achievements is dual-licensed:
-
-- **Free for Non-Commercial Use** (MIT License)
-- **Commercial License Required** for businesses, SaaS, commercial apps, and enterprise use
+React Achievements is licensed under the MIT License. It is free to use, modify, distribute, and include in personal, open-source, and commercial projects.
 
-[Get Commercial License](https://github.com/sponsors/dave-b-b) | [License Details](./LICENSE) | [Commercial Terms](./COMMERCIAL-LICENSE.md)
+See [LICENSE](./LICENSE) for details.
 
 ## AI Agents