Merge pull request #44 from pythonitalia/feature/user-tracking-and-welcome-improvements

feat: user tracking and welcome improvements

Author: MattiaFailla

.gitignore

@@ -15,9 +15,17 @@ env/
 .idea/
 .vscode/
 .cursor/
+.zed/
 *.swp
 *.swo
 
+# AI / agent tooling
+.codex/
+.gemini/
+.mcp.json
+opencode.json
+electus/
+
 # OS
 .DS_Store
 Thumbs.db

schema.sql

@@ -64,3 +64,26 @@ CREATE TABLE IF NOT EXISTS global_bans (
     reason TEXT,
     created_at TIMESTAMPTZ DEFAULT NOW()
 );
+
+CREATE TABLE IF NOT EXISTS known_users (
+    user_id BIGINT PRIMARY KEY,
+    username TEXT,
+    first_name TEXT,
+    last_name TEXT,
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_known_users_username
+    ON known_users (LOWER(username))
+    WHERE username IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS welcomed_users (
+    user_id BIGINT NOT NULL,
+    chat_id BIGINT NOT NULL,
+    welcomed_at TIMESTAMPTZ DEFAULT NOW(),
+    PRIMARY KEY (user_id, chat_id)
+);
+
+-- Add welcome_delay_minutes column to group_settings (idempotent).
+ALTER TABLE group_settings
+    ADD COLUMN IF NOT EXISTS welcome_delay_minutes INTEGER;

src/python_italy_bot/db/base.py

@@ -2,6 +2,8 @@
 
 from abc import ABC, abstractmethod
 
+from .models import KnownUser
+
 
 class Repository(ABC):
     """Abstract interface for data persistence (sync)."""
@@ -136,6 +138,53 @@ def is_globally_banned(self, user_id: int) -> bool:
         """Check if user is globally banned."""
         ...
 
+    # -- Known users (user tracking) --
+
+    @abstractmethod
+    def upsert_known_user(
+        self,
+        user_id: int,
+        username: str | None,
+        first_name: str | None,
+        last_name: str | None,
+    ) -> None:
+        """Insert or update a known user's info."""
+        ...
+
+    @abstractmethod
+    def get_known_user(self, user_id: int) -> KnownUser | None:
+        """Get a known user by ID."""
+        ...
+
+    @abstractmethod
+    def get_known_user_by_username(self, username: str) -> KnownUser | None:
+        """Get a known user by username (case-insensitive)."""
+        ...
+
+    # -- Welcomed users (welcome-once-per-group) --
+
+    @abstractmethod
+    def has_been_welcomed(self, user_id: int, chat_id: int) -> bool:
+        """Check if user has already been welcomed in this chat."""
+        ...
+
+    @abstractmethod
+    def mark_welcomed(self, user_id: int, chat_id: int) -> None:
+        """Mark user as having been welcomed in this chat."""
+        ...
+
+    # -- Welcome delay --
+
+    @abstractmethod
+    def get_welcome_delay(self, chat_id: int) -> int | None:
+        """Get welcome message auto-delete delay in minutes for a chat."""
+        ...
+
+    @abstractmethod
+    def set_welcome_delay(self, chat_id: int, minutes: int | None) -> None:
+        """Set welcome message auto-delete delay. None to reset to default."""
+        ...
+
 
 class AsyncRepository(ABC):
     """Abstract interface for data persistence (async)."""
@@ -270,6 +319,53 @@ async def is_globally_banned(self, user_id: int) -> bool:
         """Check if user is globally banned."""
         ...
 
+    # -- Known users (user tracking) --
+
+    @abstractmethod
+    async def upsert_known_user(
+        self,
+        user_id: int,
+        username: str | None,
+        first_name: str | None,
+        last_name: str | None,
+    ) -> None:
+        """Insert or update a known user's info."""
+        ...
+
+    @abstractmethod
+    async def get_known_user(self, user_id: int) -> KnownUser | None:
+        """Get a known user by ID."""
+        ...
+
+    @abstractmethod
+    async def get_known_user_by_username(self, username: str) -> KnownUser | None:
+        """Get a known user by username (case-insensitive)."""
+        ...
+
+    # -- Welcomed users (welcome-once-per-group) --
+
+    @abstractmethod
+    async def has_been_welcomed(self, user_id: int, chat_id: int) -> bool:
+        """Check if user has already been welcomed in this chat."""
+        ...
+
+    @abstractmethod
+    async def mark_welcomed(self, user_id: int, chat_id: int) -> None:
+        """Mark user as having been welcomed in this chat."""
+        ...
+
+    # -- Welcome delay --
+
+    @abstractmethod
+    async def get_welcome_delay(self, chat_id: int) -> int | None:
+        """Get welcome message auto-delete delay in minutes for a chat."""
+        ...
+
+    @abstractmethod
+    async def set_welcome_delay(self, chat_id: int, minutes: int | None) -> None:
+        """Set welcome message auto-delete delay. None to reset to default."""
+        ...
+
     async def close(self) -> None:
         """Close any resources (override if needed)."""
         pass

src/python_italy_bot/db/in_memory.py

@@ -3,7 +3,7 @@
 from datetime import datetime, timezone
 
 from .base import AsyncRepository
-from .models import Ban, Mute, Report
+from .models import Ban, KnownUser, Mute, Report
 
 
 class InMemoryRepository(AsyncRepository):
@@ -19,6 +19,10 @@ def __init__(self) -> None:
         self._globally_verified: set[int] = set()
         self._bot_chats: set[int] = set()
         self._global_bans: dict[int, tuple[int, str | None]] = {}
+        self._known_users: dict[int, KnownUser] = {}
+        self._username_to_user_id: dict[str, int] = {}
+        self._welcomed: set[tuple[int, int]] = set()
+        self._welcome_delays: dict[int, int] = {}
 
     async def add_pending_verification(self, user_id: int, chat_id: int) -> None:
         self._pending.add((user_id, chat_id))
@@ -159,3 +163,54 @@ async def remove_global_ban(self, user_id: int) -> bool:
 
     async def is_globally_banned(self, user_id: int) -> bool:
         return user_id in self._global_bans
+
+    # -- Known users --
+
+    async def upsert_known_user(
+        self,
+        user_id: int,
+        username: str | None,
+        first_name: str | None,
+        last_name: str | None,
+    ) -> None:
+        old = self._known_users.get(user_id)
+        if old and old.username:
+            self._username_to_user_id.pop(old.username.lower(), None)
+        user = KnownUser(
+            user_id=user_id,
+            username=username,
+            first_name=first_name,
+            last_name=last_name,
+            updated_at=datetime.now(timezone.utc),
+        )
+        self._known_users[user_id] = user
+        if username:
+            self._username_to_user_id[username.lower()] = user_id
+
+    async def get_known_user(self, user_id: int) -> KnownUser | None:
+        return self._known_users.get(user_id)
+
+    async def get_known_user_by_username(self, username: str) -> KnownUser | None:
+        uid = self._username_to_user_id.get(username.lower())
+        if uid is not None:
+            return self._known_users.get(uid)
+        return None
+
+    # -- Welcomed users --
+
+    async def has_been_welcomed(self, user_id: int, chat_id: int) -> bool:
+        return (user_id, chat_id) in self._welcomed
+
+    async def mark_welcomed(self, user_id: int, chat_id: int) -> None:
+        self._welcomed.add((user_id, chat_id))
+
+    # -- Welcome delay --
+
+    async def get_welcome_delay(self, chat_id: int) -> int | None:
+        return self._welcome_delays.get(chat_id)
+
+    async def set_welcome_delay(self, chat_id: int, minutes: int | None) -> None:
+        if minutes is None:
+            self._welcome_delays.pop(chat_id, None)
+        else:
+            self._welcome_delays[chat_id] = minutes

src/python_italy_bot/db/models.py

@@ -4,6 +4,17 @@
 from datetime import datetime
 
 
+@dataclass
+class KnownUser:
+    """A user the bot has interacted with."""
+
+    user_id: int
+    username: str | None
+    first_name: str | None
+    last_name: str | None
+    updated_at: datetime
+
+
 @dataclass
 class Ban:
     """A user ban in a chat."""

src/python_italy_bot/db/postgres.py

@@ -3,6 +3,7 @@
 from psycopg_pool import AsyncConnectionPool
 
 from .base import AsyncRepository
+from .models import KnownUser
 
 
 class PostgresRepository(AsyncRepository):
@@ -261,5 +262,122 @@ async def is_globally_banned(self, user_id: int) -> bool:
                 )
                 return await cur.fetchone() is not None
 
