adsun 1.0.0__py3-none-any.whl

adsun/__init__.py

@@ -0,0 +1,19 @@
+"""Adsun — Telegram ad network SDK for Python.
+
+Docs: https://adsun.io/docs · Bot monetization: https://adsun.io/telegram-bot-monetization
+
+    from adsun import AdsunBot
+    ads = AdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")
+    ad = ads.get_ad(user_id=123456789, language="en")   # None when no ad right now
+"""
+from .client import ADSUN_API_URL, AdsunBot, AsyncAdsunBot
+from .errors import AdsunError, BadRequest, BlockNotActive, InvalidToken
+from .models import BotAd
+from .reward import RewardCallback, parse_reward_callback, verify_secret
+
+__version__ = "1.0.0"
+__all__ = [
+    "ADSUN_API_URL", "AdsunBot", "AsyncAdsunBot", "BotAd",
+    "AdsunError", "BadRequest", "BlockNotActive", "InvalidToken",
+    "RewardCallback", "parse_reward_callback", "verify_secret",
+]

adsun/client.py

@@ -0,0 +1,99 @@
+"""HTTP clients for the Adsun bot ads API (``GET /advbot``)."""
+import json
+import re
+from typing import Any, Dict, Optional, Union
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .errors import AdsunError, BadRequest, InvalidToken, error_for
+from .models import BotAd
+
+ADSUN_API_URL = "https://api.adsun.io"
+_UA = "adsun-python/1.0.0"
+
+
+def block_number(block_id: Union[str, int]) -> str:
+    """``"bot-50001"`` / ``"tw-50001"`` / ``50001`` → ``"50001"`` (the API wants the numeric part)."""
+    num = re.sub(r"^(?:bot-|tw-)", "", str(block_id).strip(), flags=re.I)
+    if not num.isdigit():
+        raise BadRequest("block_id must be numeric, e.g. 50001 (got {!r})".format(block_id), 400)
+    return num
+
+
+class _Base:
+    def __init__(self, token: str, block_id: Union[str, int], api_url: str = ADSUN_API_URL, timeout: float = 10.0):
+        if not token:
+            raise InvalidToken("token is required (Adsun panel → Profile → Token)", 401)
+        self.token = token
+        self.block_id = block_number(block_id)
+        self.api_url = api_url.rstrip("/")
+        self.timeout = timeout
+
+    def _params(self, user_id: Union[int, str], language: str) -> Dict[str, str]:
+        uid = str(user_id)
+        if not uid.isdigit():
+            raise BadRequest("user_id must be the numeric Telegram user id", 400)
+        return {"tgid": uid, "blockid": self.block_id, "language": language or "", "token": self.token}
+
+    @staticmethod
+    def _message(body: bytes) -> str:
+        try:
+            return str(json.loads(body.decode("utf-8")).get("error") or "")
+        except Exception:
+            return body.decode("utf-8", "replace")[:200]
+
+
+class AdsunBot(_Base):
+    """Synchronous client (standard library only).
+
+    >>> ads = AdsunBot(token="...", block_id="50001")
+    >>> ad = ads.get_ad(user_id=123456789, language="en")
+    """
+
+    def get_ad(self, user_id: Union[int, str], language: str = "") -> Optional[BotAd]:
+        """Returns a :class:`BotAd`, or ``None`` when there is no ad right now (HTTP 204)."""
+        url = "{}/advbot?{}".format(self.api_url, urlencode(self._params(user_id, language)))
+        req = Request(url, headers={"User-Agent": _UA, "Accept": "application/json"})
+        try:
+            with urlopen(req, timeout=self.timeout) as r:  # noqa: S310 (fixed https API)
+                if r.status == 204:
+                    return None
+                body = r.read()
+                if not body:
+                    return None
+                return BotAd.from_dict(json.loads(body.decode("utf-8")))
+        except HTTPError as e:
+            raise error_for(e.code, self._message(e.read() or b""))
+        except URLError as e:
+            raise AdsunError("network error: {}".format(e.reason), 0)
+
+
+class AsyncAdsunBot(_Base):
+    """asyncio client (needs ``pip install adsun[async]``). Pass your own ``aiohttp.ClientSession`` to reuse it."""
+
+    def __init__(self, token: str, block_id: Union[str, int], api_url: str = ADSUN_API_URL, timeout: float = 10.0, session: Any = None):
+        super().__init__(token, block_id, api_url, timeout)
+        self._session = session
+
+    async def get_ad(self, user_id: Union[int, str], language: str = "") -> Optional[BotAd]:
+        try:
+            import aiohttp
+        except ImportError as e:  # pragma: no cover
+            raise AdsunError("AsyncAdsunBot needs aiohttp: pip install 'adsun[async]'") from e
+        params = self._params(user_id, language)
+        own = self._session is None
+        session = self._session or aiohttp.ClientSession(headers={"User-Agent": _UA})
+        try:
+            async with session.get(self.api_url + "/advbot", params=params, timeout=aiohttp.ClientTimeout(total=self.timeout)) as r:
+                if r.status == 204:
+                    return None
+                body = await r.read()
+                if r.status >= 400:
+                    raise error_for(r.status, self._message(body))
+                return BotAd.from_dict(json.loads(body.decode("utf-8"))) if body else None
+        except aiohttp.ClientError as e:
+            raise AdsunError("network error: {}".format(e), 0)
+        finally:
+            if own:
+                await session.close()

