nativeads 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+nativeads/__init__.py,sha256=KZXVut1Xm0NbaZANnBbChoxD10gUSlT61oDv9tVMeTY,222
+nativeads/client.py,sha256=8gEV20ldCtmomzGlx60B7wWtED3AqOKxsWPc0LKeXQ4,7309
+nativeads/keyboard.py,sha256=lKj52LETxyU61b8r1h0W10YMj5RW1H_p_l6jv09Ms8U,3081
+nativeads/middleware.py,sha256=-Fryc0pTdz4RICazHl__Rh9L6jE752o4wmc4O209yW0,2215
+nativeads-0.1.0.dist-info/METADATA,sha256=NTeuJ_xiYraT8XDT6jYGBdppchJ_dpZ-hnX0iSoWXgQ,3545
+nativeads-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+nativeads-0.1.0.dist-info/RECORD,,

nativeads-0.1.0.dist-info/WHEEL

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