Metadata-Version: 2.4
Name: adstelo
Version: 0.2.2
Summary: Adstelo Python SDK — Monetize your Telegram bot with one line of code
Author-email: Adstelo <support@adstelo.com>
License: Copyright (c) 2026 Adstelo. All rights reserved.
        
        This source code is provided for auditing and integration purposes only.
        Unauthorized copying, modification, republication, or distribution of this code
        is strictly prohibited. 
        
        For licensing inquiries, please contact support@adstelo.com.
        
Project-URL: Homepage, https://adstelo.com
Project-URL: Documentation, https://adstelo.com/documentation
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp
Requires-Dist: requests
Dynamic: license-file

# Adstelo Python SDK

**Monetize your Telegram bot with a single line of code.**

Adstelo lets you earn revenue from ads displayed in your Telegram bot — just add two lines to your existing bot and start earning.

[![PyPI version](https://badge.fury.io/py/adstelo.svg)](https://pypi.org/project/adstelo/)
[![Python 3.7+](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/)

---

## Table of Contents

- [How It Works](#how-it-works)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Supported Libraries](#supported-libraries)
  - [aiogram v3](#aiogram-v3)
  - [python-telegram-bot v20+](#python-telegram-bot-v20)
  - [pyTelegramBotAPI (telebot)](#pytelegrambotapi-telebot)
  - [Telethon](#telethon)
- [Configuration Reference](#configuration-reference)
- [Getting Your Keys](#getting-your-keys)
- [FAQ](#faq)

---

1. You register your bot on Adstelo and get a `bot_secret` + `api_key`.
2. You call `adstelo.init(...)` **once** at the top of your bot code.
3. The SDK records usage metrics to help Adstelo optimize ad delivery.
4. **No message content is ever read or transmitted** to Adstelo or any third party. Only high-level usage metrics are sent in the background.

> **Security**: Your Telegram bot token is **never transmitted**. Only an opaque `bot_secret` is sent. All requests are HMAC-signed with your API key.

---

## Installation

```bash
pip install adstelo
```

**Requires Python 3.7+**. The only dependency is `aiohttp`.

---

## Quick Start

```python
import adstelo

adstelo.init(
    bot_secret="your-bot-secret",   # From your Adstelo dashboard
    api_key="your-api-key",         # From your Adstelo dashboard
)

# ... rest of your bot code, completely unchanged
```

That's it. The SDK auto-detects whichever Telegram library you have installed and patches it transparently.

---

## Supported Libraries

### aiogram v3

```python
import adstelo
from aiogram import Bot, Dispatcher

# ✅ Initialize Adstelo BEFORE creating the Dispatcher
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

@dp.message()
async def handle_message(message):
    await message.answer("Hello!")

# Run your bot as usual
import asyncio
asyncio.run(dp.start_polling(bot))
```

---

### python-telegram-bot v20+

```python
import adstelo
from telegram.ext import Application, MessageHandler, filters

# ✅ Initialize Adstelo BEFORE building the Application
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

async def handle_message(update, context):
    await update.message.reply_text("Hello!")

app = Application.builder().token("YOUR_BOT_TOKEN").build()
app.add_handler(MessageHandler(filters.TEXT, handle_message))
app.run_polling()
```

---

### pyTelegramBotAPI (telebot)

**Synchronous:**

```python
import adstelo
import telebot

# ✅ Initialize Adstelo BEFORE creating the TeleBot instance
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

bot = telebot.TeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(func=lambda m: True)
def handle_message(message):
    bot.send_message(message.chat.id, "Hello!")

bot.infinity_polling()
```

**Async:**

```python
import adstelo
from telebot.async_telebot import AsyncTeleBot
import asyncio

adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

bot = AsyncTeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(func=lambda m: True)
async def handle_message(message):
    await bot.send_message(message.chat.id, "Hello!")

asyncio.run(bot.polling())
```

---

### Telethon

```python
import adstelo
from telethon import TelegramClient, events

# ✅ Initialize Adstelo BEFORE creating the TelegramClient
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

client = TelegramClient("my_bot", api_id=12345, api_hash="your_api_hash")
client.start(bot_token="YOUR_BOT_TOKEN")

@client.on(events.NewMessage)
async def handle_message(event):
    await event.reply("Hello!")

client.run_until_disconnected()
```

---

## Configuration Reference

| Parameter | Type | Required | Description |
|---|---|---|---|
| `bot_secret` | `str` | ✅ Yes | Your bot's secret from the Adstelo dashboard. Identifies your bot server-side without exposing your Telegram token. |
| `api_key` | `str` | ✅ Yes | Your Adstelo API key. Used to authenticate requests and sign payloads. |
| `cooldown` | `int \| float` | ❌ No | Per-user event cooldown in seconds. Default: `2`. Prevents duplicate events from rapid interactions. |

---

## Getting Your Keys

1. **Sign up** at [adstelo.com](https://adstelo.com) and log in to your dashboard
2. Go to **"Register Bot"** and submit your bot's Telegram username
3. Once approved, your dashboard will show:
   - `bot_secret` — unique to each registered bot
   - `api_key` — tied to your account (used across all your bots)
4. Copy both values and pass them to `adstelo.init()`

> Your `api_key` is like a password — keep it private and never commit it to version control. Use environment variables:
>
> ```python
> import os, adstelo
> adstelo.init(
>     bot_secret=os.environ["ADSTELO_BOT_SECRET"],
>     api_key=os.environ["ADSTELO_API_KEY"],
> )
> ```

---

## FAQ

**Does this slow down my bot?**
No. Events are dispatched asynchronously in the background and never block your handlers. The timeout for each request is 3 seconds and errors are silently swallowed.

**What if I use a library that isn't listed?**
The SDK currently supports aiogram v3, python-telegram-bot v20+, pyTelegramBotAPI (sync & async), and Telethon. More libraries are on the roadmap. Open an issue or email support@adstelo.com.

**What exactly is tracked?**
The SDK reports: user ID, chat ID, event type (`message`, `button`, `photo`, `video`, `sticker`, `inline_query`), a timestamp, and whether it was a `/start` command. No message content is ever read or transmitted.

**What is the difference between `bot_secret` and `api_key`?**
- `bot_secret` — identifies *which bot* generated the event. One per bot.
- `api_key` — authenticates *your account*. One per publisher account.

**Do I need to change anything else in my bot?**
No. Call `adstelo.init()` once at startup before your Dispatcher/Application/Bot is created, and everything else stays exactly as-is.

**When do I get paid?**
Earnings from ads displayed in your bot accumulate in your Adstelo dashboard. Withdrawals are processed on request. See [adstelo.com](https://adstelo.com) for payout details.

---

## License

Proprietary — © Adstelo. All rights reserved.
