Add user mention helpers and expand telegram utilities

- Add get_user_mention() to generate formatted mentions (@username or markdown link)
- Add get_user_mention_by_id() for markdown mentions with just ID and name
- Update handlers (captcha, message, verify) to use new mention utilities
- Add comprehensive tests for mention generation functions (16 new test cases)
- Update README with current test coverage statistics (224 tests, 100% coverage, 702 statements)

Author: rezhajulio

README.md

@@ -135,9 +135,9 @@ uv run pytest -v
 ### Test Coverage
 
 The project maintains comprehensive test coverage:
-- **Coverage**: 100% across all modules (700 statements, 0 missed)
-- **Tests**: 208 total
-- **Pass Rate**: 100% (208/208 passed)
+- **Coverage**: 100% across all modules (702 statements, 0 missed)
+- **Tests**: 224 total
+- **Pass Rate**: 100% (224/224 passed)
 - **All modules**: 100% coverage including JobQueue scheduler integration and captcha verification
   - Services: `bot_info.py`, `scheduler.py`, `user_checker.py`, `telegram_utils.py`, `captcha_recovery.py`
   - Handlers: `captcha.py`, `dm.py`, `message.py`, `topic_guard.py`, `verify.py`

src/bot/handlers/captcha.py

@@ -18,7 +18,6 @@
     MessageHandler,
     filters,
 )
-from telegram.helpers import mention_markdown
 
 from bot.config import Settings, get_settings
 from bot.constants import (
@@ -29,7 +28,7 @@
     RESTRICTED_PERMISSIONS,
 )
 from bot.database.service import get_database
-from bot.services.telegram_utils import unrestrict_user
+from bot.services.telegram_utils import get_user_mention, unrestrict_user
 
 logger = logging.getLogger(__name__)
 
