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)`
