@umituz/react-native-gamification 1.1.0 → 1.2.0

package/LICENSE

@@ -20,3 +20,5 @@ 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

@@ -274,3 +274,5 @@ MIT
 
 Ümit UZ <umit@umituz.com>
 
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-gamification",
-  "version": "1.1.0",
+  "version": "1.2.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",
@@ -53,3 +53,5 @@
     "LICENSE"
   ]
 }
+
+

package/src/domain/entities/Achievement.ts

@@ -44,3 +44,55 @@ export interface AchievementProgress {
   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;
+}
+
+
+

package/src/domain/entities/Leaderboard.ts

@@ -43,3 +43,59 @@ export interface LeaderboardRanking {
   belowUsers: number; // Number of users below
 }
 
+export type LeaderboardCategory = 'points' | 'achievements' | 'streaks' | 'activity';
+
+/**
+ * Factory function to create leaderboard entry
+ */
+export function createLeaderboardEntry(
+  props: Omit<LeaderboardEntry, 'id' | 'createdDate' | 'updatedDate' | 'change'> & { previousRank?: number }
+): LeaderboardEntry {
+  const now = new Date().toISOString();
+  const change = props.previousRank ? props.previousRank - props.rank : 0;
+  
+  return {
+    ...props,
+    id: `entry-${Date.now()}-${Math.random().toString(36).substring(7)}`,
+    createdDate: now,
+    updatedDate: now,
+    metadata: {
+      ...props.metadata,
+      change,
+    },
+  };
+}
+
+/**
+ * Calculate rank change indicator
+ */
+export function getRankChangeIndicator(change: number): '↑' | '↓' | '=' {
+  if (change > 0) return '↑'; // Improved (moved up)
+  if (change < 0) return '↓'; // Declined (moved down)
+  return '='; // No change
+}
+
+/**
+ * Get top N entries from leaderboard
+ */
+export function getTopEntries(
+  leaderboard: Leaderboard,
+  limit: number = 10
+): LeaderboardEntry[] {
+  return leaderboard.entries
+    .sort((a, b) => a.rank - b.rank)
+    .slice(0, limit);
+}
+
+/**
+ * Find user's position in leaderboard
+ */
+export function findUserRank(
+  leaderboard: Leaderboard,
+  userId: string
+): LeaderboardEntry | null {
+  return leaderboard.entries.find((entry) => entry.userId === userId) || null;
+}
+
+
+

package/src/domain/entities/Level.ts

@@ -36,3 +36,5 @@ export interface LevelProgress {
   canLevelUp: boolean;
 }
 
+
+

package/src/domain/entities/Point.ts

@@ -36,3 +36,5 @@ export interface PointTransaction {
   createdDate: string;
 }
 
+
+

package/src/domain/entities/Progress.ts

@@ -39,3 +39,5 @@ export interface ProgressMilestone {
   metadata?: Record<string, any>;
 }
 
+
+

package/src/domain/entities/Reward.ts

@@ -4,6 +4,8 @@
  * Represents rewards in the gamification system
  */
 
