feat: Add endpoint and service method to retrieve top users by various metrics

app/services/dashboard.py

@@ -5,6 +5,7 @@ from typing import Any
 
 from app.core.logging import get_logger
 from app.repositories.sound import SoundRepository
+from app.repositories.user import UserRepository
 
 logger = get_logger(__name__)
 
@@ -12,9 +13,10 @@ logger = get_logger(__name__)
 class DashboardService:
     """Service for dashboard statistics and analytics."""
 
-    def __init__(self, sound_repository: SoundRepository) -> None:
+    def __init__(self, sound_repository: SoundRepository, user_repository: UserRepository) -> None:
         """Initialize the dashboard service."""
         self.sound_repository = sound_repository
+        self.user_repository = user_repository
 
     async def get_soundboard_statistics(self) -> dict[str, Any]:
         """Get comprehensive soundboard statistics."""
@@ -100,6 +102,40 @@ class DashboardService:
             logger.exception("Failed to get TTS statistics")
             raise
 
+    async def get_top_users(
+        self,
+        metric_type: str,
+        period: str = "all_time",
+        limit: int = 10,
+    ) -> list[dict[str, Any]]:
+        """Get top users by different metrics for a specific period."""
+        try:
+            # Calculate the date filter based on period
+            date_filter = self._get_date_filter(period)
+
+            # Get top users from repository
+            top_users = await self.user_repository.get_top_users(
+                metric_type=metric_type,
+                date_filter=date_filter,
+                limit=limit,
+            )
+
+            return [
+                {
+                    "id": user["id"],
+                    "name": user["name"],
+                    "count": user["count"],
+                }
+                for user in top_users
+            ]
+        except Exception:
+            logger.exception(
+                "Failed to get top users for metric=%s, period=%s",
+                metric_type,
+                period,
+            )
+            raise
+
     def _get_date_filter(self, period: str) -> datetime | None:  # noqa: PLR0911
         """Calculate the date filter based on the period."""
         now = datetime.now(UTC)