peyk 1.0.0__tar.gz

peyk-1.0.0/CHANGES.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [1.0.0] — Initial public release
+
+- First public release of `peyk`: an aiogram-style, async, multi-platform bot
+  library supporting Telegram, Bale, and Rubika through one shared API.
+- Shared transport layer (tuned `aiohttp` session, `orjson`, retry/backoff).
+- Full Bale and Telegram client coverage, with a shared `TelegramLikeClient`
+  base extracted from both real implementations.
+- Rubika client covering its full (~19-method) API surface, including its
+  webhook secret-key verification and chat-keypad/inline-keypad button types.
+- Platform-agnostic dispatcher: `Router`/`Filter` composition, middleware,
+  and an FSM with in-memory and Redis storage backends.
+- Platform-aware text formatting and keyboard-building helpers.
+- Full test suite running offline against local fake servers — no real
+  network calls required to run the tests.

peyk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 peyk contributors
+
+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.

peyk-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include CHANGES.md
+include LICENSE
+recursive-include docs *.md *.rst *.css *.png
+recursive-include examples *.py
+recursive-include assets *.png
+recursive-include src/peyk py.typed

peyk-1.0.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: peyk
+Version: 1.0.0
+Summary: An aiogram-style async bot library for Telegram, Bale, and Rubika.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/amirhossein-ahmadi-ah/peyk
+Project-URL: Documentation, https://amirhossein-ahmadi-ah.github.io/peyk/
+Project-URL: Repository, https://github.com/amirhossein-ahmadi-ah/peyk
+Project-URL: Issues, https://github.com/amirhossein-ahmadi-ah/peyk/issues
+Project-URL: Changelog, https://github.com/amirhossein-ahmadi-ah/peyk/blob/main/CHANGES.md
+Keywords: telegram,bale,rubika,bot,asyncio,aiogram
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: orjson>=3.9
+Requires-Dist: magic-filter>=1.0
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=8; extra == "docs"
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: fakeredis>=2.20; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Provides-Extra: bale
+Provides-Extra: telegram
+Provides-Extra: rubika
+Provides-Extra: fsm-redis
+Requires-Dist: redis>=5.0; extra == "fsm-redis"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo-source.png" alt="peyk logo" width="160">
+</p>
+
+<h1 align="center">peyk</h1>
+
+<p align="center">An aiogram-style async bot library for Telegram, Bale, and Rubika.</p>
+
+## 10-line quickstart
+
+```python
+from peyk import Bot
+
+bot = Bot("TOKEN", platform="telegram")
+
+@bot.command("start")
+async def start(message):
+    await message.answer("Hello from peyk!")
+
+@bot.message()
+async def echo(message):
+    await message.answer(message.text or "")
+
+bot.run()
+```
+
+`platform=` is selected once when the bot is created; handlers, filters, keyboards, and normalized message objects stay platform-neutral.
+
+## Install
+
+```bash
+pip install peyk
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Documentation
+
+- [Capabilities](docs/capabilities.md) — audited feature support and UNKNOWN areas.
+- [Migration from aiogram](docs/migration_aiogram.rst) — import mapping, compatible surfaces, and Peyk-specific differences.
+- [Quickstart](docs/quickstart.rst) — simple `bot.run()` first, then Dispatcher/Router.
+- [Examples](examples/) — runnable examples using public imports.
+
+## Tests
+
+```bash
+pytest
+```
+
+The test suite is offline and uses local/fake servers and in-memory/fakeredis fixtures.
+
+## Project record
+
+See `docs/decisions.md` for the architectural decision record and capability evidence.
+
+## Publishing
+
+See [`PUBLISHING.md`](PUBLISHING.md) for the one-time GitHub/PyPI setup and
+the release checklist for every version after that.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

peyk-1.0.0/README.md

@@ -0,0 +1,67 @@
+<p align="center">
+  <img src="assets/logo-source.png" alt="peyk logo" width="160">
+</p>
+
+<h1 align="center">peyk</h1>
+
+<p align="center">An aiogram-style async bot library for Telegram, Bale, and Rubika.</p>
+
+## 10-line quickstart
+
+```python
+from peyk import Bot
+
+bot = Bot("TOKEN", platform="telegram")
+
+@bot.command("start")
+async def start(message):
+    await message.answer("Hello from peyk!")
+
+@bot.message()
+async def echo(message):
+    await message.answer(message.text or "")
+
+bot.run()
+```
+
+`platform=` is selected once when the bot is created; handlers, filters, keyboards, and normalized message objects stay platform-neutral.
+
+## Install
+
+```bash
+pip install peyk
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Documentation
+
+- [Capabilities](docs/capabilities.md) — audited feature support and UNKNOWN areas.
+- [Migration from aiogram](docs/migration_aiogram.rst) — import mapping, compatible surfaces, and Peyk-specific differences.
+- [Quickstart](docs/quickstart.rst) — simple `bot.run()` first, then Dispatcher/Router.
+- [Examples](examples/) — runnable examples using public imports.
+
+## Tests
+
+```bash
+pytest
+```
+
+The test suite is offline and uses local/fake servers and in-memory/fakeredis fixtures.
+
+## Project record
+
+See `docs/decisions.md` for the architectural decision record and capability evidence.
+
+## Publishing
+
+See [`PUBLISHING.md`](PUBLISHING.md) for the one-time GitHub/PyPI setup and
+the release checklist for every version after that.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

