@umituz/react-native-gamification 1.2.1 → 1.3.0

package/src/hooks/useGamification.ts

@@ -0,0 +1,91 @@
+/**
+ * useGamification Hook
+ * Main hook for gamification operations
+ */
+
+import { useCallback, useEffect, useMemo } from "react";
+import { useGamificationStore } from "../store/gamificationStore";
+import { calculateLevel } from "../utils/calculations";
+import type { GamificationConfig, LevelState, Achievement } from "../types";
+
+export interface UseGamificationReturn {
+  // State
+  points: number;
+  totalTasksCompleted: number;
+  level: LevelState;
+  streak: { current: number; longest: number };
+  achievements: Achievement[];
+  isLoading: boolean;
+  isInitialized: boolean;
+
+  // Actions
+  initialize: (config: GamificationConfig) => Promise<void>;
+  completeTask: () => void;
+  addPoints: (amount: number) => void;
+  reset: () => Promise<void>;
+}
+
+export const useGamification = (
+  config?: GamificationConfig
+): UseGamificationReturn => {
+  const store = useGamificationStore();
+
+  // Auto-initialize if config provided
+  useEffect(() => {
+    if (config && !store.isInitialized) {
+      store.initialize(config);
+    }
+  }, [config, store.isInitialized]);
+
+  // Calculate level from config
+  const level = useMemo((): LevelState => {
+    if (!config?.levels.length) {
+      return {
+        currentLevel: 1,
+        currentPoints: store.points,
+        pointsToNext: 50,
+        progress: Math.min(100, (store.points / 50) * 100),
+      };
+    }
+    return calculateLevel(store.points, config.levels);
+  }, [store.points, config?.levels]);
+
+  const completeTask = useCallback(() => {
+    store.completeTask();
+  }, [store.completeTask]);
+
+  const addPoints = useCallback(
+    (amount: number) => {
+      store.addPoints(amount);
+    },
+    [store.addPoints]
+  );
+
+  const initialize = useCallback(
+    async (cfg: GamificationConfig) => {
+      await store.initialize(cfg);
+    },
+    [store.initialize]
+  );
+
+  const reset = useCallback(async () => {
+    await store.reset();
+  }, [store.reset]);
+
+  return {
+    points: store.points,
+    totalTasksCompleted: store.totalTasksCompleted,
+    level,
+    streak: {
+      current: store.streak.current,
+      longest: store.streak.longest,
+    },
+    achievements: store.achievements,
+    isLoading: store.isLoading,
+    isInitialized: store.isInitialized,
+    initialize,
+    completeTask,
+    addPoints,
+    reset,
+  };
+};

package/src/index.ts

@@ -1,125 +1,49 @@
 /**
- * @umituz/react-native-gamification - Public API
+ * @umituz/react-native-gamification
  *
- * Comprehensive gamification system for React Native apps
- *
- * Usage:
- *   import { useGamification, useAchievements, usePoints } from '@umituz/react-native-gamification';
+ * Generic gamification system for React Native apps
+ * All text via props - NO hardcoded strings
+ * Designed for 100+ apps
  */
 
-// =============================================================================
-// DOMAIN LAYER - Entities
-// =============================================================================
-
+// Types
 export type {
-  Achievement,
   AchievementDefinition,
-  AchievementProgress,
-  AchievementDifficulty,
-  AchievementCategory,
-} from "./domain/entities/Achievement";
-export {
-  createAchievement,
-  isAchievementComplete,
-  calculateAchievementProgress,
-  getPointsForDifficulty,
-} from "./domain/entities/Achievement";
-
-export type {
-  Point,
-  PointBalance,
-  PointTransaction,
-} from "./domain/entities/Point";
-
-export type {
-  Level,
+  Achievement,
   LevelDefinition,
-  LevelProgress,
-} from "./domain/entities/Level";
+  LevelState,
+  StreakState,
+  GamificationConfig,
+  GamificationState,
+  GamificationActions,
+  GamificationStore,
+} from "./types";
 
-export type {
-  Streak,
-  StreakDefinition,
-  StreakProgress,
-  StreakMilestone,
-} from "./domain/entities/Streak";
-export {
-  createStreakEntity,
-  isStreakActive,
-  isStreakBroken,
-  updateStreakWithActivity,
-  getStreakMilestones,
-  getNextMilestone,
-  getDaysUntilStreakBreak,
-} from "./domain/entities/Streak";
+// Store
+export { useGamificationStore } from "./store/gamificationStore";
 
