@umituz/react-native-gamification 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Ümit UZ
+
+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, 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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.
+

package/README.md

@@ -0,0 +1,276 @@
+# @umituz/react-native-gamification
+
+Comprehensive gamification system for React Native apps with achievements, points, levels, streaks, leaderboards, rewards, and progress tracking.
+
+## Features
+
+- 🏆 **Achievements** - Track and unlock user achievements
+- 💰 **Points System** - Award and manage user points
+- 📈 **Levels** - Experience-based leveling system
+- 🔥 **Streaks** - Track consecutive activities
+- 🏅 **Leaderboards** - Competitive rankings
+- 🎁 **Rewards** - Unlockable rewards system
+- 📊 **Progress Tracking** - Monitor user progress across metrics
+
+## Installation
+
+```bash
+npm install @umituz/react-native-gamification
+```
+
+## Peer Dependencies
+
+- `react` >= 18.2.0
+- `react-native` >= 0.74.0
+- `@umituz/react-native-storage` (latest)
+- `zustand` >= 4.0.0
+
+## Quick Start
+
+```typescript
+import { useGamification, useGamificationInitializer } from '@umituz/react-native-gamification';
+
+function App() {
+  const userId = 'user-123';
+  useGamificationInitializer(userId);
+  
+  const { 
+    achievements, 
+    pointBalance, 
+    level,
+    addPoints,
+    addExperience 
+  } = useGamification();
+
+  // Add points when user completes an action
+  const handleActionComplete = async () => {
+    await addPoints(10, 'action_completed', 'action-id', 'actions', 'Completed action');
+  };
+
+  return (
+    // Your app UI
+  );
+}
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import { useGamification, useGamificationInitializer } from '@umituz/react-native-gamification';
+
+function MyComponent() {
+  const userId = 'user-123';
+  
+  // Initialize gamification system
+  useGamificationInitializer(userId);
+  
+  const gamification = useGamification();
+  
+  // Check if initialized
+  if (!gamification.isInitialized) {
+    return <Loading />;
+  }
+  
+  return <YourContent />;
+}
+```
+
+### Achievements
+
+```typescript
+import { useAchievements } from '@umituz/react-native-gamification';
+
+function AchievementsScreen() {
+  const { 
+    achievements, 
+    unlockAchievement,
+    updateAchievementProgress 
+  } = useAchievements();
+
+  // Update progress
+  await updateAchievementProgress('achievement-id', 50);
+
+  // Unlock achievement
+  await unlockAchievement('achievement-id');
+
+  return (
+    <View>
+      {achievements.map(achievement => (
+        <AchievementCard key={achievement.id} achievement={achievement} />
+      ))}
+    </View>
+  );
+}
+```
+
+### Points
+
+```typescript
+import { usePoints } from '@umituz/react-native-gamification';
+
+function PointsDisplay() {
+  const { 
+    pointBalance, 
+    addPoints, 
+    deductPoints 
+  } = usePoints();
+
+  // Add points
+  await addPoints(100, 'purchase', 'purchase-id', 'purchases', 'Made a purchase');
+
+  // Deduct points
+  await deductPoints(50, 'reward_claim', 'reward-id', 'Claimed reward');
+
+  return (
+    <Text>Total Points: {pointBalance?.total || 0}</Text>
+  );
+}
+```
+
+### Levels
+
+```typescript
+import { useLevel } from '@umituz/react-native-gamification';
+
+function LevelDisplay() {
+  const { 
+    level, 
+    addExperience 
+  } = useLevel();
+
+  // Add experience
+  await addExperience(50, 'action_completed');
+
+  return (
+    <View>
+      <Text>Level: {level?.currentLevel || 1}</Text>
+      <Text>XP: {level?.currentExperience || 0} / {level?.experienceToNextLevel || 100}</Text>
+      <ProgressBar progress={level?.levelProgress || 0} />
+    </View>
+  );
+}
+```
+
+### Streaks
+
+```typescript
+import { useStreaks } from '@umituz/react-native-gamification';
+
+function StreakDisplay() {
+  const { 
+    streaks, 
+    updateStreakActivity 
+  } = useStreaks();
+
+  // Update streak
+  await updateStreakActivity('daily_login', new Date().toISOString());
+
+  const loginStreak = streaks.find(s => s.type === 'daily_login');
+
+  return (
+    <Text>Login Streak: {loginStreak?.currentStreak || 0} days</Text>
+  );
+}
+```
+
+### Rewards
+
+```typescript
+import { useRewards } from '@umituz/react-native-gamification';
+
+function RewardsScreen() {
+  const { 
+    rewards, 
+    claimReward,
+    getAvailableRewards 
+  } = useRewards();
+
+  const availableRewards = getAvailableRewards();
+
+  const handleClaim = async (rewardId: string) => {
+    const claim = await claimReward(rewardId);
+    if (claim) {
+      console.log('Reward claimed!');
+    }
+  };
+
+  return (
+    <View>
+      {availableRewards.map(reward => (
+        <RewardCard 
+          key={reward.id} 
+          reward={reward}
+          onClaim={() => handleClaim(reward.id)}
+        />
+      ))}
+    </View>
+  );
+}
+```
+
+### Progress Tracking
+
+```typescript
+import { useProgress } from '@umituz/react-native-gamification';
+
+function ProgressTracker() {
+  const { 
+    progress, 
+    updateProgress 
+  } = useProgress();
+
+  // Update progress
+  await updateProgress({
+    userId: 'user-123',
+    metric: 'goals_completed',
+    increment: 1,
+    category: 'goals',
+    period: 'all-time'
+  });
+
+  const goalsProgress = progress.find(p => p.metric === 'goals_completed');
+
+  return (
+    <View>
+      <Text>Goals Completed: {goalsProgress?.currentValue || 0}</Text>
+      <ProgressBar progress={goalsProgress?.progress || 0} />
+    </View>
+  );
+}
+```
+
+## Custom Repository
+
+You can provide a custom repository implementation for app-specific storage:
+
+```typescript
+import { useGamificationRepository } from '@umituz/react-native-gamification';
+import { MyCustomRepository } from './MyCustomRepository';
+
+function App() {
+  const customRepository = new MyCustomRepository();
+  
+  useGamificationRepository(customRepository);
+  
+  // Rest of your app
+}
+```
+
+## Architecture
+
+This package follows Domain-Driven Design (DDD) principles:
+
+- **Domain Layer** - Entities and repository interfaces
+- **Infrastructure Layer** - Repository implementations and stores
+- **Presentation Layer** - React hooks for easy integration
+
+## License
+
+MIT
+
+## Author
+
+Ümit UZ <umit@umituz.com>
+

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@umituz/react-native-gamification",
+  "version": "1.1.0",
+  "description": "Comprehensive gamification system for React Native apps with achievements, points, levels, streaks, leaderboards, rewards, and progress tracking",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "gamification",
+    "achievements",
+    "points",
+    "levels",
+    "streaks",
+    "leaderboards",
+    "rewards",
+    "progress",
+    "gameification"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/react-native-gamification"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0",
+    "@umituz/react-native-storage": "latest",
+    "zustand": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "zustand": "^4.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/domain/entities/Achievement.ts

