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

app/api/v1/dashboard.py

@@ -56,6 +56,41 @@ async def get_tts_statistics(
         ) from e
 
 
+@router.get("/top-users")
+async def get_top_users(
+    _current_user: Annotated[User, Depends(get_current_user)],
+    dashboard_service: Annotated[DashboardService, Depends(get_dashboard_service)],
+    metric_type: Annotated[
+        str,
+        Query(
+            description="Metric type: sounds_played, credits_used, tracks_added, tts_added, playlists_created",
+        ),
+    ],
+    period: Annotated[
+        str,
+        Query(
+            description="Time period (today, 1_day, 1_week, 1_month, 1_year, all_time)",
+        ),
+    ] = "all_time",
+    limit: Annotated[
+        int,
+        Query(description="Number of top users to return", ge=1, le=100),
+    ] = 10,
+) -> list[dict[str, Any]]:
+    """Get top users by metric for a specific period."""
+    try:
+        return await dashboard_service.get_top_users(
+            metric_type=metric_type,
+            period=period,
+            limit=limit,
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch top users: {e!s}",
+        ) from e
+
+
 @router.get("/top-sounds")
 async def get_top_sounds(
     _current_user: Annotated[User, Depends(get_current_user)],