peyk-1.0.0/docs/_static/custom.css

@@ -0,0 +1,9 @@
+
+.sidebar-brand {
+  border-radius: 14px;
+  padding: 0.35rem;
+}
+
+.dark .sidebar-brand {
+  background: #141820;
+}

peyk-1.0.0/docs/api_reference.rst

@@ -0,0 +1,65 @@
+API reference
+=============
+
+Bot and application
+-------------------
+
+.. automodule:: peyk.bot.base
+   :members: Bot, BotDefaults
+
+Dispatcher and Router
+---------------------
+
+.. automodule:: peyk.dispatcher.dispatcher
+   :members: Dispatcher
+
+.. automodule:: peyk.dispatcher.router
+   :members: Router
+
+Types
+-----
+
+.. automodule:: peyk.types.core
+   :members:
+
+Filters
+-------
+
+.. automodule:: peyk.filters
+   :members:
+
+Keyboard
+--------
+
+.. automodule:: peyk.keyboard.builder
+   :members:
+
+Formatting
+----------
+
+.. automodule:: peyk.formatting
+   :members:
+
+Webhook
+--------
+
+.. automodule:: peyk.webhook
+   :members:
+
+FSM
+---
+
+.. automodule:: peyk.fsm
+   :members:
+
+Flags
+-----
+
+.. automodule:: peyk.flags
+   :members:
+
+Utilities
+---------
+
+.. automodule:: peyk.utils
+   :members:

peyk-1.0.0/docs/capabilities.md

@@ -0,0 +1,109 @@
+# Capability matrix
+
+Generated by `scripts/audit_capabilities.py` from the audited registry.
+
+| Feature | telegram | bale | rubika |
+|---|---|---|---|
+| `messaging.text` | ✅ | ✅ | ✅ |
+| `messaging.photo` | ✅ | ✅ | 🔁 requestSendFile -> upload -> sendFile is the confirmed three-step flow. |
+| `messaging.video` | ✅ | ✅ | 🔁 requestSendFile -> upload -> sendFile is the confirmed three-step flow. |
+| `messaging.audio` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.voice` | ✅ | ✅ | 🔁 requestSendFile -> upload -> sendFile is the confirmed three-step flow. |
+| `messaging.document` | ✅ | ✅ | 🔁 requestSendFile -> upload -> sendFile is the confirmed three-step flow. |
+| `messaging.animation` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.sticker` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.contact` | ✅ | ✅ | ✅ |
+| `messaging.location` | ✅ | ✅ | ✅ |
+| `messaging.venue` | ✅ | ❌ No send_venue method is present in the audited Bale client. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.poll` | ✅ | ❌ No send_poll method or poll model is present in the audited Bale client/model set. | ✅ |
+| `messaging.dice` | ✅ | ❌ No send_dice method or dice model is present in the audited Bale client/model set. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.media_group` | ✅ | ✅ | ❌ No Rubika send-media-group operation is present in the audited official-contract client. |
+| `messaging.copy` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.forward` | ✅ | ✅ | ✅ |
+| `messaging.edit_text` | ✅ | ✅ | ✅ |
+| `messaging.edit_caption` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.edit_media` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.edit_markup` | ✅ | ✅ | ✅ |
+| `messaging.delete` | ✅ | ✅ | ✅ |
+| `messaging.bulk_delete` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.reply_to` | ✅ | ✅ | ✅ |
+| `messaging.chat_actions` | ✅ | ✅ | ❌ No Rubika chat-action method is present in the audited official-contract client. |
+| `messaging.reactions` | ✅ | ❓ No confirmed Bale reaction contract in the audited project. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.link_preview_control` | ✅ | ❓ Bale parse/formatting and link-preview behavior is not confirmed. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.protect_content` | ✅ | ❓ Not established by the audited Bale method signatures. | ❓ Not independently established by the Phase 1 audit. |
+| `messaging.entities_formatting` | ✅ Entity and parse-mode parameters are present on the audited client. | 🟡 D5 confirms Bale native formatting syntax; no Telegram-style parse_mode is advertised. | 🟡 D5 confirms structured metadata formatting rather than a Telegram parse mode; formatted edit metadata is NONE/inferred because editMessageText has no metadata parameter. |
+| `keyboards.inline` | ✅ | ✅ | ✅ |
+| `keyboards.reply` | ✅ | ✅ | ✅ |
+| `keyboards.remove_reply` | ✅ | ✅ | ✅ |
+| `keyboards.force_reply` | ✅ | ❓ No audited Bale ForceReply model. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.url` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.callback` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.web_app` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.copy_text` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.color_style` | ✅ The audited type confirms a style field; the primary/success/danger wire values are inferred from the task specification and are not independently documented in the repository. | ❌ No `style` field exists on the audited Bale InlineKeyboardButton. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.icon_emoji` | ✅ | ❌ No `icon_custom_emoji_id` field exists on the audited Bale InlineKeyboardButton. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.request_contact` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.request_location` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.request_poll` | ✅ | ❌ No matching field exists on the audited Bale keyboard button model. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.request_users` | ✅ | ❌ No matching field exists on the audited Bale keyboard button model. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.request_chat` | ✅ | ❌ No matching field exists on the audited Bale keyboard button model. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.pay` | ✅ | ❌ No `pay` field exists on the audited Bale InlineKeyboardButton. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.switch_inline` | ✅ | ❌ No `switch_inline_query` field exists on the audited Bale InlineKeyboardButton. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.button.login_url` | ✅ | ❌ No `login_url` field exists on the audited Bale InlineKeyboardButton. | ❓ Not independently established by the Phase 1 audit. |
+| `keyboards.rubika.selection` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `keyboards.rubika.calendar` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `keyboards.rubika.number_picker` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `keyboards.rubika.string_picker` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `keyboards.rubika.location` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `keyboards.rubika.camera_image` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.camera_video` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.gallery_image` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.gallery_video` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.file` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.audio` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.record_audio` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.textbox` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `keyboards.rubika.link` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.ask_my_phone_number` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.ask_my_location` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `keyboards.rubika.barcode` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ Button kind is represented by the audited Rubika enum/model set. |
+| `callbacks.answer` | ✅ | ✅ | ❌ Rubika callback events have no callback-query identifier in the audited model, so automatic callback acknowledgement is not available. |
+| `callbacks.alert_toast` | ✅ The audited method exposes show_alert; toast is the default callback answer path. | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `callbacks.data_byte_limit` | ✅ | ✅ | ❓ button_id is confirmed but no callback-data byte limit is established. |
+| `updates.polling` | ✅ | ✅ | ✅ |
+| `updates.webhook` | ✅ | ✅ | 🟡 Endpoint method is implemented; updateBotEndpoints parameter semantics remain UNKNOWN per R6. |
+| `updates.webhook_secret_header` | ✅ Telegram enforces secret_token through the X-Telegram-Bot-Api-Secret-Token request header. | ❌ Bale documents no webhook request secret/header mechanism in the audited contract. | ❌ Rubika webhook_security.py states that the documented webhook contract has no request signing or shared-secret header. |
+| `updates.offset_kind` | ✅ | ✅ | ✅ |
+| `updates.allowed_updates` | ✅ | ✅ | ❓ Endpoint/update parameters remain a documented UNKNOWN area. |
+| `updates.long_poll_timeout` | ✅ | ✅ | ❓ The audited method exposes no timeout parameter. |
+| `chat_admin.ban` | ✅ | ✅ | ✅ |
+| `chat_admin.unban` | ✅ | ✅ | ✅ |
+| `chat_admin.restrict` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.promote` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.pin` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.unpin` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.invite_links` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.member_count` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.administrators` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.permissions` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.title` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.description` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.photo` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.leave` | ✅ | ✅ | ✅ |
+| `chat_admin.join_requests` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.forum_topics` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `chat_admin.member_status_updates` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `files.get_file` | ✅ | ✅ | ✅ |
+| `files.upload_bytes` | ✅ | ✅ | ✅ |
+| `files.multi_step_upload` | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `payments` | ✅ | ✅ | ❓ Not independently established by the Phase 1 audit. |
+| `bot_profile.commands` | ✅ | ❓ Not independently established by the Phase 1 audit. | ✅ |
+| `bot_profile.name` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `bot_profile.description` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `inline_mode` | ✅ | ❓ Not independently established by the Phase 1 audit. | ❓ Not independently established by the Phase 1 audit. |
+| `telegram.games` | ✅ | ❌ This feature is classified as Telegram-only by the Phase 1 specification. | ❌ This feature is classified as Telegram-only by the Phase 1 specification. |
+| `telegram.passport` | ✅ | ❌ This feature is classified as Telegram-only by the Phase 1 specification. | ❌ This feature is classified as Telegram-only by the Phase 1 specification. |
+| `telegram.business` | ✅ | ❌ This feature is classified as Telegram-only by the Phase 1 specification. | ❌ This feature is classified as Telegram-only by the Phase 1 specification. |
+| `telegram.stories` | ✅ | ❌ This feature is classified as Telegram-only by the Phase 1 specification. | ❌ This feature is classified as Telegram-only by the Phase 1 specification. |
+| `telegram.gifts` | ✅ | ❌ This feature is classified as Telegram-only by the Phase 1 specification. | ❌ This feature is classified as Telegram-only by the Phase 1 specification. |
+| `telegram.stars` | ✅ | ❌ This feature is classified as Telegram-only by the Phase 1 specification. | ❌ This feature is classified as Telegram-only by the Phase 1 specification. |