-export type {
-  Leaderboard,
-  LeaderboardEntry,
-  LeaderboardRanking,
-  LeaderboardCategory,
-} from "./domain/entities/Leaderboard";
-export {
-  createLeaderboardEntry,
-  getRankChangeIndicator,
-  getTopEntries,
-  findUserRank,
-} from "./domain/entities/Leaderboard";
+// Hooks
+export { useGamification, type UseGamificationReturn } from "./hooks/useGamification";
 
-export type {
-  Reward,
-  RewardDefinition,
-  RewardClaim,
-  RewardRarity,
-} from "./domain/entities/Reward";
+// Utils
 export {
-  createReward,
-  createPointsTransaction,
   calculateLevel,
-  calculateNextLevelPoints,
-  isRewardExpired,
-  getPointsForRarity,
-} from "./domain/entities/Reward";
-
-export type {
-  Progress,
-  ProgressUpdate,
-  ProgressMilestone,
-} from "./domain/entities/Progress";
-
-// =============================================================================
-// DOMAIN LAYER - Repository Interface
-// =============================================================================
-
-export type {
-  IGamificationRepository,
-  GamificationError,
-  GamificationResult,
-} from "./domain/repositories/IGamificationRepository";
-
-// =============================================================================
-// INFRASTRUCTURE LAYER
-// =============================================================================
-
-export { storageGamificationRepository } from "./infrastructure/repositories/StorageGamificationRepository";
-export { useGamificationStore } from "./infrastructure/storage/GamificationStore";
-
-// =============================================================================
-// PRESENTATION LAYER - Hooks
-// =============================================================================
+  checkAchievementUnlock,
+  updateAchievementProgress,
+  isStreakActive,
+  isSameDay,
+} from "./utils/calculations";
 
+// Components
 export {
-  useGamification,
-  useGamificationInitializer,
-  useGamificationRepository,
-} from "./presentation/hooks/useGamification";
-
-export { useAchievements } from "./presentation/hooks/useAchievements";
-export { usePoints } from "./presentation/hooks/usePoints";
-export { useLevel } from "./presentation/hooks/useLevel";
-export { useStreaks } from "./presentation/hooks/useStreaks";
-export { useRewards } from "./presentation/hooks/useRewards";
-export { useProgress } from "./presentation/hooks/useProgress";
-
-
-
+  LevelProgress,
+  type LevelProgressProps,
+  PointsBadge,
+  type PointsBadgeProps,
+  AchievementCard,
+  type AchievementCardProps,
+  AchievementToast,
+  type AchievementToastProps,
+  StreakDisplay,
+  type StreakDisplayProps,
+} from "./components";

package/src/store/gamificationStore.ts