@@ -0,0 +1,46 @@
+/**
+ * Achievement Entity
+ * 
+ * Represents a user achievement in the gamification system
+ */
+
+export interface Achievement {
+  id: string;
+  userId: string;
+  type: string; // Achievement type identifier (e.g., "first_goal", "streak_7_days")
+  title: string;
+  description: string;
+  icon?: string;
+  category?: string; // Category for grouping achievements
+  unlocked: boolean;
+  unlockedDate?: string;
+  progress: number; // Current progress (0-100 or 0-requirement)
+  requirement: number; // Required value to unlock
+  points?: number; // Points awarded when unlocked
+  rarity?: "common" | "rare" | "epic" | "legendary";
+  metadata?: Record<string, any>; // Additional metadata
+  createdDate: string;
+  updatedDate: string;
+}
+
+export interface AchievementDefinition {
+  type: string;
+  title: string;
+  description: string;
+  icon?: string;
+  category?: string;
+  requirement: number;
+  points?: number;
+  rarity?: "common" | "rare" | "epic" | "legendary";
+  metadata?: Record<string, any>;
+}
+
+export interface AchievementProgress {
+  achievementId: string;
+  userId: string;
+  currentValue: number;
+  requirement: number;
+  progress: number; // Percentage (0-100)
+  unlocked: boolean;
+}
+

