codex-bot 0.1.0__py3-none-any.whl

codex_bot/sender/protocols.py

@@ -0,0 +1,67 @@
+"""
+Protocols for sender — Business interface for UI coordinate storage.
+
+SenderStateStorageProtocol describes operations in terms of the domain area
+("UI coordinates") rather than Redis terms (hash, key). The specific implementation
+via Redis HASH remains on the project side.
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SenderStateStorageProtocol(Protocol):
+    """
+    Contract for UI coordinate storage (Menu and Content message IDs).
+
+    Implement this protocol in the project via Redis, PostgreSQL, or in-memory —
+    ViewSender and SenderManager do not know about the specific storage.
+
+    Example:
+        ```python
+        class RedisSenderStorage:
+            def __init__(self, redis: Redis): ...
+
+            async def get_sender_state(self, key: str) -> dict[str, int]:
+                data = await redis.hgetall(f"sender:{key}")
+                return {k: int(v) for k, v in data.items()}
+
+            async def save_sender_state(self, key: str, data: dict[str, int]) -> None:
+                await redis.hset(f"sender:{key}", mapping={k: str(v) for k, v in data.items()})
+
+            async def clear_sender_state(self, key: str) -> None:
+                await redis.delete(f"sender:{key}")
+        ```
+    """
+
+    async def get_sender_state(self, key: str) -> dict[str, int]:
+        """
+        Returns UI coordinates (message IDs) for a session.
+
+        Args:
+            key: Session key (e.g., user_id string or channel session_id).
+
+        Returns:
+            Dictionary like {"menu_msg_id": 123, "content_msg_id": 124}.
+            Empty dictionary if no data exists.
+        """
+        ...
+
+    async def save_sender_state(self, key: str, data: dict[str, int]) -> None:
+        """
+        Saves (partially updates) UI coordinates for a session.
+
+        Args:
+            key: Session key.
+            data: Fields to update, e.g., {"menu_msg_id": 123}.
+        """
+        ...
+
+    async def clear_sender_state(self, key: str) -> None:
+        """
+        Deletes all UI coordinates for a session.
+
+        Args:
+            key: Session key.
+        """
+        ...

codex_bot/sender/sender_keys.py

@@ -0,0 +1,50 @@
+"""
+SenderKeys — Key factory for UI coordinate storage.
+
+Used by specific implementations of SenderStateStorageProtocol in projects.
+Provided by the library as a ready-made standard for key naming.
+"""
+
+
+class SenderKeys:
+    """
+    Key factory for SenderManager.
+
+    Standardizes key naming in the UI coordinate storage.
+    Use in your implementation of SenderStateStorageProtocol.
+
+    Example:
+        ```python
+        key = SenderKeys.user(user_id=123456789)
+        # "sender:user:123456789"
+
+        key = SenderKeys.channel(session_id="booking_feed_1")
+        # "sender:channel:booking_feed_1"
+        ```
+    """
+
+    @staticmethod
+    def user(user_id: int | str) -> str:
+        """
+        Key for storing UI coordinates of private correspondence.
+
+        Args:
+            user_id: Telegram ID of the user.
+
+        Returns:
+            Key string like `sender:user:<user_id>`.
+        """
+        return f"sender:user:{user_id}"
+
+    @staticmethod
+    def channel(session_id: str) -> str:
+        """
+        Key for storing UI coordinates of a channel or group.
+
+        Args:
+            session_id: Unique identifier of the channel session.
+
+        Returns:
+            Key string like `sender:channel:<session_id>`.
+        """
+        return f"sender:channel:{session_id}"

codex_bot/sender/sender_manager.py

@@ -0,0 +1,85 @@
+"""
+SenderManager — Manager of UI coordinates (message IDs in Telegram).
+
+Stores message_ids of two persistent bot messages (Menu and Content),
+so that ViewSender can edit them instead of sending new ones.
+"""
+
+from codex_bot.sender.protocols import SenderStateStorageProtocol
+from codex_bot.sender.sender_keys import SenderKeys
+
+
+class SenderManager:
+    """
+    Manager for UI coordinate storage.
+
+    Abstracts work with coordinates (menu_msg_id, content_msg_id)
+    on top of SenderStateStorageProtocol. ViewSender works only through it.
+
+    Args:
+        storage: Implementation of SenderStateStorageProtocol (Redis, in-memory, etc.).
+
+    Example:
+        ```python
+        manager = SenderManager(storage=redis_sender_storage)
+        coords = await manager.get_coords(session_key=123456)
+        # {"menu_msg_id": 10, "content_msg_id": 11}
+
+        await manager.update_coords(123456, {"menu_msg_id": 20})
+        await manager.clear_coords(123456)
+        ```
+    """
+
+    def __init__(self, storage: SenderStateStorageProtocol) -> None:
+        self.storage = storage
+
+    async def get_coords(self, session_key: int | str, is_channel: bool = False) -> dict[str, int]:
+        """
+        Returns saved UI coordinates for a session.
+
+        Args:
+            session_key: user_id (int) or session_id (str) for a channel.
+            is_channel: True — use channel key, False — use user key.
+
+        Returns:
+            Dictionary {"menu_msg_id": int, "content_msg_id": int}.
+            Empty dictionary if no data exists.
+        """
+        key = self._build_key(session_key, is_channel)
+        return await self.storage.get_sender_state(key)
+
+    async def update_coords(
+        self,
+        session_key: int | str,
+        coords: dict[str, int],
+        is_channel: bool = False,
+    ) -> None:
+        """
+        Partially updates UI coordinates for a session.
+
+        Args:
+            session_key: user_id or session_id.
+            coords: Fields to update (partial update).
+            is_channel: Key type.
+        """
+        if not coords:
+            return
+        key = self._build_key(session_key, is_channel)
+        await self.storage.save_sender_state(key, coords)
+
+    async def clear_coords(self, session_key: int | str, is_channel: bool = False) -> None:
+        """
+        Deletes all UI coordinates for a session (state reset).
+
+        Args:
+            session_key: user_id or session_id.
+            is_channel: Key type.
+        """
+        key = self._build_key(session_key, is_channel)
+        await self.storage.clear_sender_state(key)
+
+    @staticmethod
+    def _build_key(session_key: int | str, is_channel: bool) -> str:
+        if is_channel:
+            return SenderKeys.channel(str(session_key))
+        return SenderKeys.user(session_key)

codex_bot/sender/view_sender.py

@@ -0,0 +1,200 @@
+"""
+ViewSender — STATELESS service for sending and synchronizing Telegram bot UI.
+
+Manages two persistent messages (Menu and Content):
+edits them if they exist, creates new ones if not.
+Stores their IDs via SenderManager to avoid cluttering the chat.
+
+IMPORTANT: The class must be Stateless — it does not store user state in self.
+ViewSender is a singleton. All context is passed through method arguments.
+"""
+
+import contextlib
+import logging
+
+from aiogram import Bot
+from aiogram.exceptions import TelegramAPIError, TelegramBadRequest
+
+from ..base.view_dto import UnifiedViewDTO, ViewResultDTO
+from .sender_manager import SenderManager
+
+log = logging.getLogger(__name__)
+
+
+class ViewSender:
+    """STATELESS service for sending and updating UI messages.
+
+    Works with two persistent bot messages in the chat:
+
+    - **Menu** — navigation block (section buttons).
+    - **Content** — information block (current feature data).
+
+    The ``send()`` algorithm:
+
+    1. Deletes the ``trigger_message`` (e.g., the ``/start`` command).
+    2. If ``clean_history=True`` — deletes old Menu and Content.
+    3. Edits existing messages (or creates new ones).
+    4. Saves current ``message_id`` via SenderManager.
+
+    .. note::
+        ``alert_text`` from ``UnifiedViewDTO`` is intentionally not processed by ViewSender —
+        alert requires access to ``CallbackQuery.answer()``, which ViewSender does not have.
+        Call ``await call.answer(view.alert_text)`` in the handler before ``await sender.send(view)``.
+
+    Args:
+        bot: Aiogram Bot instance.
+        manager: SenderManager for storing UI coordinates.
+
+    Example:
+        ```python
+        sender = ViewSender(bot=bot, manager=sender_manager)
+        # In a handler:
+        if view.alert_text:
+            await call.answer(view.alert_text, show_alert=True)
+        await sender.send(view)
+        ```
+    """
+
+    def __init__(self, bot: Bot, manager: SenderManager) -> None:
+        self.bot = bot
+        self.manager = manager
+
+    async def send(self, view: UnifiedViewDTO) -> None:
+        """Main UI synchronization method.
+
+        All context variables are local, without writing to self.
+        Safe for concurrent calls from different users.
+
+        Args:
+            view: ``UnifiedViewDTO`` from the orchestrator. Must contain
+                  ``session_key`` and ``chat_id`` (filled by the Director).
+        """
+        if not view.session_key or not view.chat_id:
+            log.error("ViewSender | missing session_key or chat_id in UnifiedViewDTO")
+            return
+
+        # Local variables — each send() call is isolated
+        key = view.session_key
+        chat_id = view.chat_id
+        thread_id = view.message_thread_id
+        is_channel = self._detect_channel(view)
+
+        # 1. Delete trigger message (e.g., /start)
+        if view.trigger_message_id:
+            with contextlib.suppress(TelegramAPIError):
+                await self.bot.delete_message(
+                    chat_id=chat_id,
+                    message_id=view.trigger_message_id,
+                )
+
+        coords = await self.manager.get_coords(key, is_channel)
+
+        # 2. Clean old UI
+        if view.clean_history:
+            await self._delete_coords(coords, chat_id)
+            coords = {}
+            await self.manager.clear_coords(key, is_channel)
+
+        # 3. Update Menu and Content (chat_id and thread_id explicitly via parameters)
+        old_menu_id = coords.get("menu_msg_id")
+        new_menu_id = await self._process_message(view.menu, old_menu_id, "MENU", chat_id, thread_id)
+
+        old_content_id = coords.get("content_msg_id")
+        new_content_id = await self._process_message(view.content, old_content_id, "CONTENT", chat_id, thread_id)
+
+        # 4. Save updated coordinates
+        updates: dict[str, int] = {}
+        if new_menu_id and new_menu_id != old_menu_id:
+            updates["menu_msg_id"] = new_menu_id
+        if new_content_id and new_content_id != old_content_id:
+            updates["content_msg_id"] = new_content_id
+
+        if updates:
+            await self.manager.update_coords(key, updates, is_channel)
+
+    async def _delete_coords(
+        self,
+        coords: dict[str, int],
+        chat_id: int | str,
+    ) -> None:
+        """Deletes Menu and Content messages from the chat.
+
+        Args:
+            coords: Dictionary with ``menu_msg_id`` and ``content_msg_id``.
+            chat_id: Chat ID for deletion.
+        """
+        for msg_id in (coords.get("menu_msg_id"), coords.get("content_msg_id")):
+            if msg_id:
+                with contextlib.suppress(TelegramAPIError):
+                    await self.bot.delete_message(chat_id=chat_id, message_id=msg_id)
+
+    async def _process_message(
+        self,
+        view_dto: ViewResultDTO | None,
+        old_message_id: int | None,
+        log_prefix: str,
+        chat_id: int | str,
+        thread_id: int | None,
+    ) -> int | None:
+        """Edits an existing message or sends a new one.
+
+        Args:
+            view_dto: Content to send. None — skip.
+            old_message_id: ID of the existing message to edit.
+            log_prefix: Log label (``"MENU"`` or ``"CONTENT"``).
+            chat_id: Target chat ID.
+            thread_id: Topic ID in a supergroup.
+
+        Returns:
+            ID of the current message (old or new). None on error.
+        """
+        if not view_dto:
+            return old_message_id
+
+        if old_message_id:
+            try:
+                await self.bot.edit_message_text(
+                    chat_id=chat_id,
+                    message_id=old_message_id,
+                    text=view_dto.text,
+                    reply_markup=view_dto.kb,
+                    parse_mode="HTML",
+                )
+                return old_message_id
+            except TelegramBadRequest as e:
+                if "message is not modified" in str(e).lower():
+                    return old_message_id
+                # Message deleted or inaccessible — create new
+            except TelegramAPIError:
+                pass
+
+        try:
+            sent = await self.bot.send_message(
+                chat_id=chat_id,
+                text=view_dto.text,
+                reply_markup=view_dto.kb,
+                message_thread_id=thread_id,
+                parse_mode="HTML",
+            )
+            log.debug(f"ViewSender [{log_prefix}] sent | chat={chat_id} msg={sent.message_id}")
+            return sent.message_id
+        except TelegramAPIError as e:
+            log.error(f"ViewSender [{log_prefix}] error | chat={chat_id} error='{e}'")
+            return None
+
+    @staticmethod
+    def _detect_channel(view: UnifiedViewDTO) -> bool:
+        """Detects if the chat is a channel or a group.
+
+        Args:
+            view: UnifiedViewDTO with chat data.
+
+        Returns:
+            ``True`` if it's a channel, topic, or group with a negative chat_id.
+        """
+        return (
+            view.mode in ("channel", "topic")
+            or (isinstance(view.chat_id, int) and view.chat_id < 0)
+            or str(view.chat_id).startswith("-")
+            or view.message_thread_id is not None
+        )

codex_bot/templates/feature/callbacks.py.tpl

@@ -0,0 +1,14 @@
+from aiogram.filters.callback_data import CallbackData
+
+# If this is a PAIRED feature (handling buttons from Redis notifications):
+# 1. Import the base callback:
+# from features.redis.{feature_key}.resources.callbacks import {class_name}Callback as BaseCallback
+# 2. Inherit WITHOUT a new prefix (to catch the same events):
+# class {class_name}Callback(BaseCallback):
+#     pass
+
+# If this is a STANDALONE feature:
+class {class_name}Callback(CallbackData, prefix="{feature_key}"):
+    """Callback for the {class_name} feature."""
+    action: str
+    id: str | int

codex_bot/templates/feature/contract.py.tpl

@@ -0,0 +1,12 @@
+from typing import Any, Protocol
+
+
+class {class_name}DataProvider(Protocol):
+    """
+    Contract for accessing {class_name} feature data.
+    Implementation (Client or Repository) is injected via DI.
+    """
+
+    async def get_data(self, user_id: int) -> Any:
+        """Example data retrieval method."""
+        ...

codex_bot/templates/feature/dto.py.tpl

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class {class_name}Payload(BaseModel):
+    """DTO for passing data within the {class_name} feature."""
+    id: int
+    # Add your fields here

codex_bot/templates/feature/feature.py.tpl

@@ -0,0 +1,26 @@
+from aiogram.fsm.state import State, StatesGroup
+
+# 1. State Definition
+class {class_name}States(StatesGroup):
+    main = State()
+
+STATES = {class_name}States
+
+# 2. Garbage Collector Settings
+GARBAGE_COLLECT = True
+
+# 3. Menu Settings
+MENU_CONFIG = {{
+    "key": "{feature_key}",
+    "text": "{class_name}",
+    "description": "Description of the {class_name} feature",
+    "target_state": "{feature_key}",
+    "priority": 50,
+    "is_admin": False,
+    "is_superuser": False,
+}}
+
+# 4. Factory (DI)
+def create_orchestrator(container):
+    from .logic.orchestrator import {class_name}Orchestrator
+    return {class_name}Orchestrator()

codex_bot/templates/feature/feature_redis.py.tpl

@@ -0,0 +1,6 @@
+def create_orchestrator(container):
+    """
+    Factory for creating the {class_name} feature orchestrator (Redis).
+    """
+    from .logic.orchestrator import {class_name}Orchestrator
+    return {class_name}Orchestrator()

codex_bot/templates/feature/formatters.py.tpl

@@ -0,0 +1,15 @@
+from typing import Any
+from .texts import {class_name}Texts
+
+
+class {class_name}Formatter:
+    """Message formatting for the {class_name} feature."""
+
+    def format_main(self, payload: Any) -> str:
+        """Formats the main screen text."""
+        user_name = payload.get("name", "User") if isinstance(payload, dict) else "User"
+        return (
+            f"{{{class_name}Texts.TITLE}}\n\n"
+            f"{{{class_name}Texts.DESCRIPTION}}\n"
+            f"User: {{user_name}}"
+        )

codex_bot/templates/feature/handlers.py.tpl

@@ -0,0 +1,32 @@
+from aiogram import Router, F
+from aiogram.types import CallbackQuery
+from aiogram.filters import StateFilter
+
+from codex_bot.director import Director
+from .feature_setting import {class_name}States
+from .resources.callbacks import {class_name}Callback
+
+router = Router(name="{feature_key}_router")
+
+@router.callback_query(
+    {class_name}Callback.filter(F.action == "action"),
+    StateFilter({class_name}States.main)
+)
+async def handle_action(
+    call: CallbackQuery,
+    callback_data: {class_name}Callback,
+    state,
+    container,
+):
+    await call.answer()
+
+    director = Director(
+        container=container,
+        state=state,
+        user_id=call.from_user.id,
+        chat_id=call.message.chat.id if call.message else None,
+    )
+    view_dto = await director.set_scene("{feature_key}", payload=callback_data)
+
+    if view_dto and hasattr(container, "view_sender"):
+        await container.view_sender.send(view_dto)

codex_bot/templates/feature/handlers_redis.py.tpl

@@ -0,0 +1,24 @@
+from typing import Any
+
+from loguru import logger as log
+from codex_bot.redis import RedisRouter
+
+# Router for events from Redis Stream
+redis_router = RedisRouter()
+
+
+@redis_router.message("your_event_type")
+async def handle_{feature_key}_event(message_data: dict[str, Any], container: Any):
+    """Handler for {class_name} events from Redis Stream.
+
+    Do NOT catch exceptions here — let them propagate to the dispatcher.
+    The dispatcher will trigger the retry scheduler if configured.
+    """
+    log.info(f"{class_name} | Processing event type='{message_data.get('type')}'")
+
+    orchestrator = container.{container_key}
+    view_sender = container.view_sender
+
+    # Processing logic:
+    # view_dto = await orchestrator.handle_event(message_data)
+    # await view_sender.send(view_dto)

codex_bot/templates/feature/keyboards.py.tpl

@@ -0,0 +1,14 @@
+from aiogram.utils.keyboard import InlineKeyboardBuilder
+from .callbacks import {class_name}Callback
+from .texts import {class_name}Texts
+
+
+def build_main_kb():
+    """Main screen keyboard."""
+    builder = InlineKeyboardBuilder()
+    builder.button(
+        text={class_name}Texts.BUTTON_ACTION,
+        callback_data={class_name}Callback(action="action", id=0).pack(),
+    )
+    builder.adjust(1)
+    return builder.as_markup()

codex_bot/templates/feature/orchestrator.py.tpl

@@ -0,0 +1,26 @@
+from typing import Any, TYPE_CHECKING
+
+from codex_bot.base import BaseBotOrchestrator, UnifiedViewDTO, ViewResultDTO
+from .ui.ui import {class_name}UI
+from .feature_setting import {class_name}States
+
+if TYPE_CHECKING:
+    from codex_bot.director import Director
+
+
+class {class_name}Orchestrator(BaseBotOrchestrator[Any]):
+    def __init__(self):
+        super().__init__(expected_state={class_name}States.main)
+        self.ui = {class_name}UI()
+
+    async def handle_entry(
+        self,
+        director: "Director",
+        payload: Any = None,
+    ) -> UnifiedViewDTO:
+        """Entry point into the feature. Called by Director on set_scene()."""
+        return await self.render(payload, director)
+
+    async def render_content(self, payload: Any, director: "Director") -> ViewResultDTO:
+        """Content rendering logic. Override to implement feature UI."""
+        return self.ui.render_main(payload)

codex_bot/templates/feature/orchestrator_redis.py.tpl

@@ -0,0 +1,17 @@
+from typing import Any
+
+from loguru import logger as log
+from codex_bot.base import UnifiedViewDTO
+
+
+class {class_name}Orchestrator:
+    """Orchestrator for the background feature {class_name} (Redis)."""
+
+    def __init__(self):
+        pass
+
+    def handle_event(self, payload: dict[str, Any]) -> UnifiedViewDTO:
+        """Incoming data processing."""
+        log.debug(f"{class_name}Orchestrator | Handling payload: {{payload}}")
+        # Implement logic here
+        raise NotImplementedError

codex_bot/templates/feature/texts.py.tpl

@@ -0,0 +1,6 @@
+class {class_name}Texts:
+    """Text constants for the {class_name} feature."""
+    TITLE = "👋 <b>{class_name}</b>"
+    DESCRIPTION = "This is the starting screen of the {class_name} feature."
+    BUTTON_ACTION = "Click me"
+    BUTTON_BACK = "🔙 Back"

codex_bot/templates/feature/ui.py.tpl

@@ -0,0 +1,19 @@
+from typing import Any
+
+from codex_bot.base import ViewResultDTO
+from .resources.formatters import {class_name}Formatter
+from .resources.keyboards import build_main_kb
+
+
+class {class_name}UI:
+    """
+    UI service for the {class_name} feature.
+    Uses formatters and keyboards from resources.
+    """
+    def __init__(self):
+        self.formatter = {class_name}Formatter()
+
+    def render_main(self, payload: Any) -> ViewResultDTO:
+        text = self.formatter.format_main(payload)
+        kb = build_main_kb()
+        return ViewResultDTO(text=text, kb=kb)

codex_bot/url_signer/__init__.py

@@ -0,0 +1,7 @@
+"""
+codex_bot.url_signer — Generation of HMAC-signed URLs.
+"""
+
+from codex_bot.url_signer.service import UrlSignerService
+
+__all__ = ["UrlSignerService"]