adsun/errors.py

@@ -0,0 +1,23 @@
+class AdsunError(Exception):
+    """Base error. ``status`` is the HTTP status from the Adsun API (0 for network errors)."""
+
+    def __init__(self, message: str, status: int = 0):
+        super().__init__(message)
+        self.status = status
+
+
+class BadRequest(AdsunError):
+    """400 — e.g. blockid must be the numeric part only (``50001``, not ``bot-50001``)."""
+
+
+class InvalidToken(AdsunError):
+    """401 — account token is wrong or was regenerated (Adsun panel → Profile → Token)."""
+
+
+class BlockNotActive(AdsunError):
+    """404 — the block does not exist, is not active or belongs to another account."""
+
+
+def error_for(status: int, message: str) -> AdsunError:
+    cls = {400: BadRequest, 401: InvalidToken, 404: BlockNotActive}.get(status, AdsunError)
+    return cls(message or "Adsun API error {}".format(status), status)

adsun/integrations/aiogram.py

@@ -0,0 +1,21 @@
+"""aiogram 3 helper: ``await send_ad(bot, chat_id, ads, user_id, language)``."""
+from typing import Optional
+
+from ..client import AsyncAdsunBot
+from ..models import BotAd
+
+
+async def send_ad(bot, chat_id: int, ads: AsyncAdsunBot, user_id: int, language: str = "") -> Optional[BotAd]:
+    """Fetches an Adsun ad and sends it. Returns the ad, or ``None`` when there was no ad."""
+    from aiogram.enums import ParseMode
+    from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+
+    ad = await ads.get_ad(user_id=user_id, language=language)
+    if ad is None:
+        return None
+    kb = InlineKeyboardMarkup(inline_keyboard=[[InlineKeyboardButton(text=t, url=u) for t, u in row] for row in ad.buttons()])
+    if ad.image_url:
+        await bot.send_photo(chat_id, photo=ad.image_url, caption=ad.text_html, parse_mode=ParseMode.HTML, reply_markup=kb, protect_content=True)
+    else:
+        await bot.send_message(chat_id, ad.text_html, parse_mode=ParseMode.HTML, reply_markup=kb, protect_content=True)
+    return ad

adsun/integrations/ptb.py

@@ -0,0 +1,20 @@
+"""python-telegram-bot (v20+) helper: ``await send_ad(context.bot, chat_id, ads, user_id, language)``."""
+from typing import Optional
+
+from ..client import AsyncAdsunBot
+from ..models import BotAd
+
+
+async def send_ad(bot, chat_id: int, ads: AsyncAdsunBot, user_id: int, language: str = "") -> Optional[BotAd]:
+    from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+    from telegram.constants import ParseMode
+
+    ad = await ads.get_ad(user_id=user_id, language=language)
+    if ad is None:
+        return None
+    kb = InlineKeyboardMarkup([[InlineKeyboardButton(t, url=u) for t, u in row] for row in ad.buttons()])
+    if ad.image_url:
+        await bot.send_photo(chat_id, photo=ad.image_url, caption=ad.text_html, parse_mode=ParseMode.HTML, reply_markup=kb, protect_content=True)
+    else:
+        await bot.send_message(chat_id, ad.text_html, parse_mode=ParseMode.HTML, reply_markup=kb, protect_content=True)
+    return ad

