feat(db): add KnownUser model and abstract methods for user tracking, welcome-once, and welcome delay

Add KnownUser dataclass to models.py and 7 new abstract methods to both
Repository and AsyncRepository: upsert_known_user, get_known_user,
get_known_user_by_username, has_been_welcomed, mark_welcomed,
get_welcome_delay, set_welcome_delay.

Author: 0xMett

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/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."""