feat: add /stats command showing karma given, received, and top users

Author: PenguinDevs

src/backend/tables/db_karma_transaction.py

@@ -79,4 +79,59 @@ async def oldest_transaction_to_user_since(
             return result.one()
 
 
+    async def total_given_by(self, user_id: int) -> int:
+        """Total karma given out by a user (all time)."""
+        async with self._session() as s:
+            result = await s.exec(
+                select(func.coalesce(func.sum(KarmaTransaction.amount), 0)).where(
+                    KarmaTransaction.performed_by == user_id,
+                )
+            )
+            return result.one()
+
+    async def total_received_by(self, user_id: int) -> int:
+        """Total karma received by a user (all time)."""
+        async with self._session() as s:
+            result = await s.exec(
+                select(func.coalesce(func.sum(KarmaTransaction.amount), 0)).where(
+                    KarmaTransaction.recipient_id == user_id,
+                )
+            )
+            return result.one()
+
+    async def top_given_to(
+        self, user_id: int, limit: int = 5
+    ) -> list[tuple[int, int]]:
+        """Top recipients of karma from this user. Returns [(recipient_id, total), ...]."""
+        async with self._session() as s:
+            result = await s.exec(
+                select(
+                    KarmaTransaction.recipient_id,
+                    func.sum(KarmaTransaction.amount).label("total"),
+                )
+                .where(KarmaTransaction.performed_by == user_id)
+                .group_by(KarmaTransaction.recipient_id)
+                .order_by(func.sum(KarmaTransaction.amount).desc())
+                .limit(limit)
+            )
+            return list(result.all())
+
+    async def top_received_from(
+        self, user_id: int, limit: int = 5
+    ) -> list[tuple[int, int]]:
+        """Top givers of karma to this user. Returns [(performed_by, total), ...]."""
+        async with self._session() as s:
+            result = await s.exec(
+                select(
+                    KarmaTransaction.performed_by,
+                    func.sum(KarmaTransaction.amount).label("total"),
+                )
+                .where(KarmaTransaction.recipient_id == user_id)
+                .group_by(KarmaTransaction.performed_by)
+                .order_by(func.sum(KarmaTransaction.amount).desc())
+                .limit(limit)
+            )
+            return list(result.all())
+
+
 karma_transaction = KarmaTransactionDB()

src/cogs/commands/karma.py

@@ -175,6 +175,52 @@ async def team_leaderboard(
         else:
             await interaction.followup.send(embed=embed)
 
+    @app_commands.command(name="stats", description="View your karma stats")
+    @app_commands.describe(member="User to view stats for (defaults to yourself)")
+    @has_karma_role()
+    async def stats(
+        self, interaction: discord.Interaction, member: discord.Member | None = None
+    ) -> None:
+        await interaction.response.defer()
+        target = member or interaction.user
+
+        total_given = await karma_transaction.total_given_by(target.id)
+        total_received = await karma_transaction.total_received_by(target.id)
+        top_given = await karma_transaction.top_given_to(target.id, limit=5)
+        top_received = await karma_transaction.top_received_from(target.id, limit=5)
+
+        embed = discord.Embed(
+            title=f"Karma Stats — {target.display_name}",
+            color=discord.Color.gold(),
+        )
+        embed.set_thumbnail(url=target.display_avatar.url)
+
+        embed.add_field(name="Total Given", value=str(total_given), inline=True)
+        embed.add_field(name="Total Received", value=str(total_received), inline=True)
+        embed.add_field(name="\u200b", value="\u200b", inline=True)  # spacer
+
+        if top_given:
+            lines = []
+            for recipient_id, total in top_given:
+                m = interaction.guild.get_member(recipient_id)
+                name = m.mention if m else f"Unknown ({recipient_id})"
+                lines.append(f"{name} — **{total}**")
+            embed.add_field(
+                name="Most Given To", value="\n".join(lines), inline=True
+            )
+
+        if top_received:
+            lines = []
+            for giver_id, total in top_received:
+                m = interaction.guild.get_member(giver_id)
+                name = m.mention if m else f"Unknown ({giver_id})"
+                lines.append(f"{name} — **{total}**")
+            embed.add_field(
+                name="Most Received From", value="\n".join(lines), inline=True
+            )
+
+        await interaction.followup.send(embed=embed)
+
     async def _resolve_targets(
         self, message: discord.Message
     ) -> list[tuple[discord.Member, int, bool]]: