screwinboxads 1.0.0__tar.gz

screwinboxads-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+.claude/settings.local.json
+
+# Backend
+backend/screwinboxads
+backend/screwinboxads.exe
+backend/coverage.out
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+frontend/coverage/
+
+# E2E
+e2e/node_modules/
+e2e/test-results/
+e2e/playwright-report/
+
+# Env (deploy/.env.local и .env.example коммитятся — безопасные значения для локали)
+deploy/.env
+deploy/.env.deploy
+deploy/.env.production
+
+# Локальный каталог копий WAL-G (WAL_ARCHIVE_DIR в deploy/.env.local)
+deploy/.data/
+
+# Go tool cache pinned via go.mod tool directives; build artifacts only
+*.test
+!deploy/.env.test
+*.out
+
+# TypeScript incremental build cache
+*.tsbuildinfo
+
+# Python bytecode cache
+__pycache__/
+*.pyc
+
+# sdk/conformance
+sdk/conformance/report.json
+
+# sdk/python: артефакты `make sdk-release` (wheel, sdist)
+sdk/python/dist/
+.ruff_cache/
+*.egg-info/
+
+# reference-bot: токены и ключи экземпляров (.env.example коммитится)
+reference-bot/.env.bot-*
+reference-bot/.env.test-*

screwinboxads-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Screw Inbox Ads Platform
+
+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.

screwinboxads-1.0.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: screwinboxads
+Version: 1.0.0
+Summary: Реклама Screw Inbox Ads в Telegram-боте на aiogram 3: вопрос с кнопками, оффер и подтверждение показов
+Author: Screw Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ads,advertising,aiogram,bot,monetization,sdk,telegram
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Russian
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# screwinboxads
+
+Реклама Screw Inbox Ads в Telegram-боте на aiogram 3.
+
+## Подключение
+
+**1. Установите пакет** (нужен aiogram 3.13 или новее)
+
+```bash
+pip install "screwinboxads<2"
+```
+
+**2. В начало файла, где создаётся `Dispatcher`, добавьте импорт**
+
+```python
+from screwinboxads import ScrewInboxAds
+```
+
+**3. Добавьте сразу после `dp = Dispatcher()`**
+
+```python
+ScrewInboxAds(dp, api_key="ключ-бота")   # ключ выдаёт команда Screw Inbox Ads
+```
+
+**4. Покажите рекламу в нужном обработчике — в любом файле бота**
+
+```python
+from screwinboxads import show_ad
+
+await show_ad(message)   # message — входящее сообщение или нажатие кнопки
+```
+
+Готово. Вопрос, оффер и учёт показов SDK делает сам. Нет рекламы или ошибка — бот работает
+дальше как обычно.

screwinboxads-1.0.0/README.md

@@ -0,0 +1,34 @@
+# screwinboxads
+
+Реклама Screw Inbox Ads в Telegram-боте на aiogram 3.
+
+## Подключение
+
+**1. Установите пакет** (нужен aiogram 3.13 или новее)
+
+```bash
+pip install "screwinboxads<2"
+```
+
+**2. В начало файла, где создаётся `Dispatcher`, добавьте импорт**
+
+```python
+from screwinboxads import ScrewInboxAds
+```
+
+**3. Добавьте сразу после `dp = Dispatcher()`**
+
+```python
+ScrewInboxAds(dp, api_key="ключ-бота")   # ключ выдаёт команда Screw Inbox Ads
+```
+
+**4. Покажите рекламу в нужном обработчике — в любом файле бота**
+
+```python
+from screwinboxads import show_ad
+
+await show_ad(message)   # message — входящее сообщение или нажатие кнопки
+```
+
+Готово. Вопрос, оффер и учёт показов SDK делает сам. Нет рекламы или ошибка — бот работает
+дальше как обычно.