@@ -0,0 +1,167 @@
+/**
+ * Gamification Store
+ * Zustand store with persist middleware
+ */
+
+import { create } from "zustand";
+import { persist, createJSONStorage } from "zustand/middleware";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import type {
+  GamificationState,
+  GamificationActions,
+  GamificationConfig,
+  Achievement,
+} from "../types";
+import {
+  checkAchievementUnlock,
+  updateAchievementProgress,
+  isStreakActive,
+  isSameDay,
+} from "../utils/calculations";
+
+const DEFAULT_STATE: GamificationState = {
+  points: 0,
+  totalTasksCompleted: 0,
+  achievements: [],
+  streak: {
+    current: 0,
+    longest: 0,
+    lastActivityDate: null,
+  },
+  isLoading: false,
+  isInitialized: false,
+};
+
+let currentConfig: GamificationConfig | null = null;
+
+export const useGamificationStore = create<
+  GamificationState & GamificationActions
+>()(
+  persist(
+    (set, get) => ({
+      ...DEFAULT_STATE,
+
+      initialize: async (config: GamificationConfig) => {
+        currentConfig = config;
+        const state = get();
+
+        // Initialize achievements from config
+        const achievements: Achievement[] = config.achievements.map((def) => ({
+          ...def,
+          isUnlocked: false,
+          progress: 0,
+        }));
+
+        // Merge with existing unlocked achievements
+        const mergedAchievements = achievements.map((ach) => {
+          const existing = state.achievements.find((a) => a.id === ach.id);
+          if (existing) {
+            return { ...ach, isUnlocked: existing.isUnlocked, progress: existing.progress };
+          }
+          return ach;
+        });
+
+        set({ achievements: mergedAchievements, isInitialized: true });
+      },
+
+      addPoints: (amount: number) => {
+        set((state) => ({ points: state.points + amount }));
+      },
+
+      completeTask: () => {
+        const state = get();
+        const pointsToAdd = currentConfig?.pointsPerAction ?? 15;
+
+        set({
+          totalTasksCompleted: state.totalTasksCompleted + 1,
+          points: state.points + pointsToAdd,
+        });
+
+        // Update streak
+        get().updateStreak();
+
+        // Check achievements
+        get().checkAchievements();
+      },
+
+      updateStreak: () => {
+        const state = get();
+        const now = new Date();
+        const lastDate = state.streak.lastActivityDate
+          ? new Date(state.streak.lastActivityDate)
+          : null;
+
+        let newStreak = state.streak.current;
+
+        if (!lastDate || !isSameDay(lastDate, now)) {
+          if (isStreakActive(state.streak.lastActivityDate)) {
+            newStreak = state.streak.current + 1;
+          } else {
+            newStreak = 1;
+          }
+        }
+
+        set({
+          streak: {
+            current: newStreak,
+            longest: Math.max(state.streak.longest, newStreak),
+            lastActivityDate: now.toISOString(),
+          },
+        });
+      },
+
+      checkAchievements: () => {
+        if (!currentConfig) return [];
+
+        const state = get();
+        const newlyUnlocked: Achievement[] = [];
+
+        const updatedAchievements = state.achievements.map((ach) => {
+          if (ach.isUnlocked) return ach;
+
+          const progress = updateAchievementProgress(
+            ach,
+            state.totalTasksCompleted,
+            state.streak.current
+          );
+
+          const shouldUnlock = checkAchievementUnlock(
+            ach,
+            state.totalTasksCompleted,
+            state.streak.current
+          );
+
+          if (shouldUnlock && !ach.isUnlocked) {
+            const unlocked = {
+              ...ach,
+              isUnlocked: true,
+              unlockedAt: new Date().toISOString(),
+              progress: 100,
+            };
+            newlyUnlocked.push(unlocked);
+            return unlocked;
+          }
+
+          return { ...ach, progress };
+        });
+
+        set({ achievements: updatedAchievements });
+        return newlyUnlocked;
+      },
+
+      reset: async () => {
+        set(DEFAULT_STATE);
+      },
+    }),
+    {
+      name: "gamification-storage",
+      storage: createJSONStorage(() => AsyncStorage),
+      partialize: (state) => ({
+        points: state.points,
+        totalTasksCompleted: state.totalTasksCompleted,
+        achievements: state.achievements,
+        streak: state.streak,
+      }),
+    }
+  )
+);

package/src/types/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Gamification Types
+ * Generic types for 100+ apps - NO app-specific code
+ */
+
+// Achievement Definition (provided by app)
+export interface AchievementDefinition {
+  id: string;
+  threshold: number;
+  type: "count" | "streak" | "milestone";
+}
+
+// Achievement State (internal)
+export interface Achievement extends AchievementDefinition {
+  isUnlocked: boolean;
+  unlockedAt?: string;
+  progress: number;
+}
+
+// Level Definition (provided by app)
+export interface LevelDefinition {
+  level: number;
+  minPoints: number;
+  maxPoints: number;
+}
+
+// Level State (internal)
+export interface LevelState {
+  currentLevel: number;
+  currentPoints: number;
+  pointsToNext: number;
+  progress: number;
+}
+
+// Streak State
+export interface StreakState {
+  current: number;
+  longest: number;
+  lastActivityDate: string | null;
+}
+
+// Gamification Config (provided by app via props)
+export interface GamificationConfig {
+  storageKey: string;
+  achievements: AchievementDefinition[];
+  levels: LevelDefinition[];
+  pointsPerAction?: number;
+  streakBonusMultiplier?: number;
+}
+
+// Store State
+export interface GamificationState {
+  points: number;
+  totalTasksCompleted: number;
+  achievements: Achievement[];
+  streak: StreakState;
+  isLoading: boolean;
+  isInitialized: boolean;
+}
+
+// Store Actions
+export interface GamificationActions {
+  initialize: (config: GamificationConfig) => Promise<void>;
+  addPoints: (amount: number) => void;
+  completeTask: () => void;
+  updateStreak: () => void;
+  checkAchievements: () => Achievement[];
+  reset: () => Promise<void>;
+}
+
+// Combined Store
+export type GamificationStore = GamificationState & GamificationActions;
+
+// UI Component Props (all text via props - NO hardcoded strings)
+export interface LevelProgressProps {
+  level: number;
+  points: number;
+  levelTitle: string;
+  pointsToNext: number;
+  progress: number;
+  showPoints?: boolean;
+}
+
+export interface AchievementCardProps {
+  title: string;
+  description: string;
+  icon: string;
+  isUnlocked: boolean;
+  progress: number;
+  threshold: number;
+}
+
+export interface StreakDisplayProps {
+  current: number;
+  longest: number;
+  streakLabel: string;
+  bestLabel: string;
+}
+
+export interface PointsBadgeProps {
+  points: number;
+  label?: string;
+}

