bot-framework 0.1.3__py3-none-any.whl

bot_framework/flow_management/services/flow_stack_navigator.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+
+from bot_framework.entities.user import User
+from bot_framework.flow_management.entities import FlowStackEntry
+from bot_framework.flow_management.flow_registry import FlowRegistry
+from bot_framework.flow_management.protocols import (
+    IFlowMessageDeleter,
+    IFlowStackStorage,
+    IFlowStackValidator,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FlowStackNavigator:
+    def __init__(
+        self,
+        storage: IFlowStackStorage,
+        registry: FlowRegistry,
+        validator: IFlowStackValidator,
+        message_deleter: IFlowMessageDeleter | None = None,
+    ):
+        self._storage = storage
+        self._registry = registry
+        self._validator = validator
+        self._message_deleter = message_deleter
+
+    def push(self, user: User, flow_name: str) -> None:
+        self._validator.validate_push(user.id, flow_name)
+
+        stack = self._storage.get_stack(user.id)
+        entry = FlowStackEntry(flow_name=flow_name, started_at=datetime.now(UTC))
+        self._storage.push(user.id, entry)
+
+        logger.info(
+            f"Flow pushed for user {user.id}: {flow_name}. "
+            f"Stack depth: {len(stack) + 1}"
+        )
+
+    def pop_and_return(self, user: User) -> None:
+        current_entry = self._storage.pop(user.id)
+        if not current_entry:
+            logger.warning(f"No flow to pop for user {user.id}")
+            return
+
+        self._clean_flow_messages(user.id, current_entry.flow_name)
+
+        logger.info(
+            f"Flow popped for user {user.id}: {current_entry.flow_name}. "
+            f"Duration: {datetime.now(UTC) - current_entry.started_at}"
+        )
+
+        remaining_stack = self._storage.get_stack(user.id)
+        if not remaining_stack:
+            logger.info(f"Flow stack empty for user {user.id}")
+            return
+
+        parent_entry = remaining_stack[-1]
+        parent_flow = self._registry.get(parent_entry.flow_name)
+        if not parent_flow:
+            logger.error(
+                f"Parent flow '{parent_entry.flow_name}' not found in registry"
+            )
+            return
+
+        logger.info(
+            f"Returning to parent flow for user {user.id}: {parent_entry.flow_name}"
+        )
+        parent_flow.start(user)
+
+    def terminate(self, user: User) -> None:
+        current_entry = self._storage.pop(user.id)
+        if not current_entry:
+            logger.warning(f"No flow to terminate for user {user.id}")
+            return
+
+        self._clean_flow_messages(user.id, current_entry.flow_name)
+
+        logger.info(
+            f"Flow terminated for user {user.id}: {current_entry.flow_name}. "
+            f"Duration: {datetime.now(UTC) - current_entry.started_at}"
+        )
+
+    def is_flow_in_stack(self, user: User, flow_name: str) -> bool:
+        stack = self._storage.get_stack(user.id)
+        return flow_name in [entry.flow_name for entry in stack]
+
+    def clear_all(self, user: User) -> None:
+        stack = self._storage.get_stack(user.id)
+
+        if self._message_deleter and stack:
+            for entry in stack:
+                self._message_deleter.delete_flow_messages(user.id, entry.flow_name)
+
+        if stack:
+            logger.info(f"Clearing flow stack for user {user.id}. Depth: {len(stack)}")
+        self._storage.clear(user.id)
+
+    def _clean_flow_messages(self, chat_id: int, flow_name: str) -> None:
+        if self._message_deleter:
+            self._message_deleter.delete_flow_messages(chat_id, flow_name)

bot_framework/flow_management/services/flow_stack_validator.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import logging
+
+from bot_framework.flow_management.flow_registry import FlowRegistry
+from bot_framework.flow_management.protocols import IFlowStackStorage
+
+logger = logging.getLogger(__name__)
+
+
+class FlowStackValidator:
+    MAX_STACK_DEPTH = 5
+
+    def __init__(
+        self,
+        storage: IFlowStackStorage,
+        registry: FlowRegistry,
+    ):
+        self._storage = storage
+        self._registry = registry
+
+    def validate_push(self, user_id: int, flow_name: str) -> None:
+        stack = self._storage.get_stack(user_id)
+
+        if len(stack) >= self.MAX_STACK_DEPTH:
+            logger.error(
+                f"Flow stack depth exceeded for user {user_id}. "
+                f"Max depth: {self.MAX_STACK_DEPTH}"
+            )
+            raise ValueError(
+                f"Maximum flow stack depth ({self.MAX_STACK_DEPTH}) exceeded"
+            )
+
+        flow_names_in_stack = [entry.flow_name for entry in stack]
+        if flow_name in flow_names_in_stack:
+            logger.error(
+                f"Circular flow dependency detected for user {user_id}: "
+                f"{flow_names_in_stack} -> {flow_name}"
+            )
+            raise ValueError(
+                f"Circular flow dependency detected: {flow_name} is already in stack"
+            )
+
+        if not self._registry.get(flow_name):
+            logger.error(f"Flow '{flow_name}' not found in registry")
+            raise ValueError(f"Flow '{flow_name}' not registered")

bot_framework/flows/__init__.py

@@ -0,0 +1,11 @@
+from bot_framework.flows.request_role_flow import (
+    IRequestRoleFlowRouter,
+    RequestRoleFlowFactory,
+    RequestRoleFlowRouter,
+)
+
+__all__ = [
+    "IRequestRoleFlowRouter",
+    "RequestRoleFlowFactory",
+    "RequestRoleFlowRouter",
+]

bot_framework/flows/request_role_flow/__init__.py

@@ -0,0 +1,11 @@
+from bot_framework.flows.request_role_flow.factory import RequestRoleFlowFactory
+from bot_framework.flows.request_role_flow.protocols import IRequestRoleFlowRouter
+from bot_framework.flows.request_role_flow.request_role_flow_router import (
+    RequestRoleFlowRouter,
+)
+
+__all__ = [
+    "IRequestRoleFlowRouter",
+    "RequestRoleFlowFactory",
+    "RequestRoleFlowRouter",
+]

bot_framework/flows/request_role_flow/actions/__init__.py

@@ -0,0 +1,13 @@
+from bot_framework.flows.request_role_flow.actions.role_assigner import RoleAssigner
+from bot_framework.flows.request_role_flow.actions.role_rejection_notifier import (
+    RoleRejectionNotifier,
+)
+from bot_framework.flows.request_role_flow.actions.role_request_sender import (
+    RoleRequestSender,
+)
+
+__all__ = [
+    "RoleAssigner",
+    "RoleRejectionNotifier",
+    "RoleRequestSender",
+]

bot_framework/flows/request_role_flow/actions/role_assigner.py

@@ -0,0 +1,30 @@
+from bot_framework.language_management.repos.protocols.i_phrase_repo import IPhraseRepo
+from bot_framework.protocols.i_message_sender import IMessageSender
+from bot_framework.role_management.repos.protocols.i_role_repo import IRoleRepo
+
+
+class RoleAssigner:
+    def __init__(
+        self,
+        message_sender: IMessageSender,
+        phrase_repo: IPhraseRepo,
+        role_repo: IRoleRepo,
+    ) -> None:
+        self.message_sender = message_sender
+        self.phrase_repo = phrase_repo
+        self.role_repo = role_repo
+
+    def assign_and_notify(
+        self,
+        user_id: int,
+        role_id: int,
+        language_code: str,
+    ) -> None:
+        self.role_repo.assign_role(user_id=user_id, role_id=role_id)
+
+        text = self.phrase_repo.get_phrase(
+            key="request_role.approved",
+            language_code=language_code,
+        )
+
+        self.message_sender.send(chat_id=user_id, text=text)

bot_framework/flows/request_role_flow/actions/role_rejection_notifier.py

@@ -0,0 +1,24 @@
+from bot_framework.language_management.repos.protocols.i_phrase_repo import IPhraseRepo
+from bot_framework.protocols.i_message_sender import IMessageSender
+
+
+class RoleRejectionNotifier:
+    def __init__(
+        self,
+        message_sender: IMessageSender,
+        phrase_repo: IPhraseRepo,
+    ) -> None:
+        self.message_sender = message_sender
+        self.phrase_repo = phrase_repo
+
+    def notify(
+        self,
+        user_id: int,
+        language_code: str,
+    ) -> None:
+        text = self.phrase_repo.get_phrase(
+            key="request_role.rejected",
+            language_code=language_code,
+        )
+
+        self.message_sender.send(chat_id=user_id, text=text)

bot_framework/flows/request_role_flow/actions/role_request_sender.py

@@ -0,0 +1,74 @@
+from bot_framework.entities.button import Button
+from bot_framework.entities.keyboard import Keyboard
+from bot_framework.entities.role import Role
+from bot_framework.entities.user import User
+from bot_framework.flows.request_role_flow.exceptions import NoSupervisorsFoundError
+from bot_framework.language_management.repos.protocols.i_phrase_repo import IPhraseRepo
+from bot_framework.protocols.i_message_sender import IMessageSender
+from bot_framework.role_management.repos.protocols.i_user_repo import IUserRepo
+
+
+class RoleRequestSender:
+    def __init__(
+        self,
+        message_sender: IMessageSender,
+        phrase_repo: IPhraseRepo,
+        user_repo: IUserRepo,
+        approve_handler_prefix: str,
+        reject_handler_prefix: str,
+    ) -> None:
+        self.message_sender = message_sender
+        self.phrase_repo = phrase_repo
+        self.user_repo = user_repo
+        self.approve_handler_prefix = approve_handler_prefix
+        self.reject_handler_prefix = reject_handler_prefix
+
+    def send_to_supervisors(
+        self,
+        requester: User,
+        role: Role,
+    ) -> None:
+        supervisors = self.user_repo.get_by_role_name(role_name="supervisors")
+        if not supervisors:
+            raise NoSupervisorsFoundError()
+
+        for supervisor in supervisors:
+            language_code = supervisor.language_code
+
+            title = self.phrase_repo.get_phrase(
+                key="request_role.supervisor.title",
+                language_code=language_code,
+            )
+
+            requester_name = requester.username or requester.first_name or str(requester.id)
+            text = f"{title}\n\nUser: {requester_name}\nRole: {role.name}"
+
+            approve_text = self.phrase_repo.get_phrase(
+                key="request_role.button.approve",
+                language_code=language_code,
+            )
+            reject_text = self.phrase_repo.get_phrase(
+                key="request_role.button.reject",
+                language_code=language_code,
+            )
+
+            keyboard = Keyboard(
+                rows=[
+                    [
+                        Button(
+                            text=approve_text,
+                            callback_data=f"{self.approve_handler_prefix}:{role.id}:{requester.id}",
+                        ),
+                        Button(
+                            text=reject_text,
+                            callback_data=f"{self.reject_handler_prefix}:{role.id}:{requester.id}",
+                        ),
+                    ]
+                ]
+            )
+
+            self.message_sender.send(
+                chat_id=supervisor.id,
+                text=text,
+                keyboard=keyboard,
+            )

bot_framework/flows/request_role_flow/entities/__init__.py

@@ -0,0 +1,7 @@
+from bot_framework.flows.request_role_flow.entities.request_role_flow_state import (
+    RequestRoleFlowState,
+)
+
+__all__ = [
+    "RequestRoleFlowState",
+]

bot_framework/flows/request_role_flow/entities/request_role_flow_state.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class RequestRoleFlowState(BaseModel):
+    requester_user_id: int
+    selected_role_id: int | None = None

bot_framework/flows/request_role_flow/exceptions.py

@@ -0,0 +1,6 @@
+class NoSupervisorsFoundError(Exception):
+    pass
+
+
+class UserAlreadyHasRoleError(Exception):
+    pass

bot_framework/flows/request_role_flow/factory.py

@@ -0,0 +1,146 @@
+from bot_framework.flows.request_role_flow.actions import (
+    RoleAssigner,
+    RoleRejectionNotifier,
+    RoleRequestSender,
+)
+from bot_framework.flows.request_role_flow.handlers import (
+    ApproveRoleHandler,
+    RejectRoleHandler,
+    RequestRoleCommandHandler,
+    RoleSelectionHandler,
+    ShowRolesHandler,
+)
+from bot_framework.flows.request_role_flow.presenters import RoleListPresenter
+from bot_framework.flows.request_role_flow.protocols import (
+    IRequestRoleFlowRouter,
+    IRequestRoleFlowStateStorage,
+)
+from bot_framework.flows.request_role_flow.request_role_flow_router import (
+    RequestRoleFlowRouter,
+)
+from bot_framework.language_management.repos.protocols.i_phrase_repo import IPhraseRepo
+from bot_framework.protocols.i_callback_answerer import ICallbackAnswerer
+from bot_framework.protocols.i_callback_handler_registry import (
+    ICallbackHandlerRegistry,
+)
+from bot_framework.protocols.i_message_handler_registry import IMessageHandlerRegistry
+from bot_framework.protocols.i_message_sender import IMessageSender
+from bot_framework.role_management.repos.protocols.i_role_repo import IRoleRepo
+from bot_framework.role_management.repos.protocols.i_user_repo import IUserRepo
+
+
+class RequestRoleFlowFactory:
+    def __init__(
+        self,
+        callback_answerer: ICallbackAnswerer,
+        message_sender: IMessageSender,
+        phrase_repo: IPhraseRepo,
+        role_repo: IRoleRepo,
+        user_repo: IUserRepo,
+        state_storage: IRequestRoleFlowStateStorage,
+    ) -> None:
+        self.callback_answerer = callback_answerer
+        self.message_sender = message_sender
+        self.phrase_repo = phrase_repo
+        self.role_repo = role_repo
+        self.user_repo = user_repo
+        self.state_storage = state_storage
+
+        self._show_roles_handler: ShowRolesHandler | None = None
+        self._role_selection_handler: RoleSelectionHandler | None = None
+        self._approve_handler: ApproveRoleHandler | None = None
+        self._reject_handler: RejectRoleHandler | None = None
+
+    def _get_approve_handler(self) -> ApproveRoleHandler:
+        if self._approve_handler is None:
+            self._approve_handler = ApproveRoleHandler(
+                callback_answerer=self.callback_answerer,
+                role_repo=self.role_repo,
+                user_repo=self.user_repo,
+                role_assigner=RoleAssigner(
+                    message_sender=self.message_sender,
+                    phrase_repo=self.phrase_repo,
+                    role_repo=self.role_repo,
+                ),
+            )
+        return self._approve_handler
+
+    def _get_reject_handler(self) -> RejectRoleHandler:
+        if self._reject_handler is None:
+            self._reject_handler = RejectRoleHandler(
+                callback_answerer=self.callback_answerer,
+                role_repo=self.role_repo,
+                user_repo=self.user_repo,
+                role_rejection_notifier=RoleRejectionNotifier(
+                    message_sender=self.message_sender,
+                    phrase_repo=self.phrase_repo,
+                ),
+            )
+        return self._reject_handler
+
+    def _get_role_selection_handler(self) -> RoleSelectionHandler:
+        if self._role_selection_handler is None:
+            approve_handler = self._get_approve_handler()
+            reject_handler = self._get_reject_handler()
+
+            self._role_selection_handler = RoleSelectionHandler(
+                callback_answerer=self.callback_answerer,
+                message_sender=self.message_sender,
+                phrase_repo=self.phrase_repo,
+                role_repo=self.role_repo,
+                user_repo=self.user_repo,
+                state_storage=self.state_storage,
+                role_request_sender=RoleRequestSender(
+                    message_sender=self.message_sender,
+                    phrase_repo=self.phrase_repo,
+                    user_repo=self.user_repo,
+                    approve_handler_prefix=approve_handler.prefix,
+                    reject_handler_prefix=reject_handler.prefix,
+                ),
+            )
+        return self._role_selection_handler
+
+    def _get_show_roles_handler(self) -> ShowRolesHandler:
+        if self._show_roles_handler is None:
+            role_selection_handler = self._get_role_selection_handler()
+
+            self._show_roles_handler = ShowRolesHandler(
+                callback_answerer=self.callback_answerer,
+                role_list_presenter=RoleListPresenter(
+                    message_sender=self.message_sender,
+                    phrase_repo=self.phrase_repo,
+                    role_repo=self.role_repo,
+                    role_selection_handler_prefix=role_selection_handler.prefix,
+                ),
+            )
+        return self._show_roles_handler
+
+    def create_router(self) -> IRequestRoleFlowRouter:
+        role_selection_handler = self._get_role_selection_handler()
+
+        role_list_presenter = RoleListPresenter(
+            message_sender=self.message_sender,
+            phrase_repo=self.phrase_repo,
+            role_repo=self.role_repo,
+            role_selection_handler_prefix=role_selection_handler.prefix,
+        )
+
+        return RequestRoleFlowRouter(role_list_presenter=role_list_presenter)
+
+    def register_handlers(
+        self,
+        callback_registry: ICallbackHandlerRegistry,
+        message_registry: IMessageHandlerRegistry,
+    ) -> None:
+        callback_registry.register(self._get_show_roles_handler())
+        callback_registry.register(self._get_role_selection_handler())
+        callback_registry.register(self._get_approve_handler())
+        callback_registry.register(self._get_reject_handler())
+
+        router = self.create_router()
+        command_handler = RequestRoleCommandHandler(request_role_flow_router=router)
+        message_registry.register(
+            handler=command_handler,
+            commands=["request_role"],
+            content_types=["text"],
+        )

bot_framework/flows/request_role_flow/handlers/__init__.py

@@ -0,0 +1,23 @@
+from bot_framework.flows.request_role_flow.handlers.approve_role_handler import (
+    ApproveRoleHandler,
+)
+from bot_framework.flows.request_role_flow.handlers.reject_role_handler import (
+    RejectRoleHandler,
+)
+from bot_framework.flows.request_role_flow.handlers.request_role_command_handler import (
+    RequestRoleCommandHandler,
+)
+from bot_framework.flows.request_role_flow.handlers.role_selection_handler import (
+    RoleSelectionHandler,
+)
+from bot_framework.flows.request_role_flow.handlers.show_roles_handler import (
+    ShowRolesHandler,
+)
+
+__all__ = [
+    "ApproveRoleHandler",
+    "RejectRoleHandler",
+    "RequestRoleCommandHandler",
+    "RoleSelectionHandler",
+    "ShowRolesHandler",
+]

bot_framework/flows/request_role_flow/handlers/approve_role_handler.py

@@ -0,0 +1,48 @@
+from uuid import uuid4
+
+from bot_framework.entities.bot_callback import BotCallback
+from bot_framework.flows.request_role_flow.protocols import IRoleAssigner
+from bot_framework.protocols.i_callback_answerer import ICallbackAnswerer
+from bot_framework.role_management.repos.protocols.i_role_repo import IRoleRepo
+from bot_framework.role_management.repos.protocols.i_user_repo import IUserRepo
+
+
+class ApproveRoleHandler:
+    def __init__(
+        self,
+        callback_answerer: ICallbackAnswerer,
+        role_repo: IRoleRepo,
+        user_repo: IUserRepo,
+        role_assigner: IRoleAssigner,
+    ) -> None:
+        self.callback_answerer = callback_answerer
+        self.role_repo = role_repo
+        self.user_repo = user_repo
+        self.role_assigner = role_assigner
+        self.prefix = uuid4().hex
+        self.allowed_roles: set[str] | None = None
+
+    def handle(self, callback: BotCallback) -> None:
+        self.callback_answerer.answer(callback_query_id=callback.id)
+
+        if not callback.data:
+            raise ValueError("callback.data is required but was None")
+
+        parts = callback.data.split(":")
+        if len(parts) < 3:
+            raise ValueError(f"Invalid callback data format: {callback.data}")
+
+        role_id = int(parts[1])
+        user_id = int(parts[2])
+
+        user = self.user_repo.find_by_id(id=user_id)
+        if not user:
+            return
+
+        language_code = user.language_code
+
+        self.role_assigner.assign_and_notify(
+            user_id=user_id,
+            role_id=role_id,
+            language_code=language_code,
+        )

bot_framework/flows/request_role_flow/handlers/reject_role_handler.py

@@ -0,0 +1,46 @@
+from uuid import uuid4
+
+from bot_framework.entities.bot_callback import BotCallback
+from bot_framework.flows.request_role_flow.protocols import IRoleRejectionNotifier
+from bot_framework.protocols.i_callback_answerer import ICallbackAnswerer
+from bot_framework.role_management.repos.protocols.i_role_repo import IRoleRepo
+from bot_framework.role_management.repos.protocols.i_user_repo import IUserRepo
+
+
+class RejectRoleHandler:
+    def __init__(
+        self,
+        callback_answerer: ICallbackAnswerer,
+        role_repo: IRoleRepo,
+        user_repo: IUserRepo,
+        role_rejection_notifier: IRoleRejectionNotifier,
+    ) -> None:
+        self.callback_answerer = callback_answerer
+        self.role_repo = role_repo
+        self.user_repo = user_repo
+        self.role_rejection_notifier = role_rejection_notifier
+        self.prefix = uuid4().hex
+        self.allowed_roles: set[str] | None = None
+
+    def handle(self, callback: BotCallback) -> None:
+        self.callback_answerer.answer(callback_query_id=callback.id)
+
+        if not callback.data:
+            raise ValueError("callback.data is required but was None")
+
+        parts = callback.data.split(":")
+        if len(parts) < 3:
+            raise ValueError(f"Invalid callback data format: {callback.data}")
+
+        user_id = int(parts[2])
+
+        user = self.user_repo.find_by_id(id=user_id)
+        if not user:
+            return
+
+        language_code = user.language_code
+
+        self.role_rejection_notifier.notify(
+            user_id=user_id,
+            language_code=language_code,
+        )

bot_framework/flows/request_role_flow/handlers/request_role_command_handler.py

@@ -0,0 +1,24 @@
+from bot_framework.entities.bot_message import BotMessage
+from bot_framework.flows.request_role_flow.protocols import (
+    IRequestRoleFlowRouter,
+)
+from bot_framework.protocols.i_message_handler import IMessageHandler
+
+
+class RequestRoleCommandHandler(IMessageHandler):
+    allowed_roles: set[str] | None = None
+
+    def __init__(
+        self,
+        request_role_flow_router: IRequestRoleFlowRouter,
+    ) -> None:
+        self.request_role_flow_router = request_role_flow_router
+
+    def handle(self, message: BotMessage) -> None:
+        if not message.from_user:
+            raise ValueError("message.from_user is required but was None")
+
+        self.request_role_flow_router.start(
+            user=message.from_user,
+            chat_id=message.chat_id,
+        )