feat: add contact_spam_restrict per-group config option

- Add contact_spam_restrict field to GroupConfig (default: true)
- Add .env fallback in config.py and build_group_registry
- Skip restrict in handler when config is false
- Add to groups.json.example and .env.example
- Add test for disabled restrict config (534 total)
- Update docs with new config option

Author: rezhajulio

.env.example

@@ -36,6 +36,11 @@ CAPTCHA_ENABLED=false
 # Default: 120 seconds (2 minutes)
 CAPTCHA_TIMEOUT_SECONDS=120
 
+# Restrict users who share contact cards (true/false)
+# When true, users sharing contact cards will be restricted (muted)
+# When false, contact messages are deleted but user is not restricted
+CONTACT_SPAM_RESTRICT=true
+
 # Enable duplicate message spam detection (true/false)
 # Detects and restricts users who paste the same message repeatedly
 DUPLICATE_SPAM_ENABLED=true

AGENTS.md

@@ -157,7 +157,7 @@ Time threshold → Auto-restrict via scheduler (parallel path)
 - **Fixtures**: `mock_update`, `mock_context`, `mock_settings` — copy from existing tests
 - **Database tests**: Use `temp_db` fixture with `tempfile.TemporaryDirectory`
 - **Mocking**: `AsyncMock` for Telegram API; no real network calls
-- **Coverage**: 99.9% maintained (533 tests) — check before committing
+- **Coverage**: 99.9% maintained (534 tests) — check before committing
 
 ## Anti-Patterns (THIS PROJECT)
 

README.md

@@ -196,8 +196,8 @@ uv run pytest -v
 
 The project maintains comprehensive test coverage:
 - **Coverage**: 99.9% (1,570 statements, 1 unreachable line)
-- **Tests**: 533 total
-- **Pass Rate**: 100% (533/533 passed)
+- **Tests**: 534 total
+- **Pass Rate**: 100% (534/534 passed)
 - **All modules at 100%** except one unreachable line in `anti_spam.py`
   - Services: `bot_info.py`, `scheduler.py`, `user_checker.py`, `telegram_utils.py`, `captcha_recovery.py` — all 100%
   - Handlers: `anti_spam.py` (99%), `captcha.py`, `check.py`, `dm.py`, `message.py`, `topic_guard.py`, `verify.py`, `duplicate_spam.py` — all 100%
@@ -542,6 +542,7 @@ When a restricted user DMs the bot (or sends `/start`):
 | `CAPTCHA_TIMEOUT_SECONDS` | Seconds before kicking unverified members | `120` (2 minutes) |
 | `NEW_USER_PROBATION_HOURS` | Hours new users can't send links/forwards | `72` (3 days) |
 | `NEW_USER_VIOLATION_THRESHOLD` | Spam violations before restriction | `3` |
+| `CONTACT_SPAM_RESTRICT` | Restrict users who share contact cards | `true` |
 | `DATABASE_PATH` | SQLite database path | `data/bot.db` |
 | `RULES_LINK` | Link to group rules message | `https://t.me/pythonID/290029/321799` |
 | `LOGFIRE_ENABLED` | Enable Logfire logging integration | `true` |

groups.json.example

@@ -10,6 +10,7 @@
     "new_user_probation_hours": 72,
     "new_user_violation_threshold": 3,
     "rules_link": "https://t.me/pythonID/290029/321799",
+    "contact_spam_restrict": true,
     "duplicate_spam_enabled": true,
     "duplicate_spam_window_seconds": 120,
     "duplicate_spam_threshold": 2,
@@ -27,6 +28,7 @@
     "new_user_probation_hours": 168,
     "new_user_violation_threshold": 2,
     "rules_link": "https://t.me/mygroup/rules",
+    "contact_spam_restrict": true,
     "duplicate_spam_enabled": true,
     "duplicate_spam_window_seconds": 60,
     "duplicate_spam_threshold": 2,

src/bot/config.py

@@ -79,6 +79,7 @@ class Settings(BaseSettings):
     captcha_timeout_seconds: int = 120
     new_user_probation_hours: int = 72  # 3 days default
     new_user_violation_threshold: int = 3  # restrict after this many violations
+    contact_spam_restrict: bool = True
     duplicate_spam_enabled: bool = True
     duplicate_spam_window_seconds: int = 120
     duplicate_spam_threshold: int = 2

src/bot/group_config.py

@@ -35,6 +35,7 @@ class GroupConfig(BaseModel):
     new_user_probation_hours: int = 72
     new_user_violation_threshold: int = 3
     rules_link: str = "https://t.me/pythonID/290029/321799"
+    contact_spam_restrict: bool = True
     duplicate_spam_enabled: bool = True
     duplicate_spam_window_seconds: int = 120
     duplicate_spam_threshold: int = 2
@@ -186,6 +187,7 @@ def build_group_registry(settings: object) -> GroupRegistry:
             new_user_probation_hours=settings.new_user_probation_hours,
             new_user_violation_threshold=settings.new_user_violation_threshold,
             rules_link=settings.rules_link,
+            contact_spam_restrict=settings.contact_spam_restrict,
             duplicate_spam_enabled=settings.duplicate_spam_enabled,
             duplicate_spam_window_seconds=settings.duplicate_spam_window_seconds,
             duplicate_spam_threshold=settings.duplicate_spam_threshold,

src/bot/handlers/anti_spam.py

@@ -304,19 +304,20 @@ async def handle_contact_spam(
         )
 
     restricted = False
-    try:
-        await context.bot.restrict_chat_member(
-            chat_id=group_config.group_id,
-            user_id=user.id,
-            permissions=RESTRICTED_PERMISSIONS,
-        )
-        restricted = True
-        logger.info(f"Restricted user_id={user.id} for contact spam")
-    except Exception:
-        logger.error(
-            f"Failed to restrict user for contact spam: user_id={user.id}",
-            exc_info=True,
-        )
+    if group_config.contact_spam_restrict:
+        try:
+            await context.bot.restrict_chat_member(
+                chat_id=group_config.group_id,
+                user_id=user.id,
+                permissions=RESTRICTED_PERMISSIONS,
+            )
+            restricted = True
+            logger.info(f"Restricted user_id={user.id} for contact spam")
+        except Exception:
+            logger.error(
+                f"Failed to restrict user for contact spam: user_id={user.id}",
+                exc_info=True,
+            )
 
     try:
         template = (

tests/test_anti_spam.py

@@ -1356,3 +1356,24 @@ async def test_raises_application_handler_stop(self, mock_update, mock_context,
         with patch("bot.handlers.anti_spam.get_group_config_for_update", return_value=group_config):
             with pytest.raises(ApplicationHandlerStop):
                 await handle_contact_spam(mock_update, mock_context)
+
+    async def test_contact_spam_no_restrict_when_config_disabled(
+        self, mock_update, mock_context
+    ):
+        """Test that user is NOT restricted when contact_spam_restrict is False."""
+        group_config = GroupConfig(
+            group_id=-100123456,
+            warning_topic_id=123,
+            rules_link="https://example.com/rules",
+            contact_spam_restrict=False,
+        )
+
+        with patch("bot.handlers.anti_spam.get_group_config_for_update", return_value=group_config):
+            with pytest.raises(ApplicationHandlerStop):
+                await handle_contact_spam(mock_update, mock_context)
+
+        mock_update.message.delete.assert_called_once()
+        mock_context.bot.restrict_chat_member.assert_not_called()
+        mock_context.bot.send_message.assert_called_once()
+        call_args = mock_context.bot.send_message.call_args
+        assert "dibatasi" not in call_args.kwargs.get("text", call_args[1].get("text", ""))