fix: resolve race conditions in gamification XP/streak calculation (#178)

- stats POST: Wrap XP + streak + badge computation in Firestore
  runTransaction for atomic read-compute-write. Two concurrent requests
  can no longer both read stale XP and overwrite each other's increment.
- stats GET: Wrap streak update (daysDiff check) in runTransaction so
  concurrent GET requests from multiple tabs don't double-increment streak.
- award-badge: Replace read-check-write pattern with FieldValue.arrayUnion
  which is inherently idempotent — concurrent badge awards are safe.
- daily-quests updateProgress: Wrap quest progress increment in
  runTransaction to prevent lost increments from rapid task completions.
- daily-quests claim: Wrap claim in runTransaction to prevent double-claim.
  XP award uses FieldValue.increment() for atomic addition.
- fix-streak: Wrap conditional streak fix in runTransaction.
- Add idempotency keys: Client generates unique key per awardXP call,
  server stores result in idempotency collection and returns cached
  result on duplicate requests (network retry protection).
- Use FieldValue.arrayUnion for badge updates in stats transaction to
  prevent duplicate badge entries without manual dedup logic.

Author: Sai-Emani25

src/app/api/gamification/award-badge/route.js

@@ -1,7 +1,7 @@
 import { NextResponse } from "next/server";
-import { adminDb } from "@/lib/firebase-admin";
+import { adminDb, FieldValue } from "@/lib/firebase-admin";
 
-// POST - Award a badge to user
+// POST - Award a badge to user (idempotent via FieldValue.arrayUnion)
 export async function POST(request) {
   try {
     const { userId, badgeId } = await request.json();
@@ -27,18 +27,14 @@ export async function POST(request) {
       return NextResponse.json({ success: true, badges: [badgeId] });
     }
 
-    const stats = userDoc.data();
-    const currentBadges = stats.badges || [];
+    // Use arrayUnion — inherently idempotent, no race condition
+    await userRef.update({ badges: FieldValue.arrayUnion(badgeId) });
 
-    // Don't add duplicate badges
-    if (currentBadges.includes(badgeId)) {
-      return NextResponse.json({ success: true, message: "Badge already earned", badges: currentBadges });
-    }
-
-    const newBadges = [...currentBadges, badgeId];
-    await userRef.update({ badges: newBadges });
+    // Read back to return current badges
+    const updatedDoc = await userRef.get();
+    const badges = updatedDoc.data()?.badges || [];
 
-    return NextResponse.json({ success: true, badges: newBadges });
+    return NextResponse.json({ success: true, badges });
   } catch (error) {
     console.error("Error awarding badge:", error);
     return NextResponse.json({ error: "Failed to award badge" }, { status: 500 });

src/app/api/gamification/daily-quests/route.js

@@ -1,5 +1,5 @@
 import { NextResponse } from "next/server";
-import { adminDb } from "@/lib/firebase-admin";
+import { adminDb, FieldValue } from "@/lib/firebase-admin";
 
 // Daily quest templates - rotates based on day
 const QUEST_TEMPLATES = [
@@ -136,68 +136,86 @@ export async function POST(request) {
     let userProgress = userQuestsDoc.data();
 
     if (action === "updateProgress") {
-      // Update progress for quests matching the progress type
-      userProgress.quests = userProgress.quests.map(quest => {
-        if (quest.type === progressType && !quest.completed) {
-          const newProgress = Math.min(quest.progress + (progressIncrement || 1), quest.target);
-          return {
-            ...quest,
-            progress: newProgress,
-            completed: newProgress >= quest.target,
-          };
-        }
-        return quest;
+      // Use a transaction to prevent race conditions on progress updates
+      const updatedQuests = await adminDb.runTransaction(async (transaction) => {
+        const doc = await transaction.get(userQuestsRef);
+        if (!doc.exists) throw new Error("No quests found");
+
+        const data = doc.data();
+        const updatedQuestList = data.quests.map((quest) => {
+          if (quest.type === progressType && !quest.completed) {
+            const newProgress = Math.min(
+              quest.progress + (progressIncrement || 1),
+              quest.target
+            );
+            return {
+              ...quest,
+              progress: newProgress,
+              completed: newProgress >= quest.target,
+            };
+          }
+          return quest;
+        });
+
+        transaction.update(userQuestsRef, { quests: updatedQuestList });
+        return updatedQuestList;
       });
 
-      await userQuestsRef.update({ quests: userProgress.quests });
-
       return NextResponse.json({
         success: true,
-        quests: userProgress.quests,
+        quests: updatedQuests,
       });
     }
 
     if (action === "claim") {
-      // Find and claim the quest reward
-      const questIndex = userProgress.quests.findIndex(q => q.id === questId);
+      // Use a transaction to prevent double-claim race conditions
+      const claimResult = await adminDb.runTransaction(async (transaction) => {
+        const doc = await transaction.get(userQuestsRef);
+        if (!doc.exists) throw new Error("No quests found");
 
-      if (questIndex === -1) {
-        return NextResponse.json({ error: "Quest not found" }, { status: 404 });
-      }
+        const data = doc.data();
+        const questIndex = data.quests.findIndex((q) => q.id === questId);
 
-      const quest = userProgress.quests[questIndex];
+        if (questIndex === -1) throw new Error("Quest not found");
 
-      if (!quest.completed) {
-        return NextResponse.json({ error: "Quest not completed" }, { status: 400 });
-      }
+        const quest = data.quests[questIndex];
 
-      if (quest.claimed) {
-        return NextResponse.json({ error: "Already claimed" }, { status: 400 });
-      }
+        if (!quest.completed) throw new Error("Quest not completed");
+        if (quest.claimed) throw new Error("Already claimed");
 
-      // Mark as claimed
-      userProgress.quests[questIndex].claimed = true;
-      userProgress.totalXPEarned = (userProgress.totalXPEarned || 0) + quest.xpReward;
+        // Mark as claimed within transaction
+        data.quests[questIndex].claimed = true;
+        const newTotalXP = (data.totalXPEarned || 0) + quest.xpReward;
 
-      await userQuestsRef.update({
-        quests: userProgress.quests,
-        totalXPEarned: userProgress.totalXPEarned,
-      });
+        transaction.update(userQuestsRef, {
+          quests: data.quests,
+          totalXPEarned: newTotalXP,
+        });
 
-      // Award XP to user's main stats
-      const userStatsRef = adminDb.collection("users").doc(userId).collection("gamification").doc("stats");
-      const statsDoc = await userStatsRef.get();
-      const currentXP = statsDoc.exists ? (statsDoc.data().xp || 0) : 0;
+        return { quest: data.quests[questIndex], xpReward: quest.xpReward };
+      });
 
-      await userStatsRef.set({
-        xp: currentXP + quest.xpReward,
-        lastUpdated: new Date().toISOString(),
-      }, { merge: true });
+      // Award XP to user's main stats using FieldValue.increment (atomic)
+      const userStatsRef = adminDb
+        .collection("users")
+        .doc(userId)
+        .collection("gamification")
+        .doc("stats");
+
+      await userStatsRef.set(
+        {
+          xp: FieldValue.increment(claimResult.xpReward),
+          lastUpdated: new Date().toISOString(),
+        },
+        { merge: true }
+      );
 
       return NextResponse.json({
         success: true,
-        xpAwarded: quest.xpReward,
-        quest: userProgress.quests[questIndex],
+        xpAwarded: claimResult.xpReward,
+        quest: claimResult.quest,
+      });
+    }
       });
     }
 

src/app/api/gamification/fix-streak/route.js

@@ -10,34 +10,45 @@ export async function POST(request) {
     }
 
     const userRef = adminDb.collection("gamification").doc(userId);
-    const userDoc = await userRef.get();
 
-    if (!userDoc.exists) {
-      return NextResponse.json({ error: "User not found" }, { status: 404 });
-    }
+    // Use a transaction to prevent race conditions on streak fix
+    const result = await adminDb.runTransaction(async (transaction) => {
+      const userDoc = await transaction.get(userRef);
 
-    const stats = userDoc.data();
+      if (!userDoc.exists) {
+        throw new Error("User not found");
+      }
 
-    // If streak is 0, set it to 1 (they're using it today)
-    if (stats.streak === 0) {
-      await userRef.update({
-        streak: 1,
-        lastActive: new Date().toISOString(),
-      });
+      const stats = userDoc.data();
+
+      if (stats.streak === 0) {
+        transaction.update(userRef, {
+          streak: 1,
+          lastActive: new Date().toISOString(),
+        });
+        return { fixed: true, newStreak: 1 };
+      }
 
+      return { fixed: false, currentStreak: stats.streak };
+    });
+
+    if (result.fixed) {
       return NextResponse.json({
         success: true,
         message: "Streak fixed to 1",
-        newStreak: 1,
+        newStreak: result.newStreak,
       });
     }
 
     return NextResponse.json({
       success: true,
       message: "Streak already set",
-      currentStreak: stats.streak,
+      currentStreak: result.currentStreak,
     });
   } catch (error) {
+    if (error.message === "User not found") {
+      return NextResponse.json({ error: "User not found" }, { status: 404 });
+    }
     console.error("Error fixing streak:", error);
     return NextResponse.json({ error: "Failed to fix streak" }, { status: 500 });
   }