+    # -- Known users --
+
+    async def upsert_known_user(
+        self,
+        user_id: int,
+        username: str | None,
+        first_name: str | None,
+        last_name: str | None,
+    ) -> None:
+        async with self._pool.connection() as conn:
+            await conn.execute(
+                """
+                INSERT INTO known_users (user_id, username, first_name, last_name, updated_at)
+                VALUES (%s, %s, %s, %s, NOW())
+                ON CONFLICT (user_id)
+                DO UPDATE SET username = EXCLUDED.username,
+                              first_name = EXCLUDED.first_name,
+                              last_name = EXCLUDED.last_name,
+                              updated_at = NOW()
+                """,
+                (user_id, username, first_name, last_name),
+            )
+
+    async def get_known_user(self, user_id: int) -> KnownUser | None:
+        async with self._pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT user_id, username, first_name, last_name, updated_at "
+                    "FROM known_users WHERE user_id = %s",
+                    (user_id,),
+                )
+                row = await cur.fetchone()
+                if row is None:
+                    return None
+                return KnownUser(
+                    user_id=row[0],
+                    username=row[1],
+                    first_name=row[2],
+                    last_name=row[3],
+                    updated_at=row[4],
+                )
+
+    async def get_known_user_by_username(self, username: str) -> KnownUser | None:
+        async with self._pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT user_id, username, first_name, last_name, updated_at "
+                    "FROM known_users WHERE LOWER(username) = LOWER(%s)",
+                    (username,),
+                )
+                row = await cur.fetchone()
+                if row is None:
+                    return None
+                return KnownUser(
+                    user_id=row[0],
+                    username=row[1],
+                    first_name=row[2],
+                    last_name=row[3],
+                    updated_at=row[4],
+                )
+
+    # -- Welcomed users --
+
+    async def has_been_welcomed(self, user_id: int, chat_id: int) -> bool:
+        async with self._pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT 1 FROM welcomed_users WHERE user_id = %s AND chat_id = %s",
+                    (user_id, chat_id),
+                )
+                return await cur.fetchone() is not None
+
+    async def mark_welcomed(self, user_id: int, chat_id: int) -> None:
+        async with self._pool.connection() as conn:
+            await conn.execute(
+                """
+                INSERT INTO welcomed_users (user_id, chat_id)
+                VALUES (%s, %s)
+                ON CONFLICT (user_id, chat_id) DO NOTHING
+                """,
+                (user_id, chat_id),
+            )
+
+    # -- Welcome delay --
+
+    async def get_welcome_delay(self, chat_id: int) -> int | None:
+        async with self._pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT welcome_delay_minutes FROM group_settings WHERE chat_id = %s",
+                    (chat_id,),
+                )
+                row = await cur.fetchone()
+                return row[0] if row else None
+
+    async def set_welcome_delay(self, chat_id: int, minutes: int | None) -> None:
+        async with self._pool.connection() as conn:
+            if minutes is None:
+                await conn.execute(
+                    """
+                    UPDATE group_settings SET welcome_delay_minutes = NULL, updated_at = NOW()
+                    WHERE chat_id = %s
+                    """,
+                    (chat_id,),
+                )
+            else:
+                await conn.execute(
+                    """
+                    INSERT INTO group_settings (chat_id, welcome_delay_minutes, updated_at)
+                    VALUES (%s, %s, NOW())
+                    ON CONFLICT (chat_id)
+                    DO UPDATE SET welcome_delay_minutes = EXCLUDED.welcome_delay_minutes,
+                                  updated_at = NOW()
+                    """,
+                    (chat_id, minutes),
+                )
+
     async def close(self) -> None:
         await self._pool.close()