codex-bot 0.1.0__py3-none-any.whl

codex_bot/url_signer/service.py

@@ -0,0 +1,116 @@
+"""
+UrlSignerService — Generation of HMAC-signed URLs for Telegram Mini Apps.
+
+Provides protection against link forgery with a limited lifetime.
+"""
+
+import hashlib
+import hmac
+import time
+from urllib.parse import quote_plus, urlencode
+
+
+class UrlSignerService:
+    """Generation of HMAC-signed URLs for Telegram Mini Apps.
+
+    Signs URLs using HMAC-SHA256 and a timestamp.
+    This protects against forgery and limits the link's lifetime.
+
+    Args:
+        secret_key: Secret key for signing (string).
+
+    Example:
+        ```python
+        signer = UrlSignerService(secret_key=settings.secret_key)
+        url = signer.generate_signed_url(
+            base_url="https://myapp.example.com",
+            request_id=42,
+            action="reply",
+        )
+        # https://myapp.example.com/tma/reply/?req_id=42&ts=...&sig=...
+        ```
+    """
+
+    def __init__(self, secret_key: str) -> None:
+        self._secret_key = secret_key.encode("utf-8")
+
+    def generate_signed_url(
+        self,
+        base_url: str,
+        request_id: str | int,
+        action: str = "reply",
+    ) -> str:
+        """Generates a signed URL for a WebApp.
+
+        Builds a URL of the form:
+        ``{base_url}/tma/{action}/?req_id=...&ts=...&sig=...``
+
+        The signature is calculated based on the string ``"{request_id}:{timestamp}"``.
+
+        Args:
+            base_url: Root URL of the site (e.g., ``"https://myapp.example.com"``).
+            request_id: Request ID included in the signature.
+            action: Action path (default is ``"reply"``).
+
+        Returns:
+            Full URL with signature parameters.
+
+        Example:
+            ```python
+            url = signer.generate_signed_url(
+                base_url="https://myapp.example.com",
+                request_id=123,
+                action="confirm",
+            )
+            ```
+        """
+        timestamp = str(int(time.time()))
+        req_id_str = str(request_id)
+
+        payload = f"{req_id_str}:{timestamp}".encode()
+        signature = hmac.new(self._secret_key, payload, hashlib.sha256).hexdigest()
+
+        params = {"req_id": req_id_str, "ts": timestamp, "sig": signature}
+        clean_base_url = base_url.rstrip("/")
+
+        return f"{clean_base_url}/tma/{action}/?{urlencode(params, quote_via=quote_plus)}"
+
+    def verify_signed_url(
+        self,
+        req_id: str,
+        timestamp: str,
+        signature: str,
+        max_age: int = 300,
+    ) -> bool:
+        """Verifies the URL signature.
+
+        Args:
+            req_id: Request ID from the ``req_id`` parameter.
+            timestamp: Timestamp from the ``ts`` parameter.
+            signature: Signature from the ``sig`` parameter.
+            max_age: Maximum signature age in seconds (default is 300).
+
+        Returns:
+            ``True`` if the signature is valid and has not expired.
+
+        Example:
+            ```python
+            is_valid = signer.verify_signed_url(
+                req_id=request.query_params["req_id"],
+                timestamp=request.query_params["ts"],
+                signature=request.query_params["sig"],
+            )
+            ```
+        """
+        try:
+            ts_int = int(timestamp)
+        except ValueError:
+            return False
+
+        if int(time.time()) - ts_int > max_age:
+            return False
+
+        payload = f"{req_id}:{timestamp}".encode()
+        expected = hmac.new(self._secret_key, payload, hashlib.sha256).hexdigest()
+
+        return hmac.compare_digest(expected, signature)