peyk-1.0.0/docs/capabilities.rst

@@ -0,0 +1,22 @@
+Platform capabilities
+=====================
+
+The generated capability table is maintained in ``docs/capabilities.md``.
+The Markdown file is the canonical generated artifact; the table below is the
+same audited information for the Sphinx site.
+
+.. csv-table:: Audited capability summary
+   :header: "Area", "Telegram", "Bale", "Rubika"
+   :widths: 30, 20, 20, 30
+
+   "messaging.text", "full", "full", "full"
+   "messaging.media_group", "full", "full", "none"
+   "messaging.chat_actions", "full", "full", "none"
+   "callbacks.answer", "full", "full", "none"
+   "updates.polling", "full", "full", "full"
+   "updates.webhook", "full", "full", "partial / parameter semantics UNKNOWN"
+   "files.multi_step_upload", "unknown", "unknown", "full"
+   "keyboards.inline", "full", "full", "full"
+   "keyboards.reply", "full", "full", "full"
+
+See ``capabilities.md`` for the complete generated matrix and evidence notes.

peyk-1.0.0/docs/capabilities_todo.md

@@ -0,0 +1,112 @@
+# Capability audit TODO
+
+UNKNOWN or low-confidence items from the audited registry. Each item has a concrete live-token probe suggestion.
+
+- **telegram / `keyboards.rubika.selection`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.calendar`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.number_picker`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.string_picker`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.location`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.camera_image`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.camera_video`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.gallery_image`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.gallery_video`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.file`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.audio`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.record_audio`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.textbox`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.link`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.ask_my_phone_number`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.ask_my_location`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `keyboards.rubika.barcode`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **telegram / `files.multi_step_upload`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `messaging.sticker`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `messaging.edit_media`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `messaging.bulk_delete`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `messaging.reactions`** — No confirmed Bale reaction contract in the audited project. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `messaging.link_preview_control`** — Bale parse/formatting and link-preview behavior is not confirmed. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `messaging.protect_content`** — Not established by the audited Bale method signatures. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.force_reply`** — No audited Bale ForceReply model. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.selection`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.calendar`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.number_picker`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.string_picker`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.location`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.camera_image`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.camera_video`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.gallery_image`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.gallery_video`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.file`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.audio`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.record_audio`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.textbox`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.link`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.ask_my_phone_number`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.ask_my_location`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `keyboards.rubika.barcode`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `chat_admin.restrict`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `chat_admin.permissions`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `chat_admin.join_requests`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `chat_admin.forum_topics`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `chat_admin.member_status_updates`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `files.multi_step_upload`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `bot_profile.commands`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `bot_profile.name`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `bot_profile.description`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **bale / `inline_mode`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.audio`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.animation`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.sticker`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.venue`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.dice`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.copy`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.edit_caption`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.edit_media`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.bulk_delete`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.reactions`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.link_preview_control`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `messaging.protect_content`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.force_reply`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.url`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.callback`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.web_app`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.copy_text`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.color_style`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.icon_emoji`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.request_contact`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.request_location`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.request_poll`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.request_users`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.request_chat`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.pay`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.switch_inline`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `keyboards.button.login_url`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `callbacks.alert_toast`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `callbacks.data_byte_limit`** — button_id is confirmed but no callback-data byte limit is established. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `updates.webhook`** — Endpoint method is implemented; updateBotEndpoints parameter semantics remain UNKNOWN per R6. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `updates.allowed_updates`** — Endpoint/update parameters remain a documented UNKNOWN area. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `updates.long_poll_timeout`** — The audited method exposes no timeout parameter. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.restrict`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.promote`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.pin`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.unpin`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.invite_links`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.member_count`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.administrators`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.permissions`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.title`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.description`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.photo`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.join_requests`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.forum_topics`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `chat_admin.member_status_updates`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `payments`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `bot_profile.name`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `bot_profile.description`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+- **rubika / `inline_mode`** — Not independently established by the Phase 1 audit. Probe: issue the smallest platform API request that directly exercises this feature with a live bot token and record the response schema/error.
+
+## Phase 9 webhook live probes
+
+- Rubika `GetSelectionItem` and `SearchSelectionItems` endpoint types are not registered by Peyk. Live-probe their request/response bodies before adding support.
+- Rubika webhook payloads are parsed only from repository-confirmed `Update` and `InlineMessage` models. A live probe should record any additional webhook event shapes before expanding the parser.
+- Telegram self-signed certificate upload is intentionally not exposed because the audited `set_webhook` client signature has no `certificate` parameter.