screwinboxads-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "screwinboxads"
+version = "1.0.0"
+description = "Реклама Screw Inbox Ads в Telegram-боте на aiogram 3: вопрос с кнопками, оффер и подтверждение показов"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Screw Team" }]
+keywords = ["telegram", "aiogram", "bot", "ads", "advertising", "monetization", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Natural Language :: Russian",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+# Зависимости разработки SDK — группа (PEP 735), а не extra: в метаданные пакета не попадает.
+[dependency-groups]
+dev = ["pytest", "pytest-timeout", "pytest-asyncio", "hypothesis", "ruff", "mypy", "build", "aiogram>=3.13,<4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/screwinboxads"]
+
+# В архив исходников — только то, что нужно для сборки пакета; тесты и кэши остаются в репозитории.
+[tool.hatch.build.targets.sdist]
+include = ["src/screwinboxads", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+timeout = 120
+markers = [
+    "suite: запускает проверочный набор целиком (медленно)",
+    "slow: нагрузка в реальном времени (десятки секунд); мутационные тесты её не запускают",
+]

screwinboxads-1.0.0/src/screwinboxads/__init__.py

@@ -0,0 +1,40 @@
+"""SDK Screw Inbox Ads: ScrewInboxAds — подключение к aiogram 3 одной строкой
+(`from screwinboxads import ScrewInboxAds`), show_ad — показ рекламы из любого модуля бота,
+ScrewInboxAdsClient — ядро сценария, независимое от фреймворка. `import screwinboxads` работает и
+без aiogram: адаптер загружается при первом обращении к `ScrewInboxAds` или `show_ad`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .flow import AdFinished, AdOutcome, ScrewInboxAdsClient, ShowResult
+
+if TYPE_CHECKING:
+    from ._aiogram3 import ScrewInboxAds, show_ad
+
+__all__ = [
+    "AdFinished",
+    "AdOutcome",
+    "ScrewInboxAds",
+    "ScrewInboxAdsClient",
+    "ShowResult",
+    "show_ad",
+]
+
+_ADAPTER_NAMES = frozenset({"ScrewInboxAds", "show_ad"})
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _ADAPTER_NAMES:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        from . import _aiogram3
+    except ImportError as exc:
+        # Только отсутствие самого aiogram получает понятное сообщение; прочие ошибки импорта
+        # (например, сломанная зависимость aiogram) не подменяются — иначе причина спрячется.
+        if exc.name == "aiogram" or (exc.name or "").startswith("aiogram."):
+            raise ImportError(
+                "SDK Screw Inbox Ads работает с aiogram: установите aiogram (pip install aiogram)"
+            ) from exc
+        raise
+    return getattr(_aiogram3, name)

screwinboxads-1.0.0/src/screwinboxads/_aiogram3.py

@@ -0,0 +1,381 @@
+"""Адаптер aiogram 3: `ScrewInboxAds` — `Messenger` на aiogram `Bot` и подключение к диспетчеру
+для нажатий `sa:` (design.md «Пакет», решения 1–3); `show_ad` — показ из любого модуля бота без
+ссылки на экземпляр (change sdk-show-ad-anywhere). Публичные точки входа — `from screwinboxads
+import ScrewInboxAds, show_ad`. Единственное место SDK, которому разрешено зависеть от aiogram
+(openspec/config.yaml)."""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import logging
+import weakref
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from aiogram import Bot, Dispatcher
+from aiogram.exceptions import TelegramAPIError, TelegramNetworkError
+from aiogram.types import (
+    CallbackQuery,
+    InlineKeyboardButton,
+    InlineKeyboardMarkup,
+    Message,
+    TelegramObject,
+)
+
+from .adapter import Messenger, SendResult
+from .flow import DEFAULT_API_URL, AdFinished, ScrewInboxAdsClient, ShowResult
+
+__all__ = ["ScrewInboxAds", "show_ad"]
+
+logger = logging.getLogger("screwinboxads")
+
+# Лимит Telegram: кнопок в одном блоке `buttons` rich message. Часть контракта Bot API,
+# не настройка.
+_RICH_BUTTONS_PER_BLOCK = 8
+
+# Ядро хранит `on_ad_finished` как один колбэк на весь клиент (design.md, решение 1), а Bot
+# известен только для текущего callback-запроса; contextvar передаёт его без гонок между
+# конкурентными запросами (обычный mutable-атрибут на инстансе делил бы значение между ними).
+_current_bot: contextvars.ContextVar[Bot | None] = contextvars.ContextVar(
+    "screwinboxads_current_bot", default=None
+)
+
+# Экземпляр, подключённый к диспетчеру, который сейчас обрабатывает обновление: его ставит внешний
+# middleware `dp.update`, поэтому `show_ad()` из обработчика берёт ключ своего диспетчера, даже если
+# в процессе несколько ботов. Задачи, запущенные из обработчика, наследуют значение.
+_current_ads: contextvars.ContextVar[ScrewInboxAds | None] = contextvars.ContextVar(
+    "screwinboxads_current_ads", default=None
+)
+# Живые экземпляры — для `show_ad()` вне обработки обновления (фоновая задача, рассылка).
+_instances: weakref.WeakSet[ScrewInboxAds] = weakref.WeakSet()
+
+
+def _wrap_on_ad_finished(
+    handler: Callable[[Bot, AdFinished], Awaitable[None]] | None,
+) -> Callable[[AdFinished], Awaitable[None]] | None:
+    if handler is None:
+        return None
+
+    async def _handle_finished(event: AdFinished) -> None:
+        bot = _current_bot.get()
+        if bot is None:
+            return
+        await handler(bot, event)
+
+    return _handle_finished
+
+
+class _AiogramMessenger:
+    """`Messenger` (adapter.py) поверх aiogram `Bot`: текст одним сообщением без `parse_mode`;
+    вопрос — inline-кнопки по порядку; оффер — одна URL-кнопка, URL не меняется."""
+
+    def __init__(self, bot: Bot) -> None:
+        self._bot = bot
+
+    async def send_question(
+        self, *, chat_id: int, text: str, buttons: tuple[tuple[str, str], ...]
+    ) -> SendResult:
+        markup = InlineKeyboardMarkup(
+            inline_keyboard=[
+                [InlineKeyboardButton(text=label, callback_data=data) for label, data in buttons]
+            ]
+        )
+        return await self._call(
+            self._bot.send_message(chat_id, text, parse_mode=None, reply_markup=markup)
+        )
+
+    async def send_offer(
+        self, *, chat_id: int, text: str, cta_text: str, cta_url: str
+    ) -> SendResult:
+        markup = InlineKeyboardMarkup(
+            inline_keyboard=[[InlineKeyboardButton(text=cta_text, url=cta_url)]]
+        )
+        return await self._call(
+            self._bot.send_message(chat_id, text, parse_mode=None, reply_markup=markup)
+        )
+
+    async def _call(self, call: Awaitable[Any]) -> SendResult:
+        """Выполняет вызов Bot API и переводит исход в `SendResult`."""
+        try:
+            await call
+            return SendResult.SENT
+        except (TelegramNetworkError, asyncio.TimeoutError) as exc:
+            logger.warning("Telegram: результат отправки неизвестен: %s", exc)
+            return SendResult.UNKNOWN
+        except TelegramAPIError as exc:
+            # Текст ошибки Telegram объясняет отказ (например, недопустимый URL кнопки оффера);
+            # токена бота в нём нет — aiogram выводит только ответ сервера.
+            logger.warning("Telegram отверг сообщение: %s", exc)
+            return SendResult.FAILED
+
+    async def answer_callback(self, *, callback_query_id: str) -> None:
+        try:
+            await self._bot.answer_callback_query(callback_query_id)
+        except TelegramAPIError:
+            pass
+
+
+class _AiogramRichMessenger(_AiogramMessenger):
+    """`Messenger` с методами `RichMessenger` (adapter.py): интерактивный креатив одним rich
+    message (Bot API 10.3, aiogram 3.31+). Типы rich message импортируются внутри методов: в
+    более старом aiogram их нет, и этот класс там не используется (`_messenger_for`)."""
+
+    async def send_rich_question(
+        self, *, chat_id: int, text: str, buttons: tuple[tuple[str, str], ...]
+    ) -> SendResult:
+        from aiogram.types import (
+            InputRichBlockButtons,
+            InputRichBlockParagraph,
+            InputRichMessage,
+            RichMessageButton,
+        )
+
+        blocks: list[Any] = [InputRichBlockParagraph(text=text)]
+        for start in range(0, len(buttons), _RICH_BUTTONS_PER_BLOCK):
+            chunk = buttons[start : start + _RICH_BUTTONS_PER_BLOCK]
+            blocks.append(
+                InputRichBlockButtons(
+                    buttons=[
+                        RichMessageButton(text=label, callback_data=data) for label, data in chunk
+                    ],
+                )
+            )
+        return await self._call(
+            self._bot.send_rich_message(chat_id, rich_message=InputRichMessage(blocks=blocks))
+        )
+
+    async def edit_rich_message(
+        self,
+        *,
+        chat_id: int,
+        message_id: int,
+        text: str,
+        cta_text: str | None = None,
+        cta_url: str | None = None,
+    ) -> SendResult:
+        from aiogram.types import (
+            InputRichBlockButtons,
+            InputRichBlockParagraph,
+            InputRichMessage,
+            RichMessageButton,
+        )
+
+        blocks: list[Any] = [InputRichBlockParagraph(text=text)]
+        if cta_text is not None and cta_url is not None:
+            blocks.append(
+                InputRichBlockButtons(
+                    buttons=[RichMessageButton(text=cta_text, url=cta_url, style="primary")],
+                )
+            )
+        # Умолчания бота (`parse_mode`, предпросмотр ссылок) к rich message не относятся.
+        return await self._call(
+            self._bot.edit_message_text(
+                chat_id=chat_id,
+                message_id=message_id,
+                rich_message=InputRichMessage(blocks=blocks),
+                parse_mode=None,
+                link_preview_options=None,
+                disable_web_page_preview=None,
+            )
+        )
+
+
+def _messenger_for(bot: Bot) -> Messenger:
+    """Адаптер для бота: с rich-методами, если установленный aiogram их поддерживает
+    (`send_rich_message` у `Bot`, 3.31+), иначе — только два сообщения (FR-22). Проверка при
+    каждом создании, а не при импорте: возможность определяется самим объектом `Bot`."""
+    if hasattr(bot, "send_rich_message"):
+        return _AiogramRichMessenger(bot)
+    return _AiogramMessenger(bot)
+
+
+class ScrewInboxAds:
+    """SDK Screw Inbox Ads для aiogram 3::
+
+        ads = ScrewInboxAds(dp, api_key="…")
+        ...
+        await ads.show_ad(message)
+
+    Конструктор сам подключается к `dp`: внешний middleware диспетчера забирает нажатия с
+    `callback_data`, начинающимся с `sa:`, раньше любого обработчика бота (SP-24) — порядок
+    регистрации обработчиков значения не имеет. Остальные нажатия идут к обработчикам бота как
+    обычно (SP-08). Состояние SDK хранится в памяти процесса, файлов у бота нет."""
+
+    def __init__(
+        self,
+        dp: Dispatcher,
+        api_key: str,
+        *,
+        api_url: str = DEFAULT_API_URL,
+        timeout: float = 3.0,
+        ad_request_timeout: float = 1.0,
+        confirm_retry_window: float = 3600.0,
+        max_pending_confirms: int = 10_000,
+        on_ad_finished: Callable[[Bot, AdFinished], Awaitable[None]] | None = None,
+        offer_display_delay: float = 2.0,
+        storage_retention_days: int = 7,
+        storage_purge_interval: float = 24 * 60 * 60,
+        http_workers: int = 16,
+        max_pending_shows: int = 16,
+        breaker_failures: int = 5,
+        breaker_cooldown: float = 10.0,
+    ) -> None:
+        self._client = ScrewInboxAdsClient(
+            api_key=api_key,
+            api_url=api_url,
+            timeout=timeout,
+            ad_request_timeout=ad_request_timeout,
+            confirm_retry_window=confirm_retry_window,
+            max_pending_confirms=max_pending_confirms,
+            on_ad_finished=_wrap_on_ad_finished(on_ad_finished),
+            offer_display_delay=offer_display_delay,
+            storage_retention_days=storage_retention_days,
+            storage_purge_interval=storage_purge_interval,
+            http_workers=http_workers,
+            max_pending_shows=max_pending_shows,
+            breaker_failures=breaker_failures,
+            breaker_cooldown=breaker_cooldown,
+        )
+        dp.update.outer_middleware(self._update_middleware)
+        dp.callback_query.outer_middleware(self._middleware)
+        _instances.add(self)
+
+    async def _update_middleware(
+        self,
+        handler: Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]],
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:
+        token = _current_ads.set(self)
+        try:
+            return await handler(event, data)
+        finally:
+            _current_ads.reset(token)
+
+    async def _middleware(
+        self,
+        handler: Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]],
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:
+        if isinstance(event, CallbackQuery) and (event.data or "").startswith("sa:"):
+            await self._handle_callback(event)
+            return None
+        return await handler(event, data)
+
+    async def _handle_callback(self, callback_query: CallbackQuery) -> None:
+        bot = callback_query.bot
+        message = callback_query.message
+        if bot is None or message is None:
+            missing = "бота" if bot is None else "сообщения с кнопкой"
+            logger.warning("нажатие sa: не обработано: нет %s", missing)
+            return
+        messenger = _messenger_for(bot)
+        token = _current_bot.set(bot)
+        try:
+            await self._client.handle_callback(
+                messenger,
+                callback_data=callback_query.data or "",
+                callback_query_id=callback_query.id,
+                chat_id=message.chat.id,
+                user_id=str(callback_query.from_user.id),
+                # есть и у `InaccessibleMessage` (старое сообщение) — изменить его можно
+                message_id=message.message_id,
+            )
+        finally:
+            _current_bot.reset(token)
+
+    async def show_ad(
+        self,
+        event: Message | CallbackQuery | None = None,
+        *,
+        bot: Bot | None = None,
+        chat_id: int | None = None,
+        user_id: int | None = None,
+    ) -> ShowResult:
+        """Показывает рекламу пользователю события: бот, чат и пользователь берутся из
+        `Message` или `CallbackQuery` (у нажатия — пользователь нажавшего и чат сообщения под
+        кнопкой). Явные `bot`, `chat_id`, `user_id` — для показа без события; переданные вместе с
+        событием не используются, событие главнее. Возвращает управление сразу, показ идёт в
+        фоне: `QUEUED` — принят, `SKIPPED` — пропущен (предел показов или пауза предохранителя).
+        Не хватает данных или неизвестный тип события — `FAILED` и запись в журнал, исключение
+        в код бота не выходит (SP-21, SP-02, SP-31)."""
+        try:
+            target = _resolve_target(event, bot, chat_id, user_id)
+        except Exception:
+            logger.warning("show_ad: не удалось разобрать событие", exc_info=True)
+            return ShowResult.FAILED
+        if target is None:
+            return ShowResult.FAILED
+        target_bot, target_chat_id, target_user_id = target
+        return await self._client.show_ad(
+            _messenger_for(target_bot), chat_id=target_chat_id, user_id=str(target_user_id)
+        )
+
+    async def wait_shows(self) -> None:
+        """Дожидается начатых фоновых показов: при остановке бота и в тестах."""
+        await self._client.wait_shows()
+
+    async def close_ad(self, user_id: int, reason: str) -> None:
+        await self._client.close_ad(str(user_id), reason)
+
+
+async def show_ad(
+    event: Message | CallbackQuery | None = None,
+    *,
+    bot: Bot | None = None,
+    chat_id: int | None = None,
+    user_id: int | None = None,
+) -> ShowResult:
+    """`ScrewInboxAds.show_ad` без ссылки на экземпляр — для обработчиков в любом модуле бота.
+    Внутри обработки обновления — экземпляр диспетчера этого обновления; вне её — единственный
+    созданный экземпляр. SDK не подключён или экземпляров несколько вне обработки — `FAILED` и
+    запись `ERROR` в журнал: угадывать ключ нельзя, показ ушёл бы не тому боту."""
+    ads = _current_ads.get()
+    if ads is None:
+        alive = list(_instances)
+        if len(alive) != 1:
+            if alive:
+                logger.error(
+                    "show_ad: подключено %d экземпляров ScrewInboxAds, а вызов не из обработчика "
+                    "обновления — вызовите show_ad у нужного экземпляра",
+                    len(alive),
+                )
+            else:
+                logger.error(
+                    "show_ad: SDK не подключён — создайте ScrewInboxAds(dp, api_key=...) "
+                    "сразу после создания Dispatcher"
+                )
+            return ShowResult.FAILED
+        ads = alive[0]
+    return await ads.show_ad(event, bot=bot, chat_id=chat_id, user_id=user_id)
+
+
+def _resolve_target(
+    event: Message | CallbackQuery | None,
+    bot: Bot | None,
+    chat_id: int | None,
+    user_id: int | None,
+) -> tuple[Bot, int, int] | None:
+    """Бот, чат и пользователь показа; `None` (с записью в журнал) — если чего-то не хватает."""
+    if isinstance(event, Message):
+        bot = event.bot
+        chat_id = event.chat.id
+        user_id = event.from_user.id if event.from_user is not None else None
+    elif isinstance(event, CallbackQuery):
+        bot = event.bot
+        chat_id = event.message.chat.id if event.message is not None else None
+        user_id = event.from_user.id
+    elif event is not None:
+        logger.warning("show_ad: неподдерживаемый тип события %s", type(event).__name__)
+        return None
+    missing = [
+        name
+        for name, value in (("bot", bot), ("chat_id", chat_id), ("user_id", user_id))
+        if value is None
+    ]
+    if bot is None or chat_id is None or user_id is None:
+        logger.warning("show_ad: не хватает данных для показа: %s", ", ".join(missing))
+        return None
+    return bot, chat_id, user_id