package/src/domain/entities/Leaderboard.ts

@@ -0,0 +1,45 @@
+/**
+ * Leaderboard Entity
+ * 
+ * Represents leaderboard entries in the gamification system
+ */
+
+export interface LeaderboardEntry {
+  id: string;
+  userId: string;
+  leaderboardId: string; // Leaderboard identifier (e.g., "global", "weekly", "monthly")
+  rank: number; // Current rank (1-based)
+  score: number; // Score for ranking
+  metric: string; // Metric used for ranking (e.g., "points", "experience", "streak")
+  displayName?: string; // User's display name
+  avatar?: string; // User's avatar URL
+  metadata?: Record<string, any>;
+  period?: "daily" | "weekly" | "monthly" | "all-time"; // Time period for leaderboard
+  periodStart?: string; // Start date of the period
+  periodEnd?: string; // End date of the period
+  createdDate: string;
+  updatedDate: string;
+}
+
+export interface Leaderboard {
+  id: string;
+  name: string;
+  description?: string;
+  metric: string; // Metric used for ranking
+  period?: "daily" | "weekly" | "monthly" | "all-time";
+  periodStart?: string;
+  periodEnd?: string;
+  entries: LeaderboardEntry[];
+  totalParticipants: number;
+  lastUpdated: string;
+}
+
+export interface LeaderboardRanking {
+  userId: string;
+  rank: number;
+  score: number;
+  percentile: number; // Percentile rank (0-100)
+  aboveUsers: number; // Number of users above
+  belowUsers: number; // Number of users below
+}
+

package/src/domain/entities/Level.ts

@@ -0,0 +1,38 @@
+/**
+ * Level Entity
+ * 
+ * Represents user levels in the gamification system
+ */
+
+export interface Level {
+  id: string;
+  userId: string;
+  currentLevel: number;
+  currentExperience: number; // Current XP in current level
+  totalExperience: number; // Total XP accumulated
+  experienceToNextLevel: number; // XP needed for next level
+  levelProgress: number; // Percentage progress in current level (0-100)
+  metadata?: Record<string, any>;
+  createdDate: string;
+  updatedDate: string;
+}
+
+export interface LevelDefinition {
+  level: number;
+  experienceRequired: number; // Total XP required to reach this level
+  title?: string;
+  description?: string;
+  rewards?: string[]; // Reward IDs or types
+  metadata?: Record<string, any>;
+}
+
+export interface LevelProgress {
+  userId: string;
+  currentLevel: number;
+  currentExperience: number;
+  totalExperience: number;
+  experienceToNextLevel: number;
+  levelProgress: number;
+  canLevelUp: boolean;
+}
+

package/src/domain/entities/Point.ts

@@ -0,0 +1,38 @@
+/**
+ * Point Entity
+ * 
+ * Represents points in the gamification system
+ */
+
+export interface Point {
+  id: string;
+  userId: string;
+  amount: number;
+  source: string; // Source of points (e.g., "achievement", "action", "reward")
+  sourceId?: string; // ID of the source (e.g., achievement ID)
+  category?: string; // Category for grouping points
+  description?: string;
+  metadata?: Record<string, any>;
+  createdDate: string;
+}
+
+export interface PointBalance {
+  userId: string;
+  total: number;
+  byCategory: Record<string, number>; // Points grouped by category
+  lastUpdated: string;
+}
+
+export interface PointTransaction {
+  id: string;
+  userId: string;
+  amount: number; // Can be negative for deductions
+  source: string;
+  sourceId?: string;
+  category?: string;
+  description?: string;
+  balance: number; // Balance after this transaction
+  metadata?: Record<string, any>;
+  createdDate: string;
+}
+

