Create hunt rating and review system

.kilo/kilo.jsonc

@@ -1,3 +1,4 @@
 {
+  "$schema": "https://app.kilo.ai/config.json",
   "snapshot": false
 }

app/api/v1/hunts/[id]/complete/route.ts

@@ -0,0 +1,39 @@
+import { NextResponse } from "next/server"
+import { readCompletions, writeCompletions } from "@/lib/reviews"
+
+/**
+ * POST /api/v1/hunts/[id]/complete
+ * Register that a player address has completed a hunt.
+ */
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params
+    const huntId = parseInt(id, 10)
+
+    if (isNaN(huntId)) {
+      return NextResponse.json({ error: "Invalid hunt ID" }, { status: 400 })
+    }
+
+    const body = await req.json().catch(() => ({}))
+    const { playerAddress } = body
+
+    if (!playerAddress || typeof playerAddress !== "string" || playerAddress.trim() === "") {
+      return NextResponse.json({ error: "Invalid player address" }, { status: 400 })
+    }
+
+    const completions = await readCompletions()
+    if (!completions[huntId]) {
+      completions[huntId] = {}
+    }
+    completions[huntId][playerAddress] = true
+
+    await writeCompletions(completions)
+
+    return NextResponse.json({ success: true })
+  } catch (error: any) {
+    return NextResponse.json({ error: error.message || "Failed to register completion" }, { status: 500 })
+  }
+}

app/api/v1/hunts/[id]/reviews/[reviewId]/moderate/route.ts

@@ -0,0 +1,66 @@
+import { NextResponse } from "next/server"
+import { readReviews, writeReviews } from "@/lib/reviews"
+import { getHuntById } from "@/lib/huntStore"
+
+/**
+ * POST /api/v1/hunts/[id]/reviews/[reviewId]/moderate
+ * Moderate a review. Action can be 'delete', 'flag', or 'unflag'.
+ * Enforces creator-only authorization.
+ */
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ id: string; reviewId: string }> }
+) {
+  try {
+    const { id, reviewId } = await params
+    const huntId = parseInt(id, 10)
+
+    if (isNaN(huntId)) {
+      return NextResponse.json({ error: "Invalid hunt ID" }, { status: 400 })
+    }
+
+    const body = await req.json().catch(() => ({}))
+    const { action, moderatorAddress } = body
+
+    if (!moderatorAddress || typeof moderatorAddress !== "string" || moderatorAddress.trim() === "") {
+      return NextResponse.json({ error: "Moderator address is required" }, { status: 400 })
+    }
+
+    if (!["delete", "flag", "unflag"].includes(action)) {
+      return NextResponse.json({ error: "Invalid action. Must be 'delete', 'flag', or 'unflag'" }, { status: 400 })
+    }
+
+    // 1. Authorize: Only the hunt creator can moderate reviews
+    const hunt = getHuntById(huntId)
+    if (!hunt) {
+      return NextResponse.json({ error: "Hunt not found" }, { status: 404 })
+    }
+
+    const isCreator = !hunt.creator || hunt.creator === moderatorAddress
+    if (!isCreator) {
+      return NextResponse.json({ error: "Unauthorized: only the hunt creator can moderate reviews" }, { status: 403 })
+    }
+
+    // 2. Perform moderation on the target review
+    const reviews = await readReviews()
+    const review = reviews.find((r) => r.id === reviewId && r.huntId === huntId)
+
+    if (!review) {
+      return NextResponse.json({ error: "Review not found" }, { status: 404 })
+    }
+
+    if (action === "delete") {
+      review.moderated = true
+    } else if (action === "flag") {
+      review.flagged = true
+    } else if (action === "unflag") {
+      review.flagged = false
+    }
+
+    await writeReviews(reviews)
+
+    return NextResponse.json({ success: true, data: review })
+  } catch (error: any) {
+    return NextResponse.json({ error: error.message || "Failed to moderate review" }, { status: 500 })
+  }
+}

app/api/v1/hunts/[id]/reviews/route.ts