codex_bot-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: codex-bot
+Version: 0.1.0
+Summary: Feature-based Aiogram framework library — reusable infrastructure for Telegram bots
+Author: Codex Team
+License: MIT
+License-File: LICENSE
+Keywords: aiogram,bot,framework,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: aiogram<4.0,>=3.4
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: all
+Requires-Dist: aiogram-i18n>=1.4; extra == 'all'
+Requires-Dist: arq>=0.25; extra == 'all'
+Requires-Dist: httpx<1.0,>=0.27; extra == 'all'
+Requires-Dist: redis[asyncio]<6.0,>=5.0; extra == 'all'
+Provides-Extra: arq
+Requires-Dist: arq>=0.25; extra == 'arq'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: http
+Requires-Dist: httpx<1.0,>=0.27; extra == 'http'
+Provides-Extra: i18n
+Requires-Dist: aiogram-i18n>=1.4; extra == 'i18n'
+Provides-Extra: redis
+Requires-Dist: redis[asyncio]<6.0,>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Codex Bot Framework
+
+[![PyPI version](https://img.shields.io/pypi/v/codex-bot.svg)](https://pypi.org/project/codex-bot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codex-bot.svg)](https://pypi.org/project/codex-bot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Codex Bot** is a professional, feature-based framework built on top of [Aiogram 3.x](https://github.com/aiogram/aiogram). It provides a reusable, production-ready infrastructure for building complex, scalable Telegram bots with a focus on stateless UI management and high-load Redis integration.
+
+---
+
+## 🚀 Key Features
+
+- **Feature-based Architecture**: Organize your bot into independent, reusable features.
+- **Stateless Orchestrators**: Manage UI logic without storing state in memory, making your bot horizontally scalable.
+- **Redis Stream Integration**: Native support for high-load event processing with Consumer Groups.
+- **Advanced FSM**: Automatic UI cleanup with `GarbageStateRegistry` and structured state management.
+- **Unified View System**: Consistent message rendering across different platforms using DTOs.
+- **Fluent-based I18n**: Powerful localization engine with project-level isolation and automatic compilation.
+- **CLI Scaffolding**: Rapidly generate new features with pre-defined templates.
+
+---
+
+## 📦 Installation
+
+Install the core library:
+```bash
+pip install codex-bot
+```
+
+Install with optional dependencies:
+```bash
+pip install "codex-bot[redis,i18n,http]"
+```
+
+---
+
+## 🛠 Quick Start
+
+```python
+from codex_bot import BotBuilder, BaseBotOrchestrator, Director
+from codex_bot.base.view_dto import ViewResultDTO
+
+# 1. Define your feature orchestrator
+class MyFeatureOrchestrator(BaseBotOrchestrator[None]):
+    async def render_content(self, payload: None, director: Director) -> ViewResultDTO:
+        return ViewResultDTO(text="Hello from Codex Bot!")
+
+# 2. Build and run your bot
+builder = BotBuilder(token="YOUR_TELEGRAM_TOKEN")
+builder.register_orchestrator("main", MyFeatureOrchestrator())
+builder.run_polling()
+```
+
+---
+
+## 📚 Documentation
+
+- [English Documentation](https://codex-team.github.io/codex_bot/en_EN/)
+- [Русская документация](https://codex-team.github.io/codex_bot/ru_RU/)
+- [**Changelog**](CHANGELOG.md) — see what's new in the latest versions.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+
+---
+
+### 🇷🇺 Краткое описание (RU)
+**Codex Bot** — это профессиональный фреймворк для создания Telegram-ботов на базе Aiogram 3.x. Он предоставляет готовую инфраструктуру для разработки сложных и масштабируемых систем, используя архитектуру на основе "фич", stateless-оркестраторы и глубокую интеграцию с Redis Streams.

codex_bot-0.1.0.dist-info/RECORD

@@ -0,0 +1,64 @@
+codex_bot/__init__.py,sha256=i4FE75TbJxcG9ygMDQBBm_iChgZP6FwG4WTXLFPII5M,628
+codex_bot/animation/__init__.py,sha256=2XBHp1mea4gcPlV07jHlIkxnfBvvMMo3nVUdACEXTBo,222
+codex_bot/animation/animation_service.py,sha256=FCbtnMZfh7soxOqeHdDE17GXwU1e1l9_O7KrwiPxowQ,9971
+codex_bot/base/__init__.py,sha256=pA3daayrcwK6zunSqqDGnmnYGLbNOrL0kUoxIl0tPbc,485
+codex_bot/base/base_orchestrator.py,sha256=fiQd8T3d28jN-BBUT-m7RvjQsIBi536x0r2viq8RFd4,4155
+codex_bot/base/context_dto.py,sha256=rUly2txZBpX_Y6o3AqQD-mvRT26B5aSeutpxAkO91hE,1242
+codex_bot/base/view_dto.py,sha256=6byxHY9_wZfeMewPdeOdgDEpVz96GsxA9ARigXL6Jzw,2894
+codex_bot/cli/__init__.py,sha256=8KCnN-1PIk848IAvixrhhl5gpcAxo3yR7gfTTvAAmRQ,217
+codex_bot/cli/commands.py,sha256=G24tL9-XJ4E8RFixMlu9PmZLWwyhqU8zonKhtCFGO6c,7491
+codex_bot/director/__init__.py,sha256=16Ttsvi7_HgiXgn5sDqIOemU6_eK4uAvdVL6XZyMIWY,316
+codex_bot/director/director.py,sha256=-KLOAWiaFV-VWa6tW4DIctbSst3Af97HE8q4LONP4kc,3878
+codex_bot/director/protocols.py,sha256=HV36pEnerBzE7s9ite9wMeNLPG5ZAVIVLhV3hJiseD8,2315
+codex_bot/engine/__init__.py,sha256=7diEGgyoEzq7cJqEhLkDxt8VsYv-o2x3627IKRFObgQ,715
+codex_bot/engine/discovery/__init__.py,sha256=Wj2Z8DCofYfeZSLZjDXWgKkkY9XRN5RW8e1ok_qxcU4,186
+codex_bot/engine/discovery/service.py,sha256=NzQmZj92HvSkRCHpk04-g-d4ryFclwJop9wKpIa_9WY,9994
+codex_bot/engine/factory/__init__.py,sha256=AdOmNzrbGamgPF5nhC425mzM1GTti7N8KhnjxeCVJ2E,166
+codex_bot/engine/factory/bot_builder.py,sha256=NQHRLNXBeg7Ih7NdH0HXz2c0ZJnANFR3W4ztXPowiPg,3577
+codex_bot/engine/http/__init__.py,sha256=XRpHndeYd3advmtKMeXNOZg_DvyVS30_YcW66Bc7Dh4,192
+codex_bot/engine/http/api_client.py,sha256=ERlBSLtF5vNO0HeAK5qJK-rkenz2fhbuEmwszdJAuFo,3949
+codex_bot/engine/i18n/__init__.py,sha256=q75bVn4OhlwQvbw08j--BxDApNZeAdSnUC5THmeNTUA,171
+codex_bot/engine/i18n/locales_compiler.py,sha256=5h-lH_7C25BFudY096tLBrZPcgXtY3D5o6K8Z8FDHM0,3006
+codex_bot/engine/middlewares/__init__.py,sha256=aSKBUER9Q9p6T7DzFqOPoO7OLC-9Q0cfTe2UtibnVqo,899
+codex_bot/engine/middlewares/container.py,sha256=ZYcx1u789jySMFcysWtQD1ejktWabNxu_blptFpzJnw,1376
+codex_bot/engine/middlewares/i18n.py,sha256=TJyDmh4iH_h5EXSy9bp_eJ_ohgKKBlMdee5rB29fkOs,2849
+codex_bot/engine/middlewares/throttling.py,sha256=Q9UIlHElqYWLavbsZ5itXOyxTbzzJqB1F6q7dw74X1M,2338
+codex_bot/engine/middlewares/user_validation.py,sha256=33bKB2Pd8JLzw0W434kGsleo0XcqDMegFS2bp7-PVsA,1519
+codex_bot/engine/router_builder/__init__.py,sha256=bCF3AfTQqykHMHf9xakkldRc_3RwvHJt2XSn0B0adLU,258
+codex_bot/engine/router_builder/router_builder.py,sha256=3Z6UDLw-K0YTYCOiZKixgfxDabpJVR62CC78Bh5dKtU,4852
+codex_bot/fsm/__init__.py,sha256=pmxqkx9agSj-ly7bkVpl4EMm3cvt_2BbybJPfBao0og,426
+codex_bot/fsm/common_fsm_handlers.py,sha256=0zZAFI3Rvjnprb545z3qp69S9DMiaz_QzovMBsTH66A,1524
+codex_bot/fsm/garbage_collector.py,sha256=qZdPzsAi3o_YqeOxLBipRkZboCALJFetcXTwo0uaB6E,4223
+codex_bot/fsm/state_helper.py,sha256=0_BTUncXfkZqWorTuJSwThtuaDm9_sXTIYBriHlEhhE,2178
+codex_bot/fsm/state_manager.py,sha256=EeNSWKlwDauuvuN0lh1Nks6zE9zzxWGOZfmfBFT8FXk,3128
+codex_bot/helper/__init__.py,sha256=Ds3_jmp1dBQukVLoz7DlqDCNYI78_iIGMDFrSk2WE-E,172
+codex_bot/helper/context_helper.py,sha256=BTYdld7Akx0T8pIste8fjGqgeKD3mnv_NQzbzQrK3lg,1896
+codex_bot/redis/__init__.py,sha256=mC7QUFTHgFeuwo3YrDFiTiFQYWtxq67I_eaEYvLLueM,442
+codex_bot/redis/dispatcher.py,sha256=zPMH-V9FyygsRLx1E_LdgzJLEStqWCKnWhL6Ig7-ntI,5976
+codex_bot/redis/router.py,sha256=6XysipG2Kc5srgZRn2MUuYTrycct6o7m2vnRt5ba-cE,2281
+codex_bot/redis/stream_processor.py,sha256=oig3XGCsWP71mqrAP2Xun9SDUh9IOcHwSPuVxA3h4-E,7677
+codex_bot/sender/__init__.py,sha256=hJKDzaSor4rVxqMCI4SYRdhQzuOaj_J_i4IaDvBM2U8,428
+codex_bot/sender/protocols.py,sha256=OGQCqRXNg6x0prZf1NUuY_vh8HfziVMfl8fjwtHS4lY,2138
+codex_bot/sender/sender_keys.py,sha256=xp5SXpW8w0T5mcF7dYShlVlg3RZBOFy06-ew0FRpQLU,1300
+codex_bot/sender/sender_manager.py,sha256=7WJeDh_fJvz_CFYrTIqN6ixTMcHH6FLz5rupCrIdzpg,2805
+codex_bot/sender/view_sender.py,sha256=qNSUyI7CLfqFMKivxN71jhwZlyBDsal3xs2gv0Y6oNQ,7170
+codex_bot/templates/feature/callbacks.py.tpl,sha256=yZ9OYg2eW_5uOreSvi111SsRROezmbPhEd-J-E6oPXY,564
+codex_bot/templates/feature/contract.py.tpl,sha256=0muFQG9BwyRAEpO6oD85a17h1fk-Lwwg87tGYnuxL7A,318
+codex_bot/templates/feature/dto.py.tpl,sha256=GtTL3A641Web3IWJJVmx86OVkEEcZp8VoeIeT8-KLls,174
+codex_bot/templates/feature/feature.py.tpl,sha256=FovoRZDZ1QdJprSJ929_GRD85eoVIZnqBktH1Ok2B5g,634
+codex_bot/templates/feature/feature_redis.py.tpl,sha256=g7k0pppF5OTmtoT7sDv4x2UqZ-sPKV6pp5_oaDm0oVw,223
+codex_bot/templates/feature/formatters.py.tpl,sha256=B-AeWaBs7hYYyfwaq5xuL9C_Fr3w9xokHBonZp25PQY,492
+codex_bot/templates/feature/handlers.py.tpl,sha256=ncCRGUG1pApgId7dvjMRKrTA3PRB3uPn-FLELS2TkEY,934
+codex_bot/templates/feature/handlers_redis.py.tpl,sha256=d8_iReh-K90kMjKsqxcEeITjo4dInbVJK1Rz_KDdPqo,797
+codex_bot/templates/feature/keyboards.py.tpl,sha256=kDLRQWN_rVLrqI4gdZgQQmyprts2Uhpc9kR0dRgu-Qo,430
+codex_bot/templates/feature/orchestrator.py.tpl,sha256=zmDDKXxGKzApv3d_IpqlH2-xHN0UPagwYHl1KORcqKo,911
+codex_bot/templates/feature/orchestrator_redis.py.tpl,sha256=uAWf1m8WFSGro7zjwC5SXv98csg0jilathDCE3EjXMs,499
+codex_bot/templates/feature/texts.py.tpl,sha256=QLskrg0esJD03DbAN3em7gCB5uHXxXyWnBaivcFUEp4,257
+codex_bot/templates/feature/ui.py.tpl,sha256=3XFtPCjNvkXwFa3X8ymgO6vWphL2MHSuWB9viKbwYac,562
+codex_bot/url_signer/__init__.py,sha256=8nQJHsnFNUIY9IRlYCNH4iOSWLRHJgcYcG7Vt5auvBs,156
+codex_bot/url_signer/service.py,sha256=OqLa1Y_P2SgEa38Gh0dw553vPL7iD86d0iDtnXnzMs4,3513
+codex_bot-0.1.0.dist-info/METADATA,sha256=2c8tDw2jE25SEP2YLR1_eWkyB1fZJPKDUQKYjIQhxik,4752
+codex_bot-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+codex_bot-0.1.0.dist-info/entry_points.txt,sha256=qcXUNOjDOmIDwKegdbSQmrB1SFioo7zILnKmQo0nYjk,49
+codex_bot-0.1.0.dist-info/licenses/LICENSE,sha256=hWy4ZuZrIx8qyauWVRZG22OeMnH21JHK053SG7DRQDs,1065
+codex_bot-0.1.0.dist-info/RECORD,,

codex_bot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_bot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-bot = codex_bot.cli:main

codex_bot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodexDLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.