feat(welcome): add user tracking, welcome-once-per-group, and auto-delete

Track users on every interaction via known_users table. Skip welcome
message if user was already welcomed in the group. Schedule auto-delete
of welcome messages via job_queue with configurable per-group delay.
Store welcome message-to-user mapping for ban-by-reply support.

Author: 0xMett

src/python_italy_bot/handlers/welcome.py

@@ -13,11 +13,24 @@
 )
 
 from .. import strings
+from ..db.base import AsyncRepository
 from ..services.captcha import CaptchaService
 from ..services.moderation import ModerationService
 
 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."""
@@ -34,13 +47,29 @@ def create_welcome_handlers(captcha_service: CaptchaService) -> list:
     ]
 
 
+async def _delete_welcome_message(context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Job callback: delete a welcome message after the configured delay."""
+    job = context.job
+    if job is None or job.data is None:
+        return
+    data: tuple[int, int] = job.data  # type: ignore[assignment]
+    chat_id, message_id = data
+    try:
+        await context.bot.delete_message(chat_id=chat_id, message_id=message_id)
+    except Exception as e:
+        logger.debug(
+            "Could not delete welcome message %s in chat %s: %s", message_id, chat_id, e
+        )
+
+
 async def _handle_new_member(
     update: Update,
     context: ContextTypes.DEFAULT_TYPE,
 ) -> None:
     """Handle new chat members: restrict and send welcome with captcha instructions."""
     captcha_service: CaptchaService = context.bot_data["captcha_service"]
     moderation_service: ModerationService = context.bot_data["moderation_service"]
+    repository: AsyncRepository = context.bot_data["repository"]
     result = update.chat_member
     if result is None:
         return
@@ -64,6 +93,9 @@ async def _handle_new_member(
 
     await moderation_service.register_chat(chat.id)
 
+    # Track the user
+    await _track_user(repository, user)
+
     if user.is_bot:
         return
 
@@ -90,6 +122,10 @@ async def _handle_new_member(
 
     await captcha_service.add_pending(user.id, chat.id)
 
+    # Skip welcome if user was already welcomed in this chat
+    if await captcha_service.has_been_welcomed(user.id, chat.id):
+        return
+
     bot_me = await context.bot.get_me()
     bot_username = bot_me.username or "bot"
 
@@ -99,17 +135,39 @@ async def _handle_new_member(
     else:
         template = captcha_service.get_default_welcome_template(bot_username)
 
-    formatted = captcha_service.format_welcome_message(template, user, chat, bot_username)
+    formatted = captcha_service.format_welcome_message(
+        template, user, chat, bot_username
+    )
     text, keyboard = captcha_service.parse_button_urls(formatted)
 
     try:
-        await context.bot.send_message(
+        sent = await context.bot.send_message(
             chat_id=chat.id,
             text=text,
             reply_markup=keyboard,
         )
     except Exception as e:
         logger.warning("Could not send welcome to chat %s: %s", chat.id, e)
+        return
+
+    # Mark user as welcomed in this chat
+    await captcha_service.mark_welcomed(user.id, chat.id)
+
+    # Store welcome message -> user mapping for ban-by-reply
+    welcome_map = context.bot_data.setdefault("welcome_message_map", {})
+    welcome_map[(chat.id, sent.message_id)] = user.id
+
+    # Schedule auto-deletion of the welcome message
+    delay_minutes = await captcha_service.get_welcome_delay(chat.id)
+    if delay_minutes is None:
+        delay_minutes = DEFAULT_WELCOME_DELAY_MINUTES
+    if delay_minutes > 0 and context.job_queue is not None:
+        context.job_queue.run_once(
+            _delete_welcome_message,
+            when=delay_minutes * 60,
+            data=(chat.id, sent.message_id),
+            name=f"del_welcome_{chat.id}_{sent.message_id}",
+        )
 
 
 async def _handle_start(
@@ -118,6 +176,7 @@ 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
@@ -130,6 +189,9 @@ 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()
@@ -192,6 +254,7 @@ 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
@@ -200,6 +263,9 @@ 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