@@ -66,7 +65,7 @@ async def _initiate_captcha_challenge(
         settings: Bot settings.
     """
     user_id = user.id
-    user_mention = mention_markdown(user_id, user.full_name, version=2)
+    user_mention = get_user_mention(user)
 
     try:
         await context.bot.restrict_chat_member(
@@ -283,7 +282,7 @@ async def captcha_callback_handler(
     db = get_database()
     db.remove_pending_captcha(target_user_id, settings.group_id)
 
-    user_mention = mention_markdown(target_user_id, query.from_user.full_name, version=2)
+    user_mention = get_user_mention(query.from_user)
 
     try:
         await query.edit_message_text(

src/bot/handlers/message.py

@@ -11,7 +11,7 @@
 
 from telegram import Update
 from telegram.ext import ContextTypes
-from telegram.helpers import mention_markdown
+
 
 from bot.config import get_settings
 from bot.constants import (
@@ -24,6 +24,7 @@
 )
 from bot.database.service import get_database
 from bot.services.bot_info import BotInfoCache
+from bot.services.telegram_utils import get_user_mention
 from bot.services.user_checker import check_user_profile
 
 logger = logging.getLogger(__name__)
@@ -69,11 +70,7 @@ async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
     # Build warning message components
     missing = result.get_missing_items()
     missing_text = MISSING_ITEMS_SEPARATOR.join(missing)
-    user_mention = (
-        f"@{user.username}"
-        if user.username
-        else mention_markdown(user.id, user.full_name, version=2)
-    )
+    user_mention = get_user_mention(user)
 
     # Warning mode: just send warning, don't restrict
     if not settings.restrict_failed_users:

src/bot/handlers/verify.py

@@ -11,12 +11,11 @@
 from telegram import Update
 from telegram.error import BadRequest
 from telegram.ext import ContextTypes
-from telegram.helpers import mention_markdown
 
 from bot.config import get_settings
 from bot.constants import VERIFICATION_CLEARANCE_MESSAGE
 from bot.database.service import get_database
-from bot.services.telegram_utils import unrestrict_user
+from bot.services.telegram_utils import get_user_mention_by_id, unrestrict_user
 
 logger = logging.getLogger(__name__)
 
@@ -92,7 +91,7 @@ async def handle_verify_command(
         if deleted_count > 0:
             # Get user info for proper mention
             user_info = await context.bot.get_chat(target_user_id)
-            user_mention = mention_markdown(target_user_id, user_info.full_name, version=2)
+            user_mention = get_user_mention_by_id(target_user_id, user_info.full_name)
 
             # Send clearance message to warning topic
             clearance_message = VERIFICATION_CLEARANCE_MESSAGE.format(

src/bot/services/captcha_recovery.py

@@ -11,13 +11,13 @@
 
 from telegram import Bot
 from telegram.ext import Application
-from telegram.helpers import mention_markdown
 
 from bot.config import get_settings
 from bot.constants import CAPTCHA_TIMEOUT_MESSAGE
 from bot.database.service import get_database
 from bot.handlers.captcha import captcha_timeout_callback, get_captcha_job_name
 from bot.services.bot_info import BotInfoCache
+from bot.services.telegram_utils import get_user_mention_by_id
 
 logger = logging.getLogger(__name__)
 
@@ -60,7 +60,7 @@ async def handle_captcha_expiration(
 
     bot_username = await BotInfoCache.get_username(bot)
     dm_link = f"[hubungi robot](https://t.me/{bot_username})"
-    user_mention = mention_markdown(user_id, user_full_name, version=2)
+    user_mention = get_user_mention_by_id(user_id, user_full_name)
 
     try:
         await bot.edit_message_text(

src/bot/services/scheduler.py

@@ -9,7 +9,7 @@
 
 from telegram.constants import ChatMemberStatus
 from telegram.ext import ContextTypes
-from telegram.helpers import mention_markdown
+
 
 from bot.config import get_settings
 from bot.constants import (
@@ -19,7 +19,7 @@
 )
 from bot.database.service import get_database
 from bot.services.bot_info import BotInfoCache
-from bot.services.telegram_utils import get_user_status
+from bot.services.telegram_utils import get_user_mention, get_user_status
 
 logger = logging.getLogger(__name__)
 
@@ -81,11 +81,7 @@ async def auto_restrict_expired_warnings(context: ContextTypes.DEFAULT_TYPE) ->
                     user_id=warning.user_id,
                 )
                 user = user_member.user
-                user_mention = (
-                    f"@{user.username}"
-                    if user.username
-                    else mention_markdown(user.id, user.full_name, version=2)
-                )
+                user_mention = get_user_mention(user)
             except Exception:
                 # Fallback to user ID if we can't get user info
                 user_mention = f"User {warning.user_id}"

src/bot/services/telegram_utils.py

@@ -5,9 +5,46 @@
 Telegram's API across different handlers and services.
 """
 
-from telegram import Bot
+from telegram import Bot, User
 from telegram.constants import ChatMemberStatus
 from telegram.error import BadRequest, Forbidden
+from telegram.helpers import mention_markdown
+
+
+def get_user_mention(user: User) -> str:
+    """
+    Get a formatted mention string for a user.
+
+    Returns `@username` if the user has a username, otherwise returns
+    a markdown mention using the user's full name and ID.
+
+    Args:
+        user: Telegram User object.
+
+    Returns:
+        str: Formatted user mention (either @username or markdown mention).
+    """
+    return (
+        f"@{user.username}"
+        if user.username
+        else mention_markdown(user.id, user.full_name, version=2)
+    )
+
+
+def get_user_mention_by_id(user_id: int, user_full_name: str) -> str:
+    """
+    Get a formatted markdown mention for a user by ID and name.
+
+    Used when only user ID and full name are available (not a full User object).
+
+    Args:
+        user_id: Telegram user ID.
+        user_full_name: User's full name.
+
+    Returns:
+        str: Markdown mention string.
+    """
+    return mention_markdown(user_id, user_full_name, version=2)
 
 
 async def get_user_status(