package/src/utils/calculations.ts

@@ -0,0 +1,85 @@
+/**
+ * Gamification Calculations
+ * Pure utility functions - NO side effects
+ */
+
+import type { LevelDefinition, LevelState, Achievement, AchievementDefinition } from "../types";
+
+export const calculateLevel = (
+  points: number,
+  levels: LevelDefinition[]
+): LevelState => {
+  const sortedLevels = [...levels].sort((a, b) => a.minPoints - b.minPoints);
+
+  let currentLevelDef = sortedLevels[0];
+  let nextLevelDef: LevelDefinition | null = null;
+
+  for (let i = 0; i < sortedLevels.length; i++) {
+    if (points >= sortedLevels[i].minPoints) {
+      currentLevelDef = sortedLevels[i];
+      nextLevelDef = sortedLevels[i + 1] || null;
+    }
+  }
+
+  const pointsInLevel = points - currentLevelDef.minPoints;
+  const levelRange = nextLevelDef
+    ? nextLevelDef.minPoints - currentLevelDef.minPoints
+    : 100;
+  const progress = Math.min(100, (pointsInLevel / levelRange) * 100);
+  const pointsToNext = nextLevelDef
+    ? nextLevelDef.minPoints - points
+    : 0;
+
+  return {
+    currentLevel: currentLevelDef.level,
+    currentPoints: points,
+    pointsToNext,
+    progress,
+  };
+};
+
+export const checkAchievementUnlock = (
+  definition: AchievementDefinition,
+  tasksCompleted: number,
+  currentStreak: number
+): boolean => {
+  switch (definition.type) {
+    case "count":
+      return tasksCompleted >= definition.threshold;
+    case "streak":
+      return currentStreak >= definition.threshold;
+    case "milestone":
+      return tasksCompleted >= definition.threshold;
+    default:
+      return false;
+  }
+};
+
+export const updateAchievementProgress = (
+  definition: AchievementDefinition,
+  tasksCompleted: number,
+  currentStreak: number
+): number => {
+  const value = definition.type === "streak" ? currentStreak : tasksCompleted;
+  return Math.min(100, (value / definition.threshold) * 100);
+};
+
+export const isStreakActive = (lastActivityDate: string | null): boolean => {
+  if (!lastActivityDate) return false;
+
+  const last = new Date(lastActivityDate);
+  const now = new Date();
+  const diffDays = Math.floor(
+    (now.getTime() - last.getTime()) / (1000 * 60 * 60 * 24)
+  );
+
+  return diffDays <= 1;
+};
+
+export const isSameDay = (date1: Date, date2: Date): boolean => {
+  return (
+    date1.getFullYear() === date2.getFullYear() &&
+    date1.getMonth() === date2.getMonth() &&
+    date1.getDate() === date2.getDate()
+  );
+};

package/src/domain/entities/Achievement.ts

@@ -1,98 +0,0 @@
-/**
- * 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;
-}
-
-export type AchievementDifficulty = 'easy' | 'medium' | 'hard' | 'legendary';
-export type AchievementCategory = 'milestone' | 'challenge' | 'streak' | 'social' | 'special';
-
-/**
- * Factory function to create an achievement
- */
-export function createAchievement(
-  props: Omit<Achievement, 'id' | 'unlocked' | 'createdDate' | 'updatedDate'>
-): Achievement {
-  const now = new Date().toISOString();
-  return {
-    ...props,
-    id: `achievement-${Date.now()}-${Math.random().toString(36).substring(7)}`,
-    unlocked: props.progress >= props.requirement,
-    createdDate: now,
-    updatedDate: now,
-  };
-}
-
-/**
- * Check if achievement is complete
- */
-export function isAchievementComplete(achievement: Achievement): boolean {
-  return achievement.progress >= achievement.requirement;
-}
-
-/**
- * Calculate achievement progress percentage
- */
-export function calculateAchievementProgress(achievement: Achievement): number {
-  if (achievement.requirement === 0) return 0;
-  return Math.min(100, Math.round((achievement.progress / achievement.requirement) * 100));
-}
-
-/**
- * Get points for achievement difficulty/rarity
- */
-export function getPointsForDifficulty(rarity: Achievement['rarity'] | AchievementDifficulty): number {
-  const pointsMap: Record<string, number> = {
-    easy: 10,
-    medium: 25,
-    hard: 50,
-    legendary: 100,
-    common: 10,
-    rare: 25,
-    epic: 50,
-  };
-  return pointsMap[rarity || 'common'] || 10;
-}
-
-
-