package/src/domain/entities/Progress.ts

@@ -0,0 +1,41 @@
+/**
+ * Progress Entity
+ * 
+ * Represents user progress tracking in the gamification system
+ */
+
+export interface Progress {
+  id: string;
+  userId: string;
+  metric: string; // Metric identifier (e.g., "goals_completed", "sessions_attended")
+  currentValue: number; // Current value
+  targetValue?: number; // Target value (optional)
+  progress: number; // Percentage progress (0-100)
+  unit?: string; // Unit of measurement (e.g., "times", "hours", "days")
+  category?: string; // Category for grouping
+  period?: "daily" | "weekly" | "monthly" | "all-time"; // Time period
+  periodStart?: string; // Start date of the period
+  periodEnd?: string; // End date of the period
+  metadata?: Record<string, any>;
+  createdDate: string;
+  updatedDate: string;
+}
+
+export interface ProgressUpdate {
+  userId: string;
+  metric: string;
+  increment: number; // Amount to increment
+  category?: string;
+  period?: "daily" | "weekly" | "monthly" | "all-time";
+  metadata?: Record<string, any>;
+}
+
+export interface ProgressMilestone {
+  metric: string;
+  value: number;
+  title: string;
+  description?: string;
+  reward?: string; // Reward ID or type
+  metadata?: Record<string, any>;
+}
+

package/src/domain/entities/Reward.ts

@@ -0,0 +1,48 @@
+/**
+ * Reward Entity
+ * 
+ * Represents rewards in the gamification system
+ */
+
+export interface Reward {
+  id: string;
+  userId: string;
+  type: string; // Reward type (e.g., "badge", "unlock", "discount", "item")
+  title: string;
+  description?: string;
+  icon?: string;
+  category?: string;
+  pointsCost?: number; // Points required to claim
+  levelRequired?: number; // Level required to claim
+  unlocked: boolean;
+  unlockedDate?: string;
+  claimed: boolean;
+  claimedDate?: string;
+  expiresAt?: string; // Expiration date for time-limited rewards
+  metadata?: Record<string, any>;
+  createdDate: string;
+  updatedDate: string;
+}
+
+export interface RewardDefinition {
+  type: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  category?: string;
+  pointsCost?: number;
+  levelRequired?: number;
+  rarity?: "common" | "rare" | "epic" | "legendary";
+  expiresAt?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface RewardClaim {
+  id: string;
+  userId: string;
+  rewardId: string;
+  pointsSpent?: number;
+  claimedDate: string;
+  metadata?: Record<string, any>;
+}
+

package/src/domain/entities/Streak.ts

@@ -0,0 +1,38 @@
+/**
+ * Streak Entity
+ * 
+ * Represents user streaks in the gamification system
+ */
+
+export interface Streak {
+  id: string;
+  userId: string;
+  type: string; // Streak type (e.g., "daily_login", "daily_goal", "weekly_workout")
+  currentStreak: number; // Current consecutive days/actions
+  longestStreak: number; // Longest streak ever achieved
+  lastActivityDate: string; // Last date when streak was maintained
+  isActive: boolean; // Whether streak is currently active
+  metadata?: Record<string, any>;
+  createdDate: string;
+  updatedDate: string;
+}
+
+export interface StreakDefinition {
+  type: string;
+  name: string;
+  description?: string;
+  resetOnMiss: boolean; // Whether streak resets if missed
+  timezone?: string; // Timezone for daily streaks
+  metadata?: Record<string, any>;
+}
+
+export interface StreakProgress {
+  userId: string;
+  type: string;
+  currentStreak: number;
+  longestStreak: number;
+  isActive: boolean;
+  daysUntilMilestone?: number; // Days until next milestone (7, 30, 100, etc.)
+  nextMilestone?: number; // Next milestone value
+}
+