feat(handlers): implement user tracking middleware for all handler interactions

Co-authored-by: MattiaFailla <11872425+MattiaFailla@users.noreply.github.com>

Author: Copilot

src/python_italy_bot/handlers/moderation.py

@@ -14,16 +14,6 @@
 logger = logging.getLogger(__name__)
 
 
-async def _track_user(repo: AsyncRepository, user: object) -> None:
-    """Track a Telegram user in the known_users table."""
-    await repo.upsert_known_user(
-        user_id=user.id,  # type: ignore[attr-defined]
-        username=getattr(user, "username", None),
-        first_name=getattr(user, "first_name", None),
-        last_name=getattr(user, "last_name", None),
-    )
-
-
 async def _is_admin(
     context: ContextTypes.DEFAULT_TYPE, chat_id: int, user_id: int
 ) -> bool:
@@ -81,7 +71,6 @@ async def _handle_force_group_registration(
 async def _handle_ban(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Ban a user globally. Usage: /ban user_id|@username [reason] or reply with /ban [reason]."""
     moderation_service: ModerationService = context.bot_data["moderation_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.from_user is None:
         return
@@ -90,9 +79,6 @@ async def _handle_ban(update: Update, context: ContextTypes.DEFAULT_TYPE) -> Non
     if chat is None or chat.type == "private":
         return
 
-    # Track the invoking admin
-    await _track_user(repository, message.from_user)
-
     if not await _is_admin(context, chat.id, message.from_user.id):
         await message.reply_text(strings.ONLY_ADMINS)
         return
@@ -152,7 +138,6 @@ async def _handle_ban(update: Update, context: ContextTypes.DEFAULT_TYPE) -> Non
 async def _handle_unban(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Unban a user globally. Usage: /unban user_id or reply to message with /unban."""
     moderation_service: ModerationService = context.bot_data["moderation_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.from_user is None:
         return
@@ -161,9 +146,6 @@ async def _handle_unban(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
     if chat is None or chat.type == "private":
         return
 
-    # Track the invoking admin
-    await _track_user(repository, message.from_user)
-
     if not await _is_admin(context, chat.id, message.from_user.id):
         await message.reply_text(strings.ONLY_ADMINS)
         return
@@ -197,7 +179,6 @@ async def _handle_unban(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
 async def _handle_mute(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Mute a user. Usage: /mute @username [duration_minutes] [reason]."""
     moderation_service: ModerationService = context.bot_data["moderation_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.from_user is None:
         return
@@ -206,9 +187,6 @@ async def _handle_mute(update: Update, context: ContextTypes.DEFAULT_TYPE) -> No
     if chat is None or chat.type == "private":
         return
 
-    # Track the invoking admin
-    await _track_user(repository, message.from_user)
-
     if not await _is_admin(context, chat.id, message.from_user.id):
         await message.reply_text(strings.ONLY_ADMINS)
         return
@@ -270,7 +248,6 @@ async def _handle_mute(update: Update, context: ContextTypes.DEFAULT_TYPE) -> No
 async def _handle_unmute(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Unmute a user. Usage: /unmute @username."""
     moderation_service: ModerationService = context.bot_data["moderation_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.from_user is None:
         return
@@ -279,9 +256,6 @@ async def _handle_unmute(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
     if chat is None or chat.type == "private":
         return
 
-    # Track the invoking admin
-    await _track_user(repository, message.from_user)
-
     if not await _is_admin(context, chat.id, message.from_user.id):
         await message.reply_text(strings.ONLY_ADMINS)
         return
@@ -329,7 +303,6 @@ async def _handle_unmute(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
 async def _handle_report(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Report a message or user. Usage: /report [reason] or reply to message with /report [reason]."""
     moderation_service: ModerationService = context.bot_data["moderation_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.from_user is None:
         return
@@ -338,9 +311,6 @@ async def _handle_report(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
     if chat is None or chat.type == "private":
         return
 
-    # Track the reporter
-    await _track_user(repository, message.from_user)
-
     args = message.text.split(maxsplit=1)[1:] if message.text else []
     reason = args[0] if args else None
 
@@ -387,7 +357,6 @@ async def _handle_admin_mention(
     update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
     """Handle @admin mention: notify admins of intervention request (no reply needed)."""
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.from_user is None:
         return
@@ -396,9 +365,6 @@ async def _handle_admin_mention(
     if chat is None or chat.type == "private":
         return
 
-    # Track the user
-    await _track_user(repository, message.from_user)
-
     text = message.text or message.caption or ""
     reason = _extract_reason_after_admin(text)
 

src/python_italy_bot/handlers/utils.py

@@ -0,0 +1,41 @@
+"""Shared utilities for all handlers."""
+
+import logging
+
+from telegram import Update
+from telegram.ext import ContextTypes, TypeHandler
+
+from ..db.base import AsyncRepository
+
+logger = logging.getLogger(__name__)
+
+
+async def track_user(repo: AsyncRepository, user: object) -> None:
+    """Track a Telegram user in the known_users table."""
+    await repo.upsert_known_user(
+        user_id=user.id,  # type: ignore[attr-defined]
+        username=getattr(user, "username", None),
+        first_name=getattr(user, "first_name", None),
+        last_name=getattr(user, "last_name", None),
+    )
+
+
+async def _handle_track_user(
+    update: Update, context: ContextTypes.DEFAULT_TYPE
+) -> None:
+    """Middleware: track the effective user for every update."""
+    user = update.effective_user
+    if user is None:
+        return
+    repository: AsyncRepository | None = context.bot_data.get("repository")
+    if repository is None:
+        return
+    try:
+        await track_user(repository, user)
+    except Exception as e:
+        logger.warning("Failed to track user %s: %s", user.id, e, exc_info=True)
+
+
+def create_user_tracking_handler() -> TypeHandler:
+    """Create a TypeHandler that tracks users from every incoming update."""
+    return TypeHandler(Update, _handle_track_user)

src/python_italy_bot/handlers/welcome.py

@@ -16,22 +16,13 @@
 from ..db.base import AsyncRepository
 from ..services.captcha import CaptchaService
 from ..services.moderation import ModerationService
+from .utils import track_user
 
 logger = logging.getLogger(__name__)
 
 DEFAULT_WELCOME_DELAY_MINUTES = 5
 
 
-async def _track_user(repo: AsyncRepository, user: object) -> None:
-    """Track a Telegram user in the known_users table."""
-    await repo.upsert_known_user(
-        user_id=user.id,  # type: ignore[attr-defined]
-        username=getattr(user, "username", None),
-        first_name=getattr(user, "first_name", None),
-        last_name=getattr(user, "last_name", None),
-    )
-
-
 def create_welcome_handlers(captcha_service: CaptchaService) -> list:
     """Create welcome and captcha handlers."""
     return [
@@ -93,8 +84,9 @@ async def _handle_new_member(
 
     await moderation_service.register_chat(chat.id)
 
-    # Track the user
-    await _track_user(repository, user)
+    # Track the new member explicitly: middleware tracks effective_user (the admin
+    # when someone is added by an admin), but we need to track the joined member.
+    await track_user(repository, user)
 
     if user.is_bot:
         return
@@ -176,7 +168,6 @@ async def _handle_start(
 ) -> None:
     """Handle /start command, including deep link for verification."""
     captcha_service: CaptchaService = context.bot_data["captcha_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None:
         return
@@ -189,9 +180,6 @@ async def _handle_start(
     if user is None:
         return
 
-    # Track the user
-    await _track_user(repository, user)
-
     args = context.args
     if args and args[0] == "verify":
         rules_url = captcha_service.get_rules_url()
@@ -254,7 +242,6 @@ async def _handle_private_message(
 ) -> None:
     """Handle private messages: check for secret command and verify user globally."""
     captcha_service: CaptchaService = context.bot_data["captcha_service"]
-    repository: AsyncRepository = context.bot_data["repository"]
     message = update.message
     if message is None or message.text is None:
         return
@@ -263,9 +250,6 @@ async def _handle_private_message(
     if user is None:
         return
 
-    # Track the user
-    await _track_user(repository, user)
-
     if not captcha_service.is_secret_command(message.text):
         await message.reply_text(strings.VERIFY_UNKNOWN_COMMAND)
         return

src/python_italy_bot/main.py

@@ -12,6 +12,7 @@
 from .handlers.ping import create_ping_handlers
 from .handlers.settings import create_settings_handlers
 # from .handlers.spam import create_spam_handler
+from .handlers.utils import create_user_tracking_handler
 from .handlers.welcome import create_welcome_handlers
 from .services.captcha import CaptchaService
 from .services.moderation import ModerationService
@@ -43,6 +44,9 @@ async def _post_init(application) -> None:
     application.bot_data["moderation_service"] = moderation_service
     # application.bot_data["spam_detector"] = spam_detector
 
+    # Register user-tracking middleware before all other handlers (group -1)
+    application.add_handler(create_user_tracking_handler(), group=-1)
+
     for handler in create_id_handlers():
         application.add_handler(handler)
     for handler in create_settings_handlers():