@@ -0,0 +1,95 @@
+import { NextResponse } from "next/server"
+import { readReviews, writeReviews, readCompletions } from "@/lib/reviews"
+import type { HuntReview } from "@/lib/types"
+
+/**
+ * GET /api/v1/hunts/[id]/reviews
+ * Get all active (non-moderated) reviews for a specific hunt.
+ */
+export async function GET(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params
+    const huntId = parseInt(id, 10)
+
+    if (isNaN(huntId)) {
+      return NextResponse.json({ error: "Invalid hunt ID" }, { status: 400 })
+    }
+
+    const reviews = await readReviews()
+    const huntReviews = reviews.filter((r) => r.huntId === huntId && !r.moderated)
+
+    return NextResponse.json({ data: huntReviews })
+  } catch (error: any) {
+    return NextResponse.json({ error: error.message || "Failed to retrieve reviews" }, { status: 500 })
+  }
+}
+
+/**
+ * POST /api/v1/hunts/[id]/reviews
+ * Submit a review for a specific hunt.
+ * Enforces:
+ * - One review per completed hunt per wallet.
+ * - Player address validation.
+ * - Star rating between 1 and 5.
+ * - Verification that player has completed the hunt.
+ */
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params
+    const huntId = parseInt(id, 10)
+
+    if (isNaN(huntId)) {
+      return NextResponse.json({ error: "Invalid hunt ID" }, { status: 400 })
+    }
+
+    const body = await req.json().catch(() => ({}))
+    const { playerAddress, rating, text } = body
+
+    if (!playerAddress || typeof playerAddress !== "string" || playerAddress.trim() === "") {
+      return NextResponse.json({ error: "Player address is required" }, { status: 400 })
+    }
+
+    const ratingVal = parseInt(rating, 10)
+    if (isNaN(ratingVal) || ratingVal < 1 || ratingVal > 5) {
+      return NextResponse.json({ error: "Rating must be a number between 1 and 5" }, { status: 400 })
+    }
+
+    // 1. Enforce hunt completion verification
+    const completions = await readCompletions()
+    const completed = completions[huntId]?.[playerAddress] === true
+    if (!completed) {
+      return NextResponse.json({ error: "You must complete this hunt before submitting a review" }, { status: 403 })
+    }
+
+    // 2. Prevent duplicate reviews from the same wallet
+    const reviews = await readReviews()
+    const duplicate = reviews.some(
+      (r) => r.huntId === huntId && r.playerAddress.toLowerCase() === playerAddress.toLowerCase() && !r.moderated
+    )
+    if (duplicate) {
+      return NextResponse.json({ error: "You have already reviewed this hunt" }, { status: 400 })
+    }
+
+    const newReview: HuntReview = {
+      id: Math.random().toString(36).substring(2, 15) + Date.now().toString(36),
+      huntId,
+      playerAddress,
+      rating: ratingVal,
+      text: typeof text === "string" ? text.trim() : undefined,
+      createdAt: Date.now(),
+    }
+
+    reviews.push(newReview)
+    await writeReviews(reviews)
+
+    return NextResponse.json({ data: newReview })
+  } catch (error: any) {
+    return NextResponse.json({ error: error.message || "Failed to submit review" }, { status: 500 })
+  }
+}

app/hunt/[id]/share.tsx

@@ -6,6 +6,7 @@ import { QrCode, Trophy } from "lucide-react";
 import { QrCodeModal } from "@/components/QrCodeModal";
 import { PlayGame } from "@/components/PlayGame";
 import { GameCompleteModal } from "@/components/GameCompleteModal";
+import { HuntReviewsSection } from "@/components/HuntReviewsSection";
 import type { StoredHunt } from "@/lib/types";
 import { updateHuntStatus } from "@/lib/huntStore";
 import { useRouter, useSearchParams } from "next/navigation";
@@ -319,6 +320,10 @@ export default function HuntShare({ hunt }: HuntDetailProps) {
           />
         </PlayInterfaceGuard>
       )}
+
+      <div className="mt-12 pt-8 border-t border-white/10">
+        <HuntReviewsSection huntId={hunt.id} creatorAddress={hunt.creator} />
+      </div>
     </div>
   );
 }

app/page.tsx

@@ -25,6 +25,7 @@ import { usePlayerCounts } from "@/hooks/usePlayerCounts"
 import { useRecentlyCompleted } from "@/hooks/useRecentlyCompleted"
 import type { PlayerCountResult } from "@/lib/types"
 import { queryCachePolicy, queryKeys } from "@/lib/queryKeys"
+import { StarRating } from "@/components/StarRating"
 
 const OnboardingTour = dynamic(() => import("@/components/OnboardingTour"), {
   ssr: false,
@@ -117,6 +118,7 @@ function ActiveHuntCard({
             </span>
           )}
         </div>
+        <StarRating rating={hunt.averageRating} count={hunt.reviewCount} className="mb-2" />
         <CardDescription className="text-sm text-slate-600 dark:text-slate-400 mb-4 line-clamp-3">
           {hunt.description}
         </CardDescription>
@@ -328,6 +330,7 @@ function VirtualizedInactiveHuntsGrid({
                       <CardTitle className="text-lg font-semibold mb-2 line-clamp-2">
                         {hunt.title}
                       </CardTitle>
+                      <StarRating rating={hunt.averageRating} count={hunt.reviewCount} className="mb-2" />
                       <CardDescription className="text-sm text-slate-600 mb-4 line-clamp-3">
                         {hunt.description}
                       </CardDescription>
@@ -368,7 +371,7 @@ export default function GameArcade() {
   const [activeTab, setActiveTab] = useState<"leaderboard" | "none">("none")
   const [rewardFilter, setRewardFilter] = useState<"all" | "XLM" | "NFT" | "Both">("all")
   const [statusFilter, setStatusFilter] = useState<"all" | "Active" | "Completed">("Active")
-  const [sortBy, setSortBy] = useState<"newest" | "oldest" | "clues-high" | "clues-low">("newest")
+  const [sortBy, setSortBy] = useState<"newest" | "oldest" | "clues-high" | "clues-low" | "rating-high">("newest")
 
   const isLoadedRef = useRef(false)
 
@@ -832,12 +835,13 @@ export default function GameArcade() {
                 <select
                   value={sortBy}
                   onChange={(e) =>
-                    setSortBy(e.target.value as "newest" | "oldest" | "clues-high" | "clues-low")
+                    setSortBy(e.target.value as "newest" | "oldest" | "clues-high" | "clues-low" | "rating-high")
                   }
                   className="h-10 bg-slate-50 dark:bg-slate-800 border border-slate-200 dark:border-slate-700 rounded-xl px-3 text-xs font-bold text-slate-700 dark:text-slate-300 focus:outline-none focus:ring-2 focus:ring-[#3737A4]/50 cursor-pointer"
                 >
                   <option value="newest">Newest First</option>
                   <option value="oldest">Oldest First</option>
+                  <option value="rating-high">Highest Rated</option>
                   <option value="clues-high">Most Clues</option>
                   <option value="clues-low">Fewest Clues</option>
                 </select>

components/FeaturedHunts.tsx

@@ -8,6 +8,7 @@ import { Skeleton } from "@/components/ui/skeleton"
 import { HuntCoverImage } from "@/components/HuntCoverImage"
 import { queryCachePolicy, queryKeys } from "@/lib/queryKeys"
 import { cn } from "@/lib/utils"
+import { StarRating } from "@/components/StarRating"
 
 function timeRemaining(endTime?: number): string {
   if (!endTime) return ""
@@ -75,6 +76,7 @@ export function FeaturedHunts() {
                 <h3 className="text-lg font-bold text-slate-900 dark:text-white mb-1 pr-16 line-clamp-1">
                   {hunt.title}
                 </h3>
+                <StarRating rating={hunt.averageRating} count={hunt.reviewCount} className="mb-2" />
                 <HuntCoverImage
                   src={hunt.coverImageCid}
                   alt={`${hunt.title} cover`}