adsun/models.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class BotAd:
+    """Sponsored bot message returned by ``GET /advbot``.
+
+    Send it with ``parse_mode="HTML"`` and ``protect_content=True`` (ads must not be forwardable).
+    """
+
+    text_html: str
+    click_url: str
+    button_name: str
+    image_url: Optional[str] = None
+    button_reward_name: Optional[str] = None
+    reward_url: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BotAd":
+        return cls(
+            text_html=str(data.get("text_html") or ""),
+            click_url=str(data.get("click_url") or ""),
+            button_name=str(data.get("button_name") or "Open"),
+            image_url=data.get("image_url") or None,
+            button_reward_name=data.get("button_reward_name") or None,
+            reward_url=data.get("reward_url") or None,
+            raw=dict(data),
+        )
+
+    def buttons(self):
+        """Inline keyboard rows as ``[(text, url), ...]`` — framework independent."""
+        rows = [[(self.button_name, self.click_url)]]
+        if self.button_reward_name and self.reward_url:
+            rows.append([(self.button_reward_name, self.reward_url)])
+        return rows

adsun/reward.py

@@ -0,0 +1,54 @@
+"""Server-side helpers for the Adsun Reward URL callback.
+
+In the Adsun panel set the block's Reward URL, for example::
+
+    https://your-app.com/adsun/reward?userid=[userId]&block=[blockId]&secret=YOUR_LONG_RANDOM_SECRET
+
+Adsun calls it (HTTP GET) only after a server-verified full watch (Reward) or task completion (Task).
+``[userId]`` / ``[blockId]`` are replaced; ``user`` and ``block`` params are added too.
+Failed calls (5xx / network) are retried, so handle them idempotently. Never grant rewards from the
+client-side ``.then()`` alone — grant them here.
+"""
+import hmac
+from dataclasses import dataclass
+from typing import Mapping, Optional, Sequence, Union
+
+QueryValue = Union[str, Sequence[str]]
+
+
+def _first(q: Mapping[str, QueryValue], *names: str) -> str:
+    for n in names:
+        v = q.get(n)
+        if v is None:
+            continue
+        if not isinstance(v, str):
+            v = v[0] if len(v) else ""
+        if v:
+            return str(v)
+    return ""
+
+
+def verify_secret(received: Optional[str], expected: str) -> bool:
+    """Constant-time comparison of the ``secret`` you put in your Reward URL."""
+    if not expected or not received:
+        return False
+    return hmac.compare_digest(str(received).encode(), str(expected).encode())
+
+
+@dataclass(frozen=True)
+class RewardCallback:
+    user_id: str
+    block_id: str
+
+
+def parse_reward_callback(query: Mapping[str, QueryValue], secret: Optional[str] = None, secret_param: str = "secret") -> Optional[RewardCallback]:
+    """Parse a Reward URL request. Works with dicts from Flask, FastAPI, Django or ``urllib.parse.parse_qs``.
+
+    Returns ``None`` when the user id is missing or (if ``secret`` is given) the secret does not match.
+    """
+    if secret is not None and not verify_secret(_first(query, secret_param), secret):
+        return None
+    user = _first(query, "userid", "userId", "user", "user_id")
+    if not user.isdigit():
+        return None
+    return RewardCallback(user_id=user, block_id=_first(query, "block", "blockId", "blockid", "block_id"))