+import type { PointTransaction } from './Point';
+
 export interface Reward {
   id: string;
   userId: string;
@@ -46,3 +48,84 @@ export interface RewardClaim {
   metadata?: Record<string, any>;
 }
 
+export type RewardRarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
+
+/**
+ * Factory function to create reward
+ */
+export function createReward(
+  props: Omit<Reward, 'id' | 'unlocked' | 'claimed' | 'createdDate' | 'updatedDate'>
+): Reward {
+  const now = new Date().toISOString();
+  return {
+    ...props,
+    id: `reward-${Date.now()}-${Math.random().toString(36).substring(7)}`,
+    unlocked: false,
+    claimed: false,
+    createdDate: now,
+    updatedDate: now,
+  };
+}
+
+/**
+ * Factory function to create points transaction
+ */
+export function createPointsTransaction(
+  userId: string,
+  amount: number,
+  type: 'earn' | 'spend' | 'bonus',
+  source: string,
+  description: string
+): PointTransaction {
+  const now = new Date().toISOString();
+  return {
+    id: `transaction-${Date.now()}-${Math.random().toString(36).substring(7)}`,
+    userId,
+    amount: type === 'spend' ? -Math.abs(amount) : Math.abs(amount),
+    source,
+    description,
+    balance: 0, // Will be calculated by repository
+    createdDate: now,
+  };
+}
+
+/**
+ * Calculate user level from total experience/points
+ */
+export function calculateLevel(totalPoints: number): number {
+  // Simple level formula: level = floor(sqrt(points / 100))
+  return Math.floor(Math.sqrt(totalPoints / 100));
+}
+
+/**
+ * Calculate points needed for next level
+ */
+export function calculateNextLevelPoints(currentLevel: number): number {
+  const nextLevel = currentLevel + 1;
+  return Math.pow(nextLevel, 2) * 100;
+}
+
+/**
+ * Check if reward is expired
+ */
+export function isRewardExpired(reward: Reward): boolean {
+  if (!reward.expiresAt) return false;
+  return new Date() > new Date(reward.expiresAt);
+}
+
+/**
+ * Get points value for rarity
+ */
+export function getPointsForRarity(rarity: RewardRarity): number {
+  const pointsMap: Record<RewardRarity, number> = {
+    common: 50,
+    uncommon: 100,
+    rare: 250,
+    epic: 500,
+    legendary: 1000,
+  };
+  return pointsMap[rarity];
+}
+
+
+

package/src/domain/entities/Streak.ts

@@ -36,3 +36,119 @@ export interface StreakProgress {
   nextMilestone?: number; // Next milestone value
 }
 
+export interface StreakMilestone {
+  days: number;
+  name: string;
+  reward: number; // Points awarded
+  achieved: boolean;
+}
+
+/**
+ * Factory function to create streak entity
+ */
+export function createStreakEntity(userId: string, type: string): Streak {
+  const now = new Date().toISOString();
+  return {
+    id: `streak-${Date.now()}-${Math.random().toString(36).substring(7)}`,
+    userId,
+    type,
+    currentStreak: 0,
+    longestStreak: 0,
+    lastActivityDate: now,
+    isActive: false,
+    createdDate: now,
+    updatedDate: now,
+  };
+}
+
+/**
+ * Check if streak should continue (activity within last 24 hours)
+ */
+export function isStreakActive(streak: Streak): boolean {
+  const now = new Date();
+  const lastActivity = new Date(streak.lastActivityDate);
+  const hoursSinceLastActivity = (now.getTime() - lastActivity.getTime()) / (1000 * 60 * 60);
+
+  return hoursSinceLastActivity <= 24;
+}
+
+/**
+ * Check if streak is broken (no activity for more than 48 hours)
+ */
+export function isStreakBroken(streak: Streak): boolean {
+  const now = new Date();
+  const lastActivity = new Date(streak.lastActivityDate);
+  const hoursSinceLastActivity = (now.getTime() - lastActivity.getTime()) / (1000 * 60 * 60);
+
+  return hoursSinceLastActivity > 48;
+}
+
+/**
+ * Update streak with new activity
+ */
+export function updateStreakWithActivity(streak: Streak): Streak {
+  const now = new Date().toISOString();
+
+  // Check if streak is broken
+  if (isStreakBroken(streak)) {
+    return {
+      ...streak,
+      currentStreak: 1,
+      longestStreak: Math.max(1, streak.longestStreak),
+      lastActivityDate: now,
+      isActive: true,
+      updatedDate: now,
+    };
+  }
+
+  // Continue streak
+  const newStreak = streak.currentStreak + 1;
+  const newLongestStreak = Math.max(newStreak, streak.longestStreak);
+
+  return {
+    ...streak,
+    currentStreak: newStreak,
+    longestStreak: newLongestStreak,
+    lastActivityDate: now,
+    isActive: true,
+    updatedDate: now,
+  };
+}
+
+/**
+ * Get streak milestones
+ */
+export function getStreakMilestones(currentStreak: number): StreakMilestone[] {
+  const milestones: StreakMilestone[] = [
+    { days: 7, name: 'Week Warrior', reward: 50, achieved: currentStreak >= 7 },
+    { days: 14, name: 'Fortnight Fighter', reward: 100, achieved: currentStreak >= 14 },
+    { days: 30, name: 'Monthly Master', reward: 250, achieved: currentStreak >= 30 },
+    { days: 60, name: 'Consistency Champion', reward: 500, achieved: currentStreak >= 60 },
+    { days: 100, name: 'Century Star', reward: 1000, achieved: currentStreak >= 100 },
+    { days: 365, name: 'Yearly Legend', reward: 5000, achieved: currentStreak >= 365 },
+  ];
+
+  return milestones;
+}
+
+/**
+ * Get next milestone for motivation
+ */
+export function getNextMilestone(currentStreak: number): StreakMilestone | null {
+  const milestones = getStreakMilestones(currentStreak);
+  return milestones.find((m) => !m.achieved) || null;
+}
+
+/**
+ * Calculate days until streak break
+ */
+export function getDaysUntilStreakBreak(streak: Streak): number {
+  const now = new Date();
+  const lastActivity = new Date(streak.lastActivityDate);
+  const hoursRemaining = 48 - (now.getTime() - lastActivity.getTime()) / (1000 * 60 * 60);
+
+  return Math.max(0, Math.ceil(hoursRemaining / 24));
+}
+
+
+

package/src/domain/repositories/IGamificationRepository.ts

@@ -231,3 +231,5 @@ export interface IGamificationRepository {
   updateProgress(update: ProgressUpdate): Promise<GamificationResult<Progress>>;
 }
 
+
+

package/src/index.ts

@@ -15,6 +15,14 @@ export type {
   Achievement,
   AchievementDefinition,
   AchievementProgress,
+  AchievementDifficulty,
+  AchievementCategory,
+} from "./domain/entities/Achievement";
+export {
+  createAchievement,
+  isAchievementComplete,
+  calculateAchievementProgress,
+  getPointsForDifficulty,
 } from "./domain/entities/Achievement";
 
 export type {
@@ -33,18 +41,44 @@ export type {
   Streak,
   StreakDefinition,
   StreakProgress,
+  StreakMilestone,
+} from "./domain/entities/Streak";
+export {
+  createStreakEntity,
+  isStreakActive,
+  isStreakBroken,
+  updateStreakWithActivity,
+  getStreakMilestones,
+  getNextMilestone,
+  getDaysUntilStreakBreak,
 } from "./domain/entities/Streak";
 
 export type {
   Leaderboard,
   LeaderboardEntry,
   LeaderboardRanking,
+  LeaderboardCategory,
+} from "./domain/entities/Leaderboard";
+export {
+  createLeaderboardEntry,
+  getRankChangeIndicator,
+  getTopEntries,
+  findUserRank,
 } from "./domain/entities/Leaderboard";
 
 export type {
   Reward,
   RewardDefinition,
   RewardClaim,
+  RewardRarity,
+} from "./domain/entities/Reward";
+export {
+  createReward,
+  createPointsTransaction,
+  calculateLevel,
+  calculateNextLevelPoints,
+  isRewardExpired,
+  getPointsForRarity,
 } from "./domain/entities/Reward";
 
 export type {
@@ -87,3 +121,5 @@ export { useStreaks } from "./presentation/hooks/useStreaks";
 export { useRewards } from "./presentation/hooks/useRewards";
 export { useProgress } from "./presentation/hooks/useProgress";
 
+
+

package/src/infrastructure/repositories/StorageGamificationRepository.ts

@@ -730,3 +730,5 @@ class StorageGamificationRepository implements IGamificationRepository {
 
 export const storageGamificationRepository = new StorageGamificationRepository();
 
+
+

package/src/infrastructure/storage/GamificationStore.ts

@@ -346,3 +346,5 @@ export const useGamificationStore = create<GamificationStore>((set, get) => ({
   },
 }));
 
+
+

package/src/presentation/hooks/useAchievements.ts

@@ -33,3 +33,5 @@ export const useAchievements = () => {
   };
 };
 
+
+

package/src/presentation/hooks/useGamification.ts

@@ -89,3 +89,5 @@ export const useGamificationRepository = (repository: IGamificationRepository |
   }, [repository]);
 };
 
+
+

package/src/presentation/hooks/useLevel.ts

@@ -35,3 +35,5 @@ export const useLevel = () => {
   };
 };
 
+
+

package/src/presentation/hooks/usePoints.ts

@@ -32,3 +32,5 @@ export const usePoints = () => {
   };
 };
 
+
+

package/src/presentation/hooks/useProgress.ts

@@ -29,3 +29,5 @@ export const useProgress = () => {
   };
 };
 
+
+

package/src/presentation/hooks/useRewards.ts

@@ -39,3 +39,5 @@ export const useRewards = () => {
   };
 };
 
+
+

package/src/presentation/hooks/useStreaks.ts

@@ -32,3 +32,5 @@ export const useStreaks = () => {
   };
 };
 
+
+