nativeads 0.1.0__tar.gz

nativeads-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv*/
+__pycache__/
+*.egg-info/
+*.pyc
+dist/
+build/

nativeads-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: nativeads
+Version: 0.1.0
+Summary: NativeAds SDK for Telegram bots — inject ads into LLM replies (aiogram / python-telegram-bot / raw).
+Project-URL: Homepage, https://nativeads.cloud
+License-Expression: MIT
+Keywords: ads,aiogram,bot,monetization,python-telegram-bot,telegram
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: aiogram
+Requires-Dist: aiogram>=3.0; extra == 'aiogram'
+Provides-Extra: ptb
+Requires-Dist: python-telegram-bot>=20.0; extra == 'ptb'
+Description-Content-Type: text/markdown
+
+# nativeads (Python)
+
+Python SDK for [NativeAds](https://nativeads.cloud) — monetize your Telegram bot by
+injecting ads into LLM replies. Works with **aiogram 3.x**, **python-telegram-bot v20+**,
+or raw bot code.
+
+```bash
+pip install nativeads              # core (httpx only)
+pip install nativeads[aiogram]     # + aiogram 3.x
+pip install nativeads[ptb]         # + python-telegram-bot v20+
+```
+
+## Quick start (`inject`)
+
+```python
+from nativeads import NativeAds
+
+ads = NativeAds(api_key="sk_live_xxx", platform_id="plt_xxx")
+
+# inside an async message handler, after generating the LLM answer:
+result = await ads.inject(
+    user_id=message.from_user.id,
+    message=llm_answer,
+    language_code=message.from_user.language_code,
+    is_premium=message.from_user.is_premium,
+    keyboard=my_keyboard,        # optional — aiogram / PTB / raw dict
+    # ad_button_position="top",  # default "bottom"
+)
+await message.answer(result.message, reply_markup=result.keyboard)
+```
+
+### aiogram middleware (DI)
+```python
+from nativeads import NativeAds
+from nativeads.middleware import NativeAdsMiddleware
+
+mw = NativeAdsMiddleware(api_key="sk_live_xxx", platform_id="plt_xxx")
+dp.message.middleware(mw)
+dp.shutdown.register(mw.aclose)
+
+async def handler(message: Message, nativeads: NativeAds):
+    result = await nativeads.inject(user_id=message.from_user.id, message=answer)
+    await message.answer(result.message, reply_markup=result.keyboard)
+```
+
+## Privacy-friendly mode (`fetch`)
+```python
+res = await ads.fetch(user_id=uid, language_code="ru")
+if res.has_ad:
+    text = f"{llm_answer}\n\n{res.ad.ad_text}"
+    # render res.ad.button_text / res.ad.button_url yourself
+```
+
+## Guarantees
+- **Never raises.** On any error (timeout, network, 5xx) `inject()`/`fetch()` return your
+  original message and keyboard unchanged. Default timeout 3s.
+- **Your buttons are preserved** — the ad button is a separate row (top/bottom), respecting
+  Telegram's 4096-char and 13-row limits.
+- **Click tracking is automatic** — `button_url` is a tracking redirect.
+
+## API
+- `NativeAds(api_key, platform_id=None, *, base_url=..., timeout=3.0, platform="telegram", show_every=1, skip_first=0)`
+  - `show_every` — ad on every Nth message (5 = optimal, 0 = off); N>1 keeps the first message ad-free.
+  - `skip_first` — never show an ad on a user's first N messages.
+  - Frequency is client-side (in-memory per-user counter); skipped turns return your message without a server call.
+  - `NativeAdsMiddleware(...)` accepts the same `show_every` / `skip_first`.
+- `await ads.inject(*, user_id, message, language_code=None, is_premium=None, keyboard=None, ad_button_position="bottom", parse_mode=None) -> InjectResult`
+- `await ads.fetch(*, user_id, language_code=None, is_premium=None, parse_mode=None) -> FetchResult`
+- `await ads.aclose()`
+
+`InjectResult(message, has_ad, impression_id, ad, keyboard)` ·
+`FetchResult(has_ad, impression_id, ad)` ·
+`Ad(ad_text, button_text, button_url, ad_text_formatted)`

nativeads-0.1.0/README.md

@@ -0,0 +1,73 @@
+# nativeads (Python)
+
+Python SDK for [NativeAds](https://nativeads.cloud) — monetize your Telegram bot by
+injecting ads into LLM replies. Works with **aiogram 3.x**, **python-telegram-bot v20+**,
+or raw bot code.
+
+```bash
+pip install nativeads              # core (httpx only)
+pip install nativeads[aiogram]     # + aiogram 3.x
+pip install nativeads[ptb]         # + python-telegram-bot v20+
+```
+
+## Quick start (`inject`)
+
+```python
+from nativeads import NativeAds
+
+ads = NativeAds(api_key="sk_live_xxx", platform_id="plt_xxx")
+
+# inside an async message handler, after generating the LLM answer:
+result = await ads.inject(
+    user_id=message.from_user.id,
+    message=llm_answer,
+    language_code=message.from_user.language_code,
+    is_premium=message.from_user.is_premium,
+    keyboard=my_keyboard,        # optional — aiogram / PTB / raw dict
+    # ad_button_position="top",  # default "bottom"
+)
+await message.answer(result.message, reply_markup=result.keyboard)
+```
+
+### aiogram middleware (DI)
+```python
+from nativeads import NativeAds
+from nativeads.middleware import NativeAdsMiddleware
+
+mw = NativeAdsMiddleware(api_key="sk_live_xxx", platform_id="plt_xxx")
+dp.message.middleware(mw)
+dp.shutdown.register(mw.aclose)
+
+async def handler(message: Message, nativeads: NativeAds):
+    result = await nativeads.inject(user_id=message.from_user.id, message=answer)
+    await message.answer(result.message, reply_markup=result.keyboard)
+```
+
+## Privacy-friendly mode (`fetch`)
+```python
+res = await ads.fetch(user_id=uid, language_code="ru")
+if res.has_ad:
+    text = f"{llm_answer}\n\n{res.ad.ad_text}"
+    # render res.ad.button_text / res.ad.button_url yourself
+```
+
+## Guarantees
+- **Never raises.** On any error (timeout, network, 5xx) `inject()`/`fetch()` return your
+  original message and keyboard unchanged. Default timeout 3s.
+- **Your buttons are preserved** — the ad button is a separate row (top/bottom), respecting
+  Telegram's 4096-char and 13-row limits.
+- **Click tracking is automatic** — `button_url` is a tracking redirect.
+
+## API
+- `NativeAds(api_key, platform_id=None, *, base_url=..., timeout=3.0, platform="telegram", show_every=1, skip_first=0)`
+  - `show_every` — ad on every Nth message (5 = optimal, 0 = off); N>1 keeps the first message ad-free.
+  - `skip_first` — never show an ad on a user's first N messages.
+  - Frequency is client-side (in-memory per-user counter); skipped turns return your message without a server call.
+  - `NativeAdsMiddleware(...)` accepts the same `show_every` / `skip_first`.
+- `await ads.inject(*, user_id, message, language_code=None, is_premium=None, keyboard=None, ad_button_position="bottom", parse_mode=None) -> InjectResult`
+- `await ads.fetch(*, user_id, language_code=None, is_premium=None, parse_mode=None) -> FetchResult`
+- `await ads.aclose()`
+
+`InjectResult(message, has_ad, impression_id, ad, keyboard)` ·
+`FetchResult(has_ad, impression_id, ad)` ·
+`Ad(ad_text, button_text, button_url, ad_text_formatted)`

nativeads-0.1.0/examples/README.md

@@ -0,0 +1,23 @@
+# NativeAds Python examples
+
+## `chatgpt_aiogram_bot.py`
+A ChatGPT-wrapper Telegram bot (aiogram 3.x) monetized with NativeAds via `inject()`.
+The LLM answer comes back with a native ad woven in and the button merged into the keyboard.
+
+```bash
+pip install nativeads[aiogram] openai
+BOT_TOKEN=...  OPENAI_API_KEY=... \
+AD_API_KEY=sk_live_...  AD_BASE=https://nativeads.cloud \
+  python chatgpt_aiogram_bot.py
+```
+
+| env | required | default |
+|-----|:--------:|---------|
+| `BOT_TOKEN` | ✅ | — |
+| `OPENAI_API_KEY` | ✅ | — |
+| `AD_API_KEY` | — | empty = ads off |
+| `AD_BASE` | — | `https://nativeads.cloud` |
+| `OPENAI_MODEL` | — | `gpt-4o-mini` |
+| `SYSTEM_PROMPT` / `MAX_HISTORY` | — | sensible defaults |
+
+> One long-poll per bot token — don't run two bots on the same `BOT_TOKEN` at once.

nativeads-0.1.0/examples/chatgpt_aiogram_bot.py

@@ -0,0 +1,109 @@
+"""Example: a ChatGPT-wrapper Telegram bot (aiogram 3.x) monetized with NativeAds.
+
+The LLM answer is passed through `inject()` — it comes back with a native ad woven
+into the text and the ad button merged into the keyboard. `inject()` never raises,
+so the ad layer can't break the bot.
+
+Run:
+    pip install nativeads[aiogram] openai
+    BOT_TOKEN=... OPENAI_API_KEY=... \
+    AD_API_KEY=sk_live_... AD_BASE=https://nativeads.cloud \
+        python chatgpt_aiogram_bot.py
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+
+from aiogram import Bot, Dispatcher
+from aiogram.filters import Command, CommandStart
+from aiogram.types import Message
+from openai import AsyncOpenAI
+
+from nativeads import NativeAds
+from nativeads.middleware import NativeAdsMiddleware
+
+BOT_TOKEN = os.environ["BOT_TOKEN"]
+OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
+OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+AD_API_KEY = os.environ.get("AD_API_KEY", "")
+AD_BASE = os.environ.get("AD_BASE", "https://nativeads.cloud")
+SYSTEM_PROMPT = os.environ.get(
+    "SYSTEM_PROMPT", "Ты — дружелюбный ассистент. Отвечай кратко и по делу на языке пользователя."
+)
+MAX_HISTORY = int(os.environ.get("MAX_HISTORY", "10"))
+
+openai = AsyncOpenAI(api_key=OPENAI_API_KEY)
+history: dict[int, list[dict]] = {}
+
+dp = Dispatcher()
+
+
+@dp.message(CommandStart())
+async def start(message: Message) -> None:
+    await message.answer(
+        "👋 Привет! Я ИИ-ассистент на базе ChatGPT. Спроси что угодно.\n\n/reset — сброс контекста"
+    )
+
+
+@dp.message(Command("reset"))
+async def reset(message: Message) -> None:
+    history.pop(message.chat.id, None)
+    await message.answer("🧹 Контекст очищен.")
+
+
+@dp.message()
+async def handle(message: Message, nativeads: NativeAds | None = None) -> None:
+    if not message.text or message.text.startswith("/"):
+        return
+
+    chat_id = message.chat.id
+    await message.bot.send_chat_action(chat_id, "typing")
+
+    msgs = (
+        [{"role": "system", "content": SYSTEM_PROMPT}]
+        + history.get(chat_id, [])
+        + [{"role": "user", "content": message.text}]
+    )
+    try:
+        resp = await openai.chat.completions.create(
+            model=OPENAI_MODEL, messages=msgs, temperature=0.7
+        )
+        answer = (resp.choices[0].message.content or "").strip() or "(пустой ответ)"
+    except Exception as e:  # noqa: BLE001
+        await message.answer(f"⚠️ Ошибка ИИ: {e}")
+        return
+
+    history[chat_id] = (
+        history.get(chat_id, [])
+        + [{"role": "user", "content": message.text}, {"role": "assistant", "content": answer}]
+    )[-MAX_HISTORY:]
+
+    user = message.from_user
+    # Monetize: hand the answer to inject() — get it back with a native ad + button.
+    if nativeads is not None and user is not None:
+        result = await nativeads.inject(
+            user_id=user.id,
+            message=answer,
+            language_code=user.language_code,
+            is_premium=user.is_premium,
+        )
+        if result.has_ad:
+            print(f"injected ad → impression #{result.impression_id}")
+        await message.answer(result.message, reply_markup=result.keyboard)
+    else:
+        await message.answer(answer)
+
+
+async def main() -> None:
+    bot = Bot(token=BOT_TOKEN)
+    if AD_API_KEY:
+        mw = NativeAdsMiddleware(api_key=AD_API_KEY, base_url=AD_BASE)
+        dp.message.middleware(mw)
+        dp.shutdown.register(mw.aclose)
+    print(f"Python bot started. model={OPENAI_MODEL}, ads={'on' if AD_API_KEY else 'off'}")
+    await dp.start_polling(bot)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

nativeads-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "nativeads"
+version = "0.1.0"
+description = "NativeAds SDK for Telegram bots — inject ads into LLM replies (aiogram / python-telegram-bot / raw)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["telegram", "ads", "aiogram", "python-telegram-bot", "monetization", "bot"]
+dependencies = ["httpx>=0.25.0"]
+
+[project.urls]
+Homepage = "https://nativeads.cloud"
+
+[project.optional-dependencies]
+aiogram = ["aiogram>=3.0"]
+ptb = ["python-telegram-bot>=20.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nativeads"]

nativeads-0.1.0/src/nativeads/__init__.py

@@ -0,0 +1,5 @@
+from .client import AibotAds, Ad, FetchResult, InjectResult, NativeAds
+from .keyboard import merge_keyboard
+
+__all__ = ["NativeAds", "AibotAds", "Ad", "InjectResult", "FetchResult", "merge_keyboard"]
+__version__ = "0.1.0"

nativeads-0.1.0/src/nativeads/client.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from .keyboard import merge_keyboard
+
+__version__ = "0.1.0"
+_TELEGRAM_MAX_MESSAGE_LENGTH = 4096
+
+
+@dataclass
+class Ad:
+    ad_text: str
+    button_text: str
+    button_url: str
+    ad_text_formatted: Optional[str] = None
+
+
+@dataclass
+class InjectResult:
+    message: str
+    has_ad: bool
+    impression_id: Optional[int]
+    ad: Optional[Ad]
+    keyboard: Any
+
+
+@dataclass
+class FetchResult:
+    has_ad: bool
+    impression_id: Optional[int]
+    ad: Optional[Ad]
+
+
+class NativeAds:
+    """NativeAds client for Telegram bots.
+
+    ``inject()`` and ``fetch()`` NEVER raise — on any error (timeout, network,
+    5xx) they return your original message/keyboard unchanged, so ads can never
+    break the bot. Default timeout is 3 seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        platform_id: Optional[str] = None,
+        *,
+        base_url: str = "https://nativeads.cloud",
+        timeout: float = 3.0,
+        platform: str = "telegram",
+        show_every: int = 1,
+        skip_first: int = 0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("NativeAds: api_key is required")
+        self._api_key = api_key
+        self._platform_id = platform_id
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._platform = platform
+        # Show an ad on every Nth message per user (1 = every; 0 = disabled).
+        # With N>1 the first N-1 messages are ad-free. skip_first never shows an
+        # ad on a user's first M messages.
+        self._show_every = show_every
+        self._skip_first = skip_first
+        self._counts: dict[int, int] = {}
+        self._client: Optional[httpx.AsyncClient] = None
+
+    def _should_show(self, user_id: int) -> bool:
+        """Per-user message counter → whether this turn should carry an ad.
+        In-memory (per process) — cadence is approximate across restarts."""
+        n = self._counts.get(user_id, 0) + 1
+        self._counts[user_id] = n
+        if self._show_every <= 0:
+            return False
+        if n <= self._skip_first:
+            return False
+        return (n - self._skip_first) % self._show_every == 0
+
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Content-Type": "application/json",
+                    "User-Agent": f"nativeads-python/{__version__}",
+                },
+                timeout=httpx.Timeout(self._timeout),
+            )
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
+    async def inject(
+        self,
+        *,
+        user_id: int,
+        message: str,
+        language_code: Optional[str] = None,
+        is_premium: Optional[bool] = None,
+        keyboard: Any = None,
+        ad_button_position: str = "bottom",
+        parse_mode: Optional[str] = None,
+    ) -> InjectResult:
+        """Pass the LLM reply (and optionally the keyboard you were going to send);
+        get them back with a native ad injected. Never raises."""
+        fallback = InjectResult(
+            message=message, has_ad=False, impression_id=None, ad=None, keyboard=keyboard
+        )
+
+        # Frequency gate: skip this turn (no server call, no impression).
+        if not self._should_show(user_id):
+            return fallback
+
+        try:
+            payload = {
+                "user_id": user_id,
+                "message": message,
+                "platform_id": self._platform_id,
+                "language_code": language_code or "",
+                "is_premium": bool(is_premium),
+                "platform": self._platform,
+            }
+            if parse_mode:
+                payload["parse_mode"] = parse_mode
+
+            resp = await self._ensure_client().post("/api/v1/ad", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+
+            if not data.get("has_ad") or not data.get("ad"):
+                return InjectResult(
+                    message=data.get("message", message),
+                    has_ad=False,
+                    impression_id=data.get("impression_id"),
+                    ad=None,
+                    keyboard=keyboard,
+                )
+
+            raw = data["ad"]
+            ad = Ad(
+                ad_text=raw["ad_text"],
+                button_text=raw["button_text"],
+                button_url=raw["button_url"],
+                ad_text_formatted=raw.get("ad_text_formatted"),
+            )
+
+            result_message = data.get("message", message)
+            if len(result_message) > _TELEGRAM_MAX_MESSAGE_LENGTH:
+                result_message = message
+
+            result_keyboard = keyboard
+            if ad.button_text and ad.button_url:
+                result_keyboard = merge_keyboard(
+                    keyboard, ad.button_text, ad.button_url, ad_button_position
+                )
+
+            if result_keyboard is keyboard and result_message == message:
+                return fallback
+
+            return InjectResult(
+                message=result_message,
+                has_ad=True,
+                impression_id=data.get("impression_id"),
+                ad=ad,
+                keyboard=result_keyboard,
+            )
+        except Exception:
+            return fallback
+
+    async def fetch(
+        self,
+        *,
+        user_id: int,
+        language_code: Optional[str] = None,
+        is_premium: Optional[bool] = None,
+        parse_mode: Optional[str] = None,
+    ) -> FetchResult:
+        """Privacy-friendly alternative: get the ad as separate fields without
+        sending the LLM reply text. You render it yourself. Never raises."""
+        empty = FetchResult(has_ad=False, impression_id=None, ad=None)
+        try:
+            payload = {
+                "user_id": user_id,
+                "platform_id": self._platform_id,
+                "language_code": language_code or "",
+                "is_premium": bool(is_premium),
+                "platform": self._platform,
+            }
+            if parse_mode:
+                payload["parse_mode"] = parse_mode
+
+            resp = await self._ensure_client().post("/api/v1/ad/fetch", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+
+            if not data.get("has_ad") or not data.get("ad"):
+                return empty
+
+            raw = data["ad"]
+            return FetchResult(
+                has_ad=True,
+                impression_id=data.get("impression_id"),
+                ad=Ad(
+                    ad_text=raw["ad_text"],
+                    button_text=raw["button_text"],
+                    button_url=raw["button_url"],
+                    ad_text_formatted=raw.get("ad_text_formatted"),
+                ),
+            )
+        except Exception:
+            return empty
+
+
+# Deprecated alias, kept for compatibility with code written against the old name.
+AibotAds = NativeAds

nativeads-0.1.0/src/nativeads/keyboard.py

@@ -0,0 +1,77 @@
+"""Framework-aware inline-keyboard merging.
+
+Adds the ad button as its own row, never touching the publisher's buttons.
+Supports aiogram 3.x, python-telegram-bot v20+, and the raw Telegram dict shape.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+# Telegram's hard limit on inline keyboard rows.
+_MAX_ROWS = 13
+
+
+def _aiogram_types() -> Optional[Tuple[Any, Any]]:
+    try:
+        from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+        return InlineKeyboardMarkup, InlineKeyboardButton
+    except ImportError:
+        return None
+
+
+def _ptb_types() -> Optional[Tuple[Any, Any]]:
+    try:
+        from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+        return InlineKeyboardMarkup, InlineKeyboardButton
+    except ImportError:
+        return None
+
+
+def merge_keyboard(keyboard: Any, button_text: str, button_url: str, position: str = "bottom") -> Any:
+    """Return a new keyboard with the ad button row inserted (top/bottom), in the
+    same framework type it was given. Returns the original unchanged when the row
+    limit is reached or the shape is unrecognized."""
+    aiogram = _aiogram_types()
+    ptb = _ptb_types()
+
+    # --- existing aiogram markup ---
+    if aiogram is not None and isinstance(keyboard, aiogram[0]):
+        markup_cls, button_cls = aiogram
+        rows = list(keyboard.inline_keyboard)
+        if len(rows) >= _MAX_ROWS:
+            return keyboard
+        ad_row = [button_cls(text=button_text, url=button_url)]
+        rows = [ad_row] + rows if position == "top" else rows + [ad_row]
+        return markup_cls(inline_keyboard=rows)
+
+    # --- existing python-telegram-bot markup ---
+    if ptb is not None and isinstance(keyboard, ptb[0]):
+        markup_cls, button_cls = ptb
+        rows = [list(r) for r in keyboard.inline_keyboard]
+        if len(rows) >= _MAX_ROWS:
+            return keyboard
+        ad_row = [button_cls(text=button_text, url=button_url)]
+        rows = [ad_row] + rows if position == "top" else rows + [ad_row]
+        return markup_cls(rows)
+
+    # --- existing raw dict markup ---
+    if isinstance(keyboard, dict) and isinstance(keyboard.get("inline_keyboard"), list):
+        rows = list(keyboard["inline_keyboard"])
+        if len(rows) >= _MAX_ROWS:
+            return keyboard
+        ad_row = [{"text": button_text, "url": button_url}]
+        rows = [ad_row] + rows if position == "top" else rows + [ad_row]
+        return {**keyboard, "inline_keyboard": rows}
+
+    # --- no keyboard → build a fresh one in whatever framework is available ---
+    if keyboard is None:
+        if aiogram is not None:
+            markup_cls, button_cls = aiogram
+            return markup_cls(inline_keyboard=[[button_cls(text=button_text, url=button_url)]])
+        if ptb is not None:
+            markup_cls, button_cls = ptb
+            return markup_cls([[button_cls(text=button_text, url=button_url)]])
+        return {"inline_keyboard": [[{"text": button_text, "url": button_url}]]}
+
+    # Unrecognized shape — never break the bot.
+    return keyboard

nativeads-0.1.0/src/nativeads/middleware.py

@@ -0,0 +1,68 @@
+"""Optional aiogram 3.x middleware that injects a configured ``NativeAds`` into
+handler data, so handlers receive it via dependency injection.
+
+    from nativeads import NativeAds
+    from nativeads.middleware import NativeAdsMiddleware
+
+    mw = NativeAdsMiddleware(api_key="sk_live_...", platform_id="plt_...")
+    dp.message.middleware(mw)
+    dp.shutdown.register(mw.aclose)
+
+    async def handler(message: Message, nativeads: NativeAds):
+        result = await nativeads.inject(user_id=message.from_user.id, message=answer)
+"""
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from .client import NativeAds
+
+
+class NativeAdsMiddleware:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        platform_id: Optional[str] = None,
+        *,
+        client: Optional[NativeAds] = None,
+        base_url: str = "https://nativeads.cloud",
+        timeout: float = 3.0,
+        platform: str = "telegram",
+        show_every: int = 1,
+        skip_first: int = 0,
+    ) -> None:
+        if client is not None:
+            self.client = client
+            self._owned = False
+        else:
+            if not api_key:
+                raise TypeError("NativeAdsMiddleware requires api_key or an existing client=")
+            self.client = NativeAds(
+                api_key=api_key,
+                platform_id=platform_id,
+                base_url=base_url,
+                timeout=timeout,
+                platform=platform,
+                show_every=show_every,
+                skip_first=skip_first,
+            )
+            self._owned = True
+
+    async def aclose(self) -> None:
+        if self._owned:
+            await self.client.aclose()
+
+    async def __call__(
+        self,
+        handler: Callable[[Any, Dict[str, Any]], Awaitable[Any]],
+        event: Any,
+        data: Dict[str, Any],
+    ) -> Any:
+        # Inject under the new key; keep the old key for backward compatibility.
+        data["nativeads"] = self.client
+        data["aibotads"] = self.client
+        return await handler(event, data)
+
+
+# Deprecated alias, kept for compatibility with code written against the old name.
+AibotAdsMiddleware = NativeAdsMiddleware

nativeads-0.1.0/tests/run.py

@@ -0,0 +1,147 @@
+"""Integration + unit test for the NativeAds Python SDK against a local API.
+
+    AD_API_KEY=sk_live_... BASE_URL=http://localhost:3000 python tests/run.py
+"""
+import asyncio
+import os
+import sys
+
+from nativeads import NativeAds, merge_keyboard
+
+API_KEY = os.environ.get("AD_API_KEY")
+BASE_URL = os.environ.get("BASE_URL", "http://localhost:3000")
+if not API_KEY:
+    sys.exit("set AD_API_KEY")
+
+passed = 0
+
+
+def ok(name: str) -> None:
+    global passed
+    passed += 1
+    print(f"  \033[32m✓\033[0m {name}")
+
+
+def _aiogram_installed() -> bool:
+    try:
+        import aiogram.types  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def test_keyboard_unit() -> None:
+    print("\n— unit: merge_keyboard (raw dict) —")
+
+    # None → fresh keyboard. Shape depends on the installed framework.
+    k = merge_keyboard(None, "Ad", "u", "bottom")
+    if _aiogram_installed():
+        from aiogram.types import InlineKeyboardMarkup as AG
+        assert isinstance(k, AG) and len(k.inline_keyboard) == 1
+        ok("None keyboard → fresh aiogram markup (framework present)")
+    else:
+        assert k == {"inline_keyboard": [[{"text": "Ad", "url": "u"}]]}
+        ok("None keyboard → raw dict (core-only)")
+
+    raw = {"inline_keyboard": [[{"text": "A", "url": "a"}], [{"text": "B", "url": "b"}]]}
+    m = merge_keyboard(raw, "Ad", "u", "bottom")
+    assert len(m["inline_keyboard"]) == 3
+    assert m["inline_keyboard"][0] == [{"text": "A", "url": "a"}]
+    assert m["inline_keyboard"][2] == [{"text": "Ad", "url": "u"}]
+    assert len(raw["inline_keyboard"]) == 2, "original not mutated"
+    ok("raw keyboard: ad appended last, originals intact")
+
+    t = merge_keyboard(raw, "Ad", "u", "top")
+    assert t["inline_keyboard"][0] == [{"text": "Ad", "url": "u"}]
+    ok("position=top puts ad first")
+
+    full = {"inline_keyboard": [[{"text": str(i), "url": "x"}] for i in range(13)]}
+    assert merge_keyboard(full, "Ad", "u") is full
+    ok("13-row limit respected (returns original)")
+
+    weird = {"foo": "bar"}
+    assert merge_keyboard(weird, "Ad", "u") is weird
+    ok("unknown keyboard shape returned unchanged")
+
+
+def test_keyboard_aiogram() -> None:
+    try:
+        from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+    except ImportError:
+        print("\n— unit: aiogram keyboard — (skipped: aiogram not installed)")
+        return
+    print("\n— unit: merge_keyboard (aiogram) —")
+    kb = InlineKeyboardMarkup(inline_keyboard=[[InlineKeyboardButton(text="Mine", url="https://me")]])
+    merged = merge_keyboard(kb, "Ad", "https://ad", "bottom")
+    assert isinstance(merged, InlineKeyboardMarkup)
+    assert len(merged.inline_keyboard) == 2
+    assert merged.inline_keyboard[0][0].text == "Mine", "publisher button preserved"
+    assert merged.inline_keyboard[1][0].text == "Ad", "ad row at bottom"
+    ok("aiogram InlineKeyboardMarkup merged, type preserved")
+
+
+async def test_integration() -> None:
+    ads = NativeAds(API_KEY, platform_id="plt_localtest", base_url=BASE_URL)
+
+    print("\n— integration: inject —")
+    r = await ads.inject(user_id=800001, message="Столица Японии — Токио.", language_code="ru")
+    assert r.has_ad, "has ad"
+    assert r.impression_id, "impression id"
+    assert r.message.startswith("Столица Японии — Токио."), "original text preserved"
+    assert len(r.message) > len("Столица Японии — Токио."), "ad text appended"
+    assert "/api/v1/click/" in r.ad.button_url
+    ok(f"inject no-keyboard → ad injected (impression #{r.impression_id})")
+
+    existing = {"inline_keyboard": [[{"text": "Сайт", "url": "https://me.example"}]]}
+    r2 = await ads.inject(user_id=800002, message="Ответ.", keyboard=existing)
+    assert r2.has_ad
+    assert len(r2.keyboard["inline_keyboard"]) == 2, "existing + ad row"
+    assert r2.keyboard["inline_keyboard"][0][0]["text"] == "Сайт", "publisher button intact"
+    ok("inject with existing keyboard → ad row added, publisher button intact")
+
+    print("\n— integration: fetch —")
+    f = await ads.fetch(user_id=800003, language_code="ru")
+    assert f.has_ad and f.ad.ad_text and f.ad.button_url
+    ok(f"fetch → ad object (impression #{f.impression_id})")
+
+    print("\n— resilience: never raises —")
+    dead = NativeAds(API_KEY, base_url="http://127.0.0.1:59999", timeout=1.5)
+    kb = {"inline_keyboard": [[{"text": "Keep", "url": "k"}]]}
+    rd = await dead.inject(user_id=800004, message="original", keyboard=kb)
+    assert rd.has_ad is False and rd.message == "original" and rd.keyboard is kb
+    ok("inject() swallows network error, returns original")
+    fd = await dead.fetch(user_id=800005, language_code="ru")
+    assert fd.has_ad is False
+    ok("fetch() swallows network error")
+
+    print("\n— frequency: show_every / skip_first —")
+    every3 = NativeAds(API_KEY, base_url=BASE_URL, show_every=3)
+    seen = [(await every3.inject(user_id=800100, message="q")).has_ad for _ in range(6)]
+    assert seen == [False, False, True, False, False, True], "ad on every 3rd message"
+    ok("show_every=3 → ad on messages 3 and 6 (first message ad-free)")
+    await every3.aclose()
+
+    skip1 = NativeAds(API_KEY, base_url=BASE_URL, show_every=1, skip_first=1)
+    seen2 = [(await skip1.inject(user_id=800101, message="q")).has_ad for _ in range(3)]
+    assert seen2 == [False, True, True], "first message skipped, then every"
+    ok("skip_first=1 → no ad on the first message")
+    await skip1.aclose()
+
+    off = NativeAds(API_KEY, base_url=BASE_URL, show_every=0)
+    assert (await off.inject(user_id=800102, message="q")).has_ad is False
+    ok("show_every=0 → ads disabled")
+    await off.aclose()
+
+    await ads.aclose()
+    await dead.aclose()
+
+
+def main() -> None:
+    test_keyboard_unit()
+    test_keyboard_aiogram()
+    asyncio.run(test_integration())
+    print(f"\n\033[32mALL {passed} CHECKS PASSED\033[0m\n")
+
+
+if __name__ == "__main__":
+    main()

nativeads-0.1.0/tests/unit.py

@@ -0,0 +1,336 @@
+"""Offline unit tests for the NativeAds Python SDK — no server or API key needed.
+
+The httpx transport is mocked so every branch is deterministic.
+
+    python tests/unit.py
+"""
+import asyncio
+import json
+import sys
+
+import httpx
+
+from nativeads import Ad, AibotAds, NativeAds, merge_keyboard
+from nativeads import client as client_mod
+from nativeads.middleware import AibotAdsMiddleware, NativeAdsMiddleware
+
+passed = 0
+
+
+def ok(name: str) -> None:
+    global passed
+    passed += 1
+    print(f"  \033[32m✓\033[0m {name}")
+
+
+AD = {
+    "ad_text": "Try Acme — the best widget.",
+    "button_text": "Open Acme",
+    "button_url": "https://nativeads.cloud/api/v1/click/42",
+    "ad_text_formatted": "<b>Try Acme</b>",
+}
+
+
+def ad_response(**over):
+    body = {
+        "has_ad": True,
+        "impression_id": 42,
+        "message": "Paris is the capital of France.\n\nTry Acme — the best widget.",
+        "ad": AD,
+    }
+    body.update(over)
+    return body
+
+
+class _Patch:
+    """Force every httpx.AsyncClient the SDK builds to use a MockTransport whose
+    handler returns `responder(request)`. Records every request for assertions."""
+
+    def __init__(self, responder):
+        self.responder = responder
+        self.requests = []
+        self._orig = httpx.AsyncClient
+
+    def _handler(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        out = self.responder(request)
+        if isinstance(out, httpx.Response):
+            return out
+        return httpx.Response(200, json=out)
+
+    def __enter__(self):
+        transport = httpx.MockTransport(self._handler)
+        orig = self._orig
+
+        def factory(*args, **kwargs):
+            kwargs["transport"] = transport
+            return orig(*args, **kwargs)
+
+        client_mod.httpx.AsyncClient = factory
+        return self
+
+    def __exit__(self, *exc):
+        client_mod.httpx.AsyncClient = self._orig
+        return False
+
+
+def body_of(request: httpx.Request) -> dict:
+    return json.loads(request.content)
+
+
+def rows_of(keyboard) -> list:
+    """Normalize a keyboard (raw dict / aiogram / PTB markup) to a list of rows
+    of (text, url) tuples, so assertions don't depend on the installed framework."""
+    if isinstance(keyboard, dict):
+        rows = keyboard["inline_keyboard"]
+    else:
+        rows = keyboard.inline_keyboard  # aiogram / PTB markup
+    out = []
+    for row in rows:
+        norm = []
+        for btn in row:
+            if isinstance(btn, dict):
+                norm.append((btn["text"], btn["url"]))
+            else:
+                norm.append((btn.text, btn.url))
+        out.append(norm)
+    return out
+
+
+# --- sync tests ---
+
+def test_constructor_requires_api_key():
+    try:
+        NativeAds("")
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "api_key" in str(e)
+    ok("constructor requires api_key")
+
+
+def test_backward_compat_alias():
+    assert AibotAds is NativeAds
+    assert AibotAdsMiddleware is NativeAdsMiddleware
+    ok("AibotAds / AibotAdsMiddleware are aliases for the NativeAds names")
+
+
+def test_default_base_url():
+    ads = NativeAds("sk_live_x")
+    assert ads._base_url == "https://nativeads.cloud", ads._base_url
+    ok("default base_url is https://nativeads.cloud")
+
+
+def test_base_url_trailing_slash_trimmed():
+    ads = NativeAds("sk", base_url="https://example.com///")
+    assert ads._base_url == "https://example.com"
+    ok("trailing slashes trimmed from base_url")
+
+
+def test_merge_keyboard_raw():
+    k = merge_keyboard(None, "Ad", "u", "bottom")
+    # core-only env → raw dict; with a framework installed → framework markup.
+    if isinstance(k, dict):
+        assert k == {"inline_keyboard": [[{"text": "Ad", "url": "u"}]]}
+
+    raw = {"inline_keyboard": [[{"text": "A", "url": "a"}], [{"text": "B", "url": "b"}]]}
+    m = merge_keyboard(raw, "Ad", "u", "bottom")
+    assert len(m["inline_keyboard"]) == 3
+    assert m["inline_keyboard"][2] == [{"text": "Ad", "url": "u"}]
+    assert len(raw["inline_keyboard"]) == 2, "original not mutated"
+
+    t = merge_keyboard(raw, "Ad", "u", "top")
+    assert t["inline_keyboard"][0] == [{"text": "Ad", "url": "u"}]
+
+    full = {"inline_keyboard": [[{"text": str(i), "url": "x"}] for i in range(13)]}
+    assert merge_keyboard(full, "Ad", "u") is full
+
+    weird = {"foo": "bar"}
+    assert merge_keyboard(weird, "Ad", "u") is weird
+    ok("merge_keyboard (raw dict): append/top/limit/unknown all correct")
+
+
+# --- async tests ---
+
+async def test_inject_payload_and_headers():
+    with _Patch(lambda req: ad_response()) as p:
+        ads = NativeAds("sk_live_abc", platform_id="plt_1", platform="discord")
+        await ads.inject(
+            user_id=555, message="hello", language_code="ru",
+            is_premium=True, parse_mode="HTML",
+        )
+        await ads.aclose()
+    req = p.requests[0]
+    assert str(req.url) == "https://nativeads.cloud/api/v1/ad", str(req.url)
+    assert req.headers["authorization"] == "Bearer sk_live_abc"
+    assert req.headers["user-agent"].startswith("nativeads-python/")
+    assert body_of(req) == {
+        "user_id": 555, "message": "hello", "platform_id": "plt_1",
+        "language_code": "ru", "is_premium": True, "platform": "discord",
+        "parse_mode": "HTML",
+    }
+    ok("inject sends correct URL, auth header and payload")
+
+
+async def test_inject_weaves_ad_and_keyboard():
+    with _Patch(lambda req: ad_response()):
+        ads = NativeAds("sk")
+        r = await ads.inject(user_id=1, message="Paris is the capital of France.")
+        await ads.aclose()
+    assert r.has_ad and r.impression_id == 42
+    assert r.message == ad_response()["message"]
+    assert isinstance(r.ad, Ad) and r.ad.button_url == AD["button_url"]
+    # Shape adapts to the installed framework; compare normalized rows.
+    assert rows_of(r.keyboard) == [[("Open Acme", AD["button_url"])]]
+    ok("inject weaves ad text + adds ad button row")
+
+
+async def test_inject_preserves_existing_keyboard():
+    with _Patch(lambda req: ad_response()):
+        ads = NativeAds("sk")
+        existing = {"inline_keyboard": [[{"text": "My site", "url": "https://me"}]]}
+        r = await ads.inject(user_id=1, message="x", keyboard=existing)
+        await ads.aclose()
+    assert len(r.keyboard["inline_keyboard"]) == 2
+    assert r.keyboard["inline_keyboard"][0] == [{"text": "My site", "url": "https://me"}]
+    assert len(existing["inline_keyboard"]) == 1, "caller keyboard not mutated"
+    ok("inject preserves existing keyboard, appends ad row")
+
+
+async def test_inject_no_ad():
+    with _Patch(lambda req: {"has_ad": False, "impression_id": 7, "ad": None}):
+        ads = NativeAds("sk")
+        kb = {"inline_keyboard": [[{"text": "Keep", "url": "k"}]]}
+        r = await ads.inject(user_id=1, message="original", keyboard=kb)
+        await ads.aclose()
+    assert r.has_ad is False and r.message == "original"
+    assert r.impression_id == 7 and r.keyboard is kb
+    ok("inject: no ad → original message, impression_id passthrough")
+
+
+async def test_inject_message_too_long():
+    long_msg = "x" * 5000
+    with _Patch(lambda req: ad_response(message=long_msg)):
+        ads = NativeAds("sk")
+        r = await ads.inject(user_id=1, message="original short")
+        await ads.aclose()
+    assert r.has_ad is True
+    assert r.message == "original short", "falls back to original when too long"
+    assert rows_of(r.keyboard) == [[("Open Acme", AD["button_url"])]], "button still attached"
+    ok("inject: server message > 4096 → keep original text but attach button")
+
+
+async def test_inject_http_500():
+    with _Patch(lambda req: httpx.Response(500, json={"error": "boom"})):
+        ads = NativeAds("sk")
+        kb = {"inline_keyboard": [[{"text": "Keep", "url": "k"}]]}
+        r = await ads.inject(user_id=1, message="original", keyboard=kb)
+        await ads.aclose()
+    assert r.has_ad is False and r.message == "original" and r.keyboard is kb
+    ok("inject: HTTP 500 → silent fallback (never raises)")
+
+
+async def test_inject_network_error():
+    def boom(req):
+        raise httpx.ConnectError("refused", request=req)
+    with _Patch(boom):
+        ads = NativeAds("sk")
+        r = await ads.inject(user_id=1, message="original")
+        await ads.aclose()
+    assert r.has_ad is False and r.message == "original"
+    ok("inject: network error → silent fallback")
+
+
+async def test_fetch():
+    with _Patch(lambda req: ad_response()) as p:
+        ads = NativeAds("sk")
+        r = await ads.fetch(user_id=9, language_code="en")
+        await ads.aclose()
+    assert str(p.requests[0].url) == "https://nativeads.cloud/api/v1/ad/fetch"
+    assert "message" not in body_of(p.requests[0]), "fetch never sends reply text"
+    assert r.has_ad and r.ad.ad_text == AD["ad_text"]
+    ok("fetch returns ad fields without sending message text")
+
+
+async def test_fetch_error():
+    def boom(req):
+        raise httpx.ConnectTimeout("timeout", request=req)
+    with _Patch(boom):
+        ads = NativeAds("sk")
+        r = await ads.fetch(user_id=9)
+        await ads.aclose()
+    assert r.has_ad is False and r.impression_id is None and r.ad is None
+    ok("fetch: error → empty result")
+
+
+async def test_frequency_show_every():
+    with _Patch(lambda req: ad_response()) as p:
+        ads = NativeAds("sk", show_every=3)
+        seen = [(await ads.inject(user_id=1, message="q")).has_ad for _ in range(6)]
+        await ads.aclose()
+    assert seen == [False, False, True, False, False, True]
+    assert len(p.requests) == 2, "server only called on the 2 ad turns"
+    ok("show_every=3 → ad on turns 3 and 6, server skipped otherwise")
+
+
+async def test_frequency_skip_first():
+    with _Patch(lambda req: ad_response()):
+        ads = NativeAds("sk", skip_first=2)
+        seen = [(await ads.inject(user_id=1, message="q")).has_ad for _ in range(4)]
+        await ads.aclose()
+    assert seen == [False, False, True, True]
+    ok("skip_first=2 → first two turns ad-free")
+
+
+async def test_frequency_off():
+    with _Patch(lambda req: ad_response()) as p:
+        ads = NativeAds("sk", show_every=0)
+        r = await ads.inject(user_id=1, message="q")
+        await ads.aclose()
+    assert r.has_ad is False and len(p.requests) == 0
+    ok("show_every=0 → ads disabled, no server call")
+
+
+async def test_frequency_per_user():
+    with _Patch(lambda req: ad_response()):
+        ads = NativeAds("sk", show_every=2)
+        assert (await ads.inject(user_id=1, message="q")).has_ad is False
+        assert (await ads.inject(user_id=2, message="q")).has_ad is False
+        assert (await ads.inject(user_id=1, message="q")).has_ad is True
+        assert (await ads.inject(user_id=2, message="q")).has_ad is True
+        await ads.aclose()
+    ok("frequency counters are independent per user")
+
+
+async def run_async():
+    for fn in (
+        test_inject_payload_and_headers,
+        test_inject_weaves_ad_and_keyboard,
+        test_inject_preserves_existing_keyboard,
+        test_inject_no_ad,
+        test_inject_message_too_long,
+        test_inject_http_500,
+        test_inject_network_error,
+        test_fetch,
+        test_fetch_error,
+        test_frequency_show_every,
+        test_frequency_skip_first,
+        test_frequency_off,
+        test_frequency_per_user,
+    ):
+        await fn()
+
+
+def main():
+    print("\n— sync —")
+    test_constructor_requires_api_key()
+    test_backward_compat_alias()
+    test_default_base_url()
+    test_base_url_trailing_slash_trimmed()
+    test_merge_keyboard_raw()
+    print("\n— async (mocked httpx) —")
+    asyncio.run(run_async())
+    print(f"\n\033[32mALL {passed} CHECKS PASSED\033[0m\n")
+
+
+if __name__ == "__main__":
+    main()