adsun-1.0.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: adsun
+Version: 1.0.0
+Summary: Official Adsun Python SDK: monetize Telegram bots with sponsored ads (aiogram, python-telegram-bot) and verify Telegram Mini App reward callbacks.
+Project-URL: Homepage, https://adsun.io
+Project-URL: Documentation, https://adsun.io/docs
+Project-URL: Source, https://github.com/adsun-io/adsun-sdk
+Project-URL: Issues, https://github.com/adsun-io/adsun-sdk/issues
+Project-URL: Bot monetization, https://adsun.io/telegram-bot-monetization
+Author-email: Adsun <support@adsun.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ad-network,adsgram,adsgram-alternative,adsun,aiogram,bot-monetization,python-telegram-bot,rewarded-ads,telegram,telegram-ad-network,telegram-ads,telegram-bot,telegram-mini-app,telegram-monetization,ton,usdt
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: aiogram
+Requires-Dist: aiogram>=3.0; extra == 'aiogram'
+Requires-Dist: aiohttp>=3.8; extra == 'aiogram'
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8; extra == 'async'
+Provides-Extra: ptb
+Requires-Dist: python-telegram-bot>=20.0; extra == 'ptb'
+Description-Content-Type: text/markdown
+
+# adsun — Telegram bot ads for Python
+
+Official [Adsun](https://adsun.io) Python SDK. **Monetize your Telegram bot** with sponsored messages and earn **USDT**,
+and verify **Telegram Mini App reward callbacks** on your server. Zero required dependencies; helpers for
+**aiogram 3** and **python-telegram-bot 20+**.
+
+```bash
+pip install adsun              # core (standard library only)
+pip install "adsun[aiogram]"   # + aiogram helper
+pip install "adsun[ptb]"       # + python-telegram-bot helper
+```
+
+1. Sign up at https://adsun.io/publishers, add your bot as a **Bot** platform and create a block.
+2. Copy your **account token** (Profile → Token) and the numeric **block id** (e.g. `50001`).
+
+## aiogram 3
+
+```python
+from aiogram.filters import Command
+from adsun import AsyncAdsunBot
+from adsun.integrations.aiogram import send_ad
+
+ads = AsyncAdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")
+
+@dp.message(Command("bonus"))
+async def bonus(message):
+    ad = await send_ad(message.bot, message.chat.id, ads, message.from_user.id, message.from_user.language_code or "en")
+    if ad is None:
+        await message.answer("No offer right now")
+```
+
+## python-telegram-bot
+
+```python
+from adsun import AsyncAdsunBot
+from adsun.integrations.ptb import send_ad
+
+ads = AsyncAdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")
+
+async def bonus(update, context):
+    u = update.effective_user
+    await send_ad(context.bot, update.effective_chat.id, ads, u.id, u.language_code or "en")
+```
+
+## Any framework (sync, no dependencies)
+
+```python
+from adsun import AdsunBot
+
+ads = AdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")
+ad = ads.get_ad(user_id=123456789, language="en")   # None = no ad right now
+if ad:
+    print(ad.text_html, ad.image_url, ad.buttons())  # [[(text, url)], [(reward_text, reward_url)]]
+```
+
+Send it yourself with `parse_mode="HTML"` and `protect_content=True` (ad messages must not be forwardable).
+
+Errors: `InvalidToken` (401), `BlockNotActive` (404), `BadRequest` (400), `AdsunError` (others / network).
+
+## Reward URL callback (Mini Apps and bots)
+
+Set the block's Reward URL in the panel:
+`https://your-app.com/adsun/reward?userid=[userId]&block=[blockId]&secret=LONG_RANDOM_SECRET`
+
+```python
+from adsun import parse_reward_callback
+
+@app.get("/adsun/reward")            # Flask / FastAPI / Django — any dict-like query works
+def reward():
+    cb = parse_reward_callback(request.args, secret=REWARD_SECRET)
+    if cb is None:
+        return "forbidden", 403
+    add_coins(cb.user_id)            # make this idempotent: Adsun retries on 5xx / network errors
+    return "ok"
+```
+
+## HTTP API (what the SDK calls)
+
+`GET https://api.adsun.io/advbot?tgid=<user id>&blockid=<number>&language=<code>&token=<account token>`
+→ `200 {text_html, click_url, button_name, image_url, button_reward_name, reward_url}` or `204` (no ad).
+
+Links: https://adsun.io/docs · https://adsun.io/telegram-bot-monetization · support@adsun.io ·
+[@ADSunSupport](https://t.me/ADSunSupport)
+
+MIT License. Adsun is not affiliated with Telegram.

adsun-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+adsun/__init__.py,sha256=YdrJFVD2i_ARFnVV5HqEZqXppixv3wT0BDS_zYANQrc,784
+adsun/client.py,sha256=aTX3AhJV889ZcbHMk0au6UXZ5Jp2QISsEqutFe_p1D8,4288
+adsun/errors.py,sha256=p6WOi9-Ct77DTpmMD10_eICeIHwa7Q94rMxKQT03Flc,845
+adsun/models.py,sha256=ONcJhmT_rxCFPt2QLecLo1Xk97-vGeCYagam98XkTuQ,1344
+adsun/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adsun/reward.py,sha256=Y8VUKAfuukzVaARAHLDV9raBjshOO3v9CLhAHiqo0UI,2050
+adsun/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adsun/integrations/aiogram.py,sha256=jQk_YzMJQ7ANmK5S773JgpYHbXVdwH2Mki_dRI_uYa8,1032
+adsun/integrations/ptb.py,sha256=4cz1Dl85pscUyEiL2CkZh6U9p62GF8RV1NJ1j3FthlY,942
+adsun-1.0.0.dist-info/METADATA,sha256=E-4u9mLLultio_G5jTZNOxXzfZ8gZNBhPCoed8JLy04,4657
+adsun-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+adsun-1.0.0.dist-info/licenses/LICENSE,sha256=qUqhUZUKNNG9Hfms_yxqBfjsgo7zuBnsjAt3pTe-OtU,1081
+adsun-1.0.0.dist-info/RECORD,,

adsun-1.0.0.dist-info/WHEEL

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

adsun-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adsun (https://adsun.io)
+
+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.