easyyad 1.0.0__tar.gz

easyyad-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 N'GUESSAN JEAN STEPHANE ELIEL (EasyAd)
+
+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.

easyyad-1.0.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: easyyad
+Version: 1.0.0
+Summary: Show EasyAd ads in your Telegram bot and earn 50% of what advertisers pay.
+Author-email: EasyAd <support@easyyad.com>
+License: MIT
+Project-URL: Homepage, https://easyyad.com
+Project-URL: Documentation, https://easyyad.com/docs
+Keywords: telegram,telegram-bot,bot,ads,advertising,monetization,aiogram,easyad
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == "async"
+Dynamic: license-file
+
+# easyyad (Python)
+
+> Le paquet s'appelle **easyyad**, comme le domaine : `easyad` était déjà pris sur PyPI par une
+> bibliothèque Active Directory sans rapport avec nous.
+
+Affichez des publicités EasyAd dans votre bot Telegram et touchez **50 %** de ce que l'annonceur paie.
+
+> **English** — Show EasyAd ads in your Telegram bot and earn **50%** of what advertisers pay.
+> `pip install easyyad` (or `easyyad[async]` for aiogram), create `EasyAd(api_key=...)`, then call
+> `next_ad(...)` and `mark_shown(...)` after your bot has answered. Python 3.9+, no required dependency.
+> Full documentation: https://easyyad.com/docs
+
+```bash
+pip install easyyad            # client synchrone, sans dépendance
+pip install easyyad[async]     # ajoute httpx pour la version asynchrone
+```
+
+## En trois lignes
+
+```python
+import os
+from easyyad import EasyAd
+
+easyad = EasyAd(api_key=os.environ["EASYAD_API_KEY"])
+```
+
+Récupérez votre clé dans votre espace EasyAd, onglet **Bots** → votre bot → **Clé d'intégration**.
+Elle n'est affichée qu'une fois : nous n'en gardons qu'une empreinte, nous ne pouvons pas vous la
+redonner, seulement la remplacer.
+
+## Montrer une annonce
+
+```python
+ad = easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+
+if ad:
+    bot.send_message(
+        message.chat.id, ad.text,
+        parse_mode="HTML", reply_markup=ad.reply_markup,
+    )
+    easyad.mark_shown(ad.placement_id)        # sans cette ligne, vous n'êtes pas payé
+```
+
+`next_ad` renvoie `None` quand il n'y a rien à montrer, quand cet utilisateur a déjà vu son quota du
+jour, ou si EasyAd est momentanément injoignable. Dans les trois cas, votre bot continue comme si
+rien ne s'était passé : **une panne chez nous ne doit jamais casser votre bot.**
+
+### Le raccourci `serve()`
+
+```python
+easyad.serve(
+    user_id=message.from_user.id,
+    locale=message.from_user.language_code,
+    send=lambda ad: bot.send_message(
+        message.chat.id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup,
+    ),
+)
+```
+
+Demande, envoie, confirme. Si votre fonction `send` lève une exception, rien n'est confirmé — donc
+rien ne vous est compté, et l'annonceur n'est pas facturé.
+
+## Bots asynchrones (aiogram, python-telegram-bot)
+
+```python
+from easyyad import AsyncEasyAd
+
+easyad = AsyncEasyAd(api_key=os.environ["EASYAD_API_KEY"])
+
+@dp.message()
+async def handler(message: Message):
+    await repondre_normalement(message)
+
+    ad = await easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+    if ad:
+        await message.answer(ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+        await easyad.mark_shown(ad.placement_id)
+```
+
+`AsyncEasyAd` utilise `httpx` s'il est installé, sinon `aiohttp`. Si aucune des deux n'est présente,
+l'erreur arrive à la construction du client — pas au premier appel en production.
+
+## Avec une image
+
+```python
+if ad.image_url:
+    bot.send_photo(chat_id, ad.image_url, caption=ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+else:
+    bot.send_message(chat_id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+
+easyad.mark_shown(ad.placement_id)
+```
+
+## Vérifier l'intégration
+
+```python
+print(easyad.health())
+# {'ok': True, 'bot': {'name': 'Mon bot', 'status': 'approved', 'serving': True}, 'limits': {...}}
+```
+
+Appelez-le au démarrage : vous saurez tout de suite si la clé est bonne et si votre bot est approuvé.
+
+## Ce que l'on reçoit de vous
+
+`user_id` est **haché avant l'envoi** (SHA-256, tronqué à 32 caractères, salé avec votre clé). Nous ne
+voyons jamais l'identifiant Telegram de vos utilisateurs, et comme le sel est votre clé, deux
+partenaires ne peuvent pas recouper leurs audiences. Cette empreinte ne sert qu'à une chose : ne pas
+montrer trop d'annonces à la même personne.
+
+Vous pouvez choisir votre propre sel avec `user_salt=` — gardez-le stable, sinon le plafond de
+fréquence repart de zéro à chaque changement.
+
+## Options
+
+| Option | Défaut | À quoi ça sert |
+|---|---|---|
+| `api_key` | — | Votre clé secrète. Obligatoire. |
+| `base_url` | `https://api.easyyad.com/api/v1/sdk/bot` | Pour viser un environnement de test. |
+| `timeout` | `4.0` | Secondes. Au-delà, on renonce : votre bot doit rester rapide. |
+| `raise_on_error` | `False` | `True` pour gérer les exceptions vous-même. |
+| `user_salt` | la clé | Sel du hachage des identifiants. |
+
+La journalisation passe par le logger standard `easyyad` :
+
+```python
+import logging
+logging.getLogger("easyyad").setLevel(logging.DEBUG)
+```
+
+## Fréquence
+
+Deux limites, réglables dans votre espace EasyAd :
+
+- **annonces par utilisateur et par jour** (3 par défaut) ;
+- **délai minimum entre deux annonces** pour la même personne (60 minutes par défaut).
+
+Elles existent pour protéger votre audience : une conversation privée saturée de publicité fait
+partir vos utilisateurs, et c'est votre revenu qui disparaît avec eux. Vous pouvez les resserrer
+autant que vous voulez.
+
+## Rémunération
+
+Vous êtes payé sur les annonces **confirmées**. Une annonce demandée mais jamais confirmée est
+abandonnée au bout de 30 minutes et ne compte pour personne. Les gains apparaissent dans votre
+portefeuille après la période de vérification, puis deviennent retirables.
+
+Documentation complète : <https://www.easyyad.com/docs/bots>

easyyad-1.0.0/README.md

@@ -0,0 +1,147 @@
+# easyyad (Python)
+
+> Le paquet s'appelle **easyyad**, comme le domaine : `easyad` était déjà pris sur PyPI par une
+> bibliothèque Active Directory sans rapport avec nous.
+
+Affichez des publicités EasyAd dans votre bot Telegram et touchez **50 %** de ce que l'annonceur paie.
+
+> **English** — Show EasyAd ads in your Telegram bot and earn **50%** of what advertisers pay.
+> `pip install easyyad` (or `easyyad[async]` for aiogram), create `EasyAd(api_key=...)`, then call
+> `next_ad(...)` and `mark_shown(...)` after your bot has answered. Python 3.9+, no required dependency.
+> Full documentation: https://easyyad.com/docs
+
+```bash
+pip install easyyad            # client synchrone, sans dépendance
+pip install easyyad[async]     # ajoute httpx pour la version asynchrone
+```
+
+## En trois lignes
+
+```python
+import os
+from easyyad import EasyAd
+
+easyad = EasyAd(api_key=os.environ["EASYAD_API_KEY"])
+```
+
+Récupérez votre clé dans votre espace EasyAd, onglet **Bots** → votre bot → **Clé d'intégration**.
+Elle n'est affichée qu'une fois : nous n'en gardons qu'une empreinte, nous ne pouvons pas vous la
+redonner, seulement la remplacer.
+
+## Montrer une annonce
+
+```python
+ad = easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+
+if ad:
+    bot.send_message(
+        message.chat.id, ad.text,
+        parse_mode="HTML", reply_markup=ad.reply_markup,
+    )
+    easyad.mark_shown(ad.placement_id)        # sans cette ligne, vous n'êtes pas payé
+```
+
+`next_ad` renvoie `None` quand il n'y a rien à montrer, quand cet utilisateur a déjà vu son quota du
+jour, ou si EasyAd est momentanément injoignable. Dans les trois cas, votre bot continue comme si
+rien ne s'était passé : **une panne chez nous ne doit jamais casser votre bot.**
+
+### Le raccourci `serve()`
+
+```python
+easyad.serve(
+    user_id=message.from_user.id,
+    locale=message.from_user.language_code,
+    send=lambda ad: bot.send_message(
+        message.chat.id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup,
+    ),
+)
+```
+
+Demande, envoie, confirme. Si votre fonction `send` lève une exception, rien n'est confirmé — donc
+rien ne vous est compté, et l'annonceur n'est pas facturé.
+
+## Bots asynchrones (aiogram, python-telegram-bot)
+
+```python
+from easyyad import AsyncEasyAd
+
+easyad = AsyncEasyAd(api_key=os.environ["EASYAD_API_KEY"])
+
+@dp.message()
+async def handler(message: Message):
+    await repondre_normalement(message)
+
+    ad = await easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+    if ad:
+        await message.answer(ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+        await easyad.mark_shown(ad.placement_id)
+```
+
+`AsyncEasyAd` utilise `httpx` s'il est installé, sinon `aiohttp`. Si aucune des deux n'est présente,
+l'erreur arrive à la construction du client — pas au premier appel en production.
+
+## Avec une image
+
+```python
+if ad.image_url:
+    bot.send_photo(chat_id, ad.image_url, caption=ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+else:
+    bot.send_message(chat_id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+
+easyad.mark_shown(ad.placement_id)
+```
+
+## Vérifier l'intégration
+
+```python
+print(easyad.health())
+# {'ok': True, 'bot': {'name': 'Mon bot', 'status': 'approved', 'serving': True}, 'limits': {...}}
+```
+
+Appelez-le au démarrage : vous saurez tout de suite si la clé est bonne et si votre bot est approuvé.
+
+## Ce que l'on reçoit de vous
+
+`user_id` est **haché avant l'envoi** (SHA-256, tronqué à 32 caractères, salé avec votre clé). Nous ne
+voyons jamais l'identifiant Telegram de vos utilisateurs, et comme le sel est votre clé, deux
+partenaires ne peuvent pas recouper leurs audiences. Cette empreinte ne sert qu'à une chose : ne pas
+montrer trop d'annonces à la même personne.
+
+Vous pouvez choisir votre propre sel avec `user_salt=` — gardez-le stable, sinon le plafond de
+fréquence repart de zéro à chaque changement.
+
+## Options
+
+| Option | Défaut | À quoi ça sert |
+|---|---|---|
+| `api_key` | — | Votre clé secrète. Obligatoire. |
+| `base_url` | `https://api.easyyad.com/api/v1/sdk/bot` | Pour viser un environnement de test. |
+| `timeout` | `4.0` | Secondes. Au-delà, on renonce : votre bot doit rester rapide. |
+| `raise_on_error` | `False` | `True` pour gérer les exceptions vous-même. |
+| `user_salt` | la clé | Sel du hachage des identifiants. |
+
+La journalisation passe par le logger standard `easyyad` :
+
+```python
+import logging
+logging.getLogger("easyyad").setLevel(logging.DEBUG)
+```
+
+## Fréquence
+
+Deux limites, réglables dans votre espace EasyAd :
+
+- **annonces par utilisateur et par jour** (3 par défaut) ;
+- **délai minimum entre deux annonces** pour la même personne (60 minutes par défaut).
+
+Elles existent pour protéger votre audience : une conversation privée saturée de publicité fait
+partir vos utilisateurs, et c'est votre revenu qui disparaît avec eux. Vous pouvez les resserrer
+autant que vous voulez.
+
+## Rémunération
+
+Vous êtes payé sur les annonces **confirmées**. Une annonce demandée mais jamais confirmée est
+abandonnée au bout de 30 minutes et ne compte pour personne. Les gains apparaissent dans votre
+portefeuille après la période de vérification, puis deviennent retirables.
+
+Documentation complète : <https://www.easyyad.com/docs/bots>

easyyad-1.0.0/easyyad/__init__.py

@@ -0,0 +1,23 @@
+"""
+SDK EasyAd pour les bots — Python 3.9+.
+
+Deux appels suffisent : demander une annonce, puis confirmer qu'elle a bien été envoyée.
+Par défaut, rien ne lève d'exception : un réseau coupé ou un quota atteint renvoie simplement
+``None``, pour qu'une panne chez nous ne casse jamais votre bot.
+
+    from easyyad import EasyAd
+
+    easyad = EasyAd(api_key=os.environ["EASYAD_API_KEY"])
+
+    ad = easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+    if ad:
+        await bot.send_message(chat_id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+        easyad.mark_shown(ad.placement_id)
+
+Une variante asynchrone (``AsyncEasyAd``) est disponible pour aiogram et les bots async.
+"""
+
+from .client import AsyncEasyAd, EasyAd, EasyAdError, Ad, hash_user_id
+
+__all__ = ["EasyAd", "AsyncEasyAd", "EasyAdError", "Ad", "hash_user_id"]
+__version__ = "1.0.0"

easyyad-1.0.0/easyyad/client.py

@@ -0,0 +1,261 @@
+"""Client HTTP du SDK EasyAd : version synchrone et version asynchrone."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+DEFAULT_BASE = "https://api.easyyad.com/api/v1/sdk/bot"
+LOGGER = logging.getLogger("easyyad")
+
+
+class EasyAdError(Exception):
+    """Erreur renvoyée par EasyAd, ou impossibilité de le joindre."""
+
+    def __init__(self, message: str, *, status: int = 0, code: str = "unknown",
+                 retry_after_seconds: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retry_after_seconds = retry_after_seconds
+
+
+@dataclass(frozen=True)
+class Ad:
+    """Une annonce prête à envoyer."""
+
+    placement_id: str
+    text: str
+    reply_markup: Dict[str, Any]
+    parse_mode: str = "HTML"
+    image_url: Optional[str] = None
+    label: str = "#Ad #EasyAd"
+    confirm_within_seconds: int = 1800
+
+    @classmethod
+    def from_payload(cls, payload: Dict[str, Any]) -> "Ad":
+        return cls(
+            placement_id=payload["placement_id"],
+            text=payload["text"],
+            reply_markup=payload.get("reply_markup") or {},
+            parse_mode=payload.get("parse_mode") or "HTML",
+            image_url=payload.get("image_url"),
+            label=payload.get("label") or "#Ad #EasyAd",
+            confirm_within_seconds=int(payload.get("confirm_within_seconds") or 1800),
+        )
+
+
+def hash_user_id(user_id: Any, salt: str) -> str:
+    """Empreinte stable d'un identifiant : nous n'avons jamais besoin de l'identifiant réel."""
+    digest = hashlib.sha256(f"{salt}:{user_id}".encode("utf-8")).hexdigest()
+    return digest[:32]
+
+
+class _Base:
+    """Réglages et traitement des réponses, partagés par les deux clients."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE,
+        timeout: float = 4.0,
+        raise_on_error: bool = False,
+        user_salt: Optional[str] = None,
+    ) -> None:
+        if not api_key:
+            raise EasyAdError("Clé EasyAd manquante : passez api_key=…", code="missing_api_key")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.raise_on_error = raise_on_error
+        self.user_salt = user_salt or api_key
+
+    # -- préparation ----------------------------------------------------
+
+    def _headers(self, with_body: bool) -> Dict[str, str]:
+        headers = {"Authorization": f"Bearer {self.api_key}", "Accept": "application/json"}
+        if with_body:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def _next_payload(self, user_id: Any, locale: Optional[str]) -> Dict[str, Any]:
+        if user_id is None or user_id == "":
+            raise EasyAdError(
+                "user_id est requis : il sert à limiter la fréquence par utilisateur.",
+                code="missing_user_id",
+            )
+        payload: Dict[str, Any] = {"user_ref": hash_user_id(user_id, self.user_salt)}
+        if locale:
+            payload["locale"] = locale
+        return payload
+
+    # -- traitement des réponses ----------------------------------------
+
+    def _handle(self, status: int, text: str) -> Optional[Dict[str, Any]]:
+        body: Optional[Dict[str, Any]]
+        try:
+            body = json.loads(text) if text else None
+        except ValueError:
+            body = None
+
+        if status >= 400:
+            code = (body or {}).get("error") or f"http_{status}"
+            message = (body or {}).get("message") or f"EasyAd a répondu {status}."
+            error = EasyAdError(
+                message, status=status, code=code,
+                retry_after_seconds=(body or {}).get("retry_after_seconds"),
+            )
+            # Un quota atteint est une réponse normale, pas une panne.
+            if code == "frequency_capped":
+                LOGGER.debug("EasyAd : quota de fréquence atteint pour cet utilisateur.")
+                return None
+            if self.raise_on_error:
+                raise error
+            LOGGER.warning("EasyAd : %s (%s)", message, code)
+            return None
+
+        return body
+
+    def _failure(self, exc: BaseException) -> None:
+        timeout = isinstance(exc, (TimeoutError, urllib.error.URLError)) and "timed out" in str(exc).lower()
+        error = EasyAdError(
+            f"EasyAd n'a pas répondu en {self.timeout} s." if timeout else f"EasyAd est injoignable : {exc}",
+            code="timeout" if timeout else "network_error",
+        )
+        if self.raise_on_error:
+            raise error
+        LOGGER.warning("%s", error)
+        return None
+
+    @staticmethod
+    def _ad_from(body: Optional[Dict[str, Any]]) -> Optional[Ad]:
+        if not body or not body.get("ad"):
+            return None
+        return Ad.from_payload(body["ad"])
+
+
+class EasyAd(_Base):
+    """Client synchrone, sans dépendance : il n'utilise que la bibliothèque standard."""
+
+    def next_ad(self, *, user_id: Any, locale: Optional[str] = None) -> Optional[Ad]:
+        """Une annonce à montrer, ou ``None`` : rien à montrer, quota atteint, ou souci réseau."""
+        return self._ad_from(self._request("POST", "/ads/next", self._next_payload(user_id, locale)))
+
+    def mark_shown(self, placement_id: str) -> bool:
+        """À appeler **après** l'envoi : c'est cette confirmation qui déclenche votre rémunération."""
+        if not placement_id:
+            return False
+        quoted = urllib.parse.quote(placement_id, safe="")
+        body = self._request("POST", f"/ads/{quoted}/shown", {})
+        return bool(body and body.get("status") == "published")
+
+    def health(self) -> Optional[Dict[str, Any]]:
+        """Vérifie la clé et renvoie les réglages du bot. Pratique au démarrage."""
+        return self._request("GET", "/health", None)
+
+    def serve(self, *, user_id: Any, send: Callable[[Ad], Any], locale: Optional[str] = None) -> bool:
+        """
+        Raccourci : demande, envoie via ``send``, confirme.
+
+        Si ``send`` lève une exception, rien n'est confirmé — donc rien n'est facturé ni payé.
+        """
+        ad = self.next_ad(user_id=user_id, locale=locale)
+        if ad is None:
+            return False
+        send(ad)
+        return self.mark_shown(ad.placement_id)
+
+    def _request(self, method: str, path: str, payload: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        data = json.dumps(payload).encode("utf-8") if payload is not None else None
+        request = urllib.request.Request(
+            self.base_url + path, data=data, method=method, headers=self._headers(payload is not None)
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return self._handle(response.status, response.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:            # réponse reçue, mais code d'erreur
+            return self._handle(exc.code, exc.read().decode("utf-8", errors="replace"))
+        except EasyAdError:
+            raise
+        except Exception as exc:                          # réseau, DNS, TLS, délai dépassé
+            return self._failure(exc)
+
+
+class AsyncEasyAd(_Base):
+    """
+    Client asynchrone pour aiogram, python-telegram-bot et autres bots async.
+
+    Nécessite ``httpx`` ou ``aiohttp``. Si aucune des deux n'est installée, l'erreur le dit
+    clairement au démarrage plutôt qu'au premier appel en production.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client_factory = self._detect_backend()
+
+    async def next_ad(self, *, user_id: Any, locale: Optional[str] = None) -> Optional[Ad]:
+        return self._ad_from(await self._request("POST", "/ads/next", self._next_payload(user_id, locale)))
+
+    async def mark_shown(self, placement_id: str) -> bool:
+        if not placement_id:
+            return False
+        quoted = urllib.parse.quote(placement_id, safe="")
+        body = await self._request("POST", f"/ads/{quoted}/shown", {})
+        return bool(body and body.get("status") == "published")
+
+    async def health(self) -> Optional[Dict[str, Any]]:
+        return await self._request("GET", "/health", None)
+
+    async def serve(
+        self, *, user_id: Any, send: Callable[[Ad], Awaitable[Any]], locale: Optional[str] = None
+    ) -> bool:
+        ad = await self.next_ad(user_id=user_id, locale=locale)
+        if ad is None:
+            return False
+        await send(ad)
+        return await self.mark_shown(ad.placement_id)
+
+    def _detect_backend(self) -> str:
+        try:
+            import httpx  # noqa: F401
+            return "httpx"
+        except ImportError:
+            pass
+        try:
+            import aiohttp  # noqa: F401
+            return "aiohttp"
+        except ImportError as exc:
+            raise EasyAdError(
+                "AsyncEasyAd a besoin de httpx ou aiohttp : pip install httpx",
+                code="missing_dependency",
+            ) from exc
+
+    async def _request(self, method: str, path: str, payload: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        url = self.base_url + path
+        headers = self._headers(payload is not None)
+
+        try:
+            if self._client_factory == "httpx":
+                import httpx
+
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    response = await client.request(method, url, json=payload, headers=headers)
+                    return self._handle(response.status_code, response.text)
+
+            import aiohttp
+
+            timeout = aiohttp.ClientTimeout(total=self.timeout)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.request(method, url, json=payload, headers=headers) as response:
+                    return self._handle(response.status, await response.text())
+        except EasyAdError:
+            raise
+        except Exception as exc:
+            return self._failure(exc)

easyyad-1.0.0/easyyad.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: easyyad
+Version: 1.0.0
+Summary: Show EasyAd ads in your Telegram bot and earn 50% of what advertisers pay.
+Author-email: EasyAd <support@easyyad.com>
+License: MIT
+Project-URL: Homepage, https://easyyad.com
+Project-URL: Documentation, https://easyyad.com/docs
+Keywords: telegram,telegram-bot,bot,ads,advertising,monetization,aiogram,easyad
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == "async"
+Dynamic: license-file
+
+# easyyad (Python)
+
+> Le paquet s'appelle **easyyad**, comme le domaine : `easyad` était déjà pris sur PyPI par une
+> bibliothèque Active Directory sans rapport avec nous.
+
+Affichez des publicités EasyAd dans votre bot Telegram et touchez **50 %** de ce que l'annonceur paie.
+
+> **English** — Show EasyAd ads in your Telegram bot and earn **50%** of what advertisers pay.
+> `pip install easyyad` (or `easyyad[async]` for aiogram), create `EasyAd(api_key=...)`, then call
+> `next_ad(...)` and `mark_shown(...)` after your bot has answered. Python 3.9+, no required dependency.
+> Full documentation: https://easyyad.com/docs
+
+```bash
+pip install easyyad            # client synchrone, sans dépendance
+pip install easyyad[async]     # ajoute httpx pour la version asynchrone
+```
+
+## En trois lignes
+
+```python
+import os
+from easyyad import EasyAd
+
+easyad = EasyAd(api_key=os.environ["EASYAD_API_KEY"])
+```
+
+Récupérez votre clé dans votre espace EasyAd, onglet **Bots** → votre bot → **Clé d'intégration**.
+Elle n'est affichée qu'une fois : nous n'en gardons qu'une empreinte, nous ne pouvons pas vous la
+redonner, seulement la remplacer.
+
+## Montrer une annonce
+
+```python
+ad = easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+
+if ad:
+    bot.send_message(
+        message.chat.id, ad.text,
+        parse_mode="HTML", reply_markup=ad.reply_markup,
+    )
+    easyad.mark_shown(ad.placement_id)        # sans cette ligne, vous n'êtes pas payé
+```
+
+`next_ad` renvoie `None` quand il n'y a rien à montrer, quand cet utilisateur a déjà vu son quota du
+jour, ou si EasyAd est momentanément injoignable. Dans les trois cas, votre bot continue comme si
+rien ne s'était passé : **une panne chez nous ne doit jamais casser votre bot.**
+
+### Le raccourci `serve()`
+
+```python
+easyad.serve(
+    user_id=message.from_user.id,
+    locale=message.from_user.language_code,
+    send=lambda ad: bot.send_message(
+        message.chat.id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup,
+    ),
+)
+```
+
+Demande, envoie, confirme. Si votre fonction `send` lève une exception, rien n'est confirmé — donc
+rien ne vous est compté, et l'annonceur n'est pas facturé.
+
+## Bots asynchrones (aiogram, python-telegram-bot)
+
+```python
+from easyyad import AsyncEasyAd
+
+easyad = AsyncEasyAd(api_key=os.environ["EASYAD_API_KEY"])
+
+@dp.message()
+async def handler(message: Message):
+    await repondre_normalement(message)
+
+    ad = await easyad.next_ad(user_id=message.from_user.id, locale=message.from_user.language_code)
+    if ad:
+        await message.answer(ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+        await easyad.mark_shown(ad.placement_id)
+```
+
+`AsyncEasyAd` utilise `httpx` s'il est installé, sinon `aiohttp`. Si aucune des deux n'est présente,
+l'erreur arrive à la construction du client — pas au premier appel en production.
+
+## Avec une image
+
+```python
+if ad.image_url:
+    bot.send_photo(chat_id, ad.image_url, caption=ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+else:
+    bot.send_message(chat_id, ad.text, parse_mode="HTML", reply_markup=ad.reply_markup)
+
+easyad.mark_shown(ad.placement_id)
+```
+
+## Vérifier l'intégration
+
+```python
+print(easyad.health())
+# {'ok': True, 'bot': {'name': 'Mon bot', 'status': 'approved', 'serving': True}, 'limits': {...}}
+```
+
+Appelez-le au démarrage : vous saurez tout de suite si la clé est bonne et si votre bot est approuvé.
+
+## Ce que l'on reçoit de vous
+
+`user_id` est **haché avant l'envoi** (SHA-256, tronqué à 32 caractères, salé avec votre clé). Nous ne
+voyons jamais l'identifiant Telegram de vos utilisateurs, et comme le sel est votre clé, deux
+partenaires ne peuvent pas recouper leurs audiences. Cette empreinte ne sert qu'à une chose : ne pas
+montrer trop d'annonces à la même personne.
+
+Vous pouvez choisir votre propre sel avec `user_salt=` — gardez-le stable, sinon le plafond de
+fréquence repart de zéro à chaque changement.
+
+## Options
+
+| Option | Défaut | À quoi ça sert |
+|---|---|---|
+| `api_key` | — | Votre clé secrète. Obligatoire. |
+| `base_url` | `https://api.easyyad.com/api/v1/sdk/bot` | Pour viser un environnement de test. |
+| `timeout` | `4.0` | Secondes. Au-delà, on renonce : votre bot doit rester rapide. |
+| `raise_on_error` | `False` | `True` pour gérer les exceptions vous-même. |
+| `user_salt` | la clé | Sel du hachage des identifiants. |
+
+La journalisation passe par le logger standard `easyyad` :
+
+```python
+import logging
+logging.getLogger("easyyad").setLevel(logging.DEBUG)
+```
+
+## Fréquence
+
+Deux limites, réglables dans votre espace EasyAd :
+
+- **annonces par utilisateur et par jour** (3 par défaut) ;
+- **délai minimum entre deux annonces** pour la même personne (60 minutes par défaut).
+
+Elles existent pour protéger votre audience : une conversation privée saturée de publicité fait
+partir vos utilisateurs, et c'est votre revenu qui disparaît avec eux. Vous pouvez les resserrer
+autant que vous voulez.
+
+## Rémunération
+
+Vous êtes payé sur les annonces **confirmées**. Une annonce demandée mais jamais confirmée est
+abandonnée au bout de 30 minutes et ne compte pour personne. Les gains apparaissent dans votre
+portefeuille après la période de vérification, puis deviennent retirables.
+
+Documentation complète : <https://www.easyyad.com/docs/bots>

easyyad-1.0.0/easyyad.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+easyyad/__init__.py
+easyyad/client.py
+easyyad/py.typed
+easyyad.egg-info/PKG-INFO
+easyyad.egg-info/SOURCES.txt
+easyyad.egg-info/dependency_links.txt
+easyyad.egg-info/requires.txt
+easyyad.egg-info/top_level.txt
+tests/test_client.py

easyyad-1.0.0/easyyad.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

easyyad-1.0.0/easyyad.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[async]
+httpx>=0.27

easyyad-1.0.0/easyyad.egg-info/top_level.txt

@@ -0,0 +1 @@
+easyyad

easyyad-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "easyyad"
+version = "1.0.0"
+description = "Show EasyAd ads in your Telegram bot and earn 50% of what advertisers pay."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "EasyAd", email = "support@easyyad.com" }]
+keywords = ["telegram", "telegram-bot", "bot", "ads", "advertising", "monetization", "aiogram", "easyad"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Framework :: AsyncIO",
+  "Topic :: Communications :: Chat",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+async = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://easyyad.com"
+Documentation = "https://easyyad.com/docs"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["easyyad"]
+license-files = ["LICENSE"]
+
+[tool.setuptools.package-data]
+easyyad = ["py.typed"]

easyyad-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

easyyad-1.0.0/tests/test_client.py

@@ -0,0 +1,217 @@
+"""Tests du SDK Python : aucun appel réseau réel, le transport est remplacé."""
+
+import json
+import sys
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from easyyad import Ad, EasyAd, EasyAdError, hash_user_id  # noqa: E402
+
+AD_PAYLOAD = {
+    "ad": {
+        "placement_id": "pl_abc1234567",
+        "text": "<b>Offre</b>\n\nTexte\n\n#Ad #EasyAd",
+        "parse_mode": "HTML",
+        "reply_markup": {"inline_keyboard": [[{"text": "Découvrir", "url": "https://go.easyyad.com/r/xyz"}]]},
+        "image_url": None,
+        "label": "#Ad #EasyAd",
+        "confirm_within_seconds": 1800,
+    }
+}
+
+
+class FakeResponse:
+    def __init__(self, status, body):
+        self.status = status
+        self._body = json.dumps(body).encode() if body is not None else b""
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def patch_urlopen(responses):
+    """Remplace urlopen ; `responses` est une liste de (status, body) ou d'exceptions."""
+    calls = []
+    queue = list(responses)
+
+    def fake(request, timeout=None):
+        calls.append({
+            "url": request.full_url,
+            "method": request.method,
+            "headers": dict(request.headers),
+            "body": json.loads(request.data) if request.data else None,
+            "timeout": timeout,
+        })
+        item = queue.pop(0) if len(queue) > 1 else queue[0]
+        if isinstance(item, BaseException):
+            raise item
+        return FakeResponse(*item)
+
+    return mock.patch("urllib.request.urlopen", side_effect=fake), calls
+
+
+class TestKeyAndHashing(unittest.TestCase):
+    def test_la_cle_est_obligatoire(self):
+        with self.assertRaises(EasyAdError):
+            EasyAd(api_key="")
+
+    def test_l_identifiant_ne_quitte_jamais_le_bot_en_clair(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch:
+            EasyAd(api_key="ea_live_test").next_ad(user_id=123456789)
+
+        sent = calls[0]["body"]["user_ref"]
+        self.assertEqual(len(sent), 32)
+        self.assertNotIn("123456789", sent)
+
+    def test_la_meme_personne_donne_la_meme_empreinte(self):
+        self.assertEqual(hash_user_id(7, "sel"), hash_user_id(7, "sel"))
+        self.assertNotEqual(hash_user_id(7, "sel-a"), hash_user_id(7, "sel-b"))
+
+
+class TestNextAd(unittest.TestCase):
+    def test_une_annonce_est_renvoyee_en_objet(self):
+        patch, _ = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch:
+            ad = EasyAd(api_key="k").next_ad(user_id=1, locale="fr")
+
+        self.assertIsInstance(ad, Ad)
+        self.assertEqual(ad.placement_id, "pl_abc1234567")
+        self.assertEqual(ad.parse_mode, "HTML")
+        self.assertIsNone(ad.image_url)
+
+    def test_la_langue_est_transmise(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch:
+            EasyAd(api_key="k").next_ad(user_id=1, locale="fr")
+        self.assertEqual(calls[0]["body"]["locale"], "fr")
+
+    def test_sans_langue_le_champ_est_absent(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch:
+            EasyAd(api_key="k").next_ad(user_id=1)
+        self.assertNotIn("locale", calls[0]["body"])
+
+    def test_user_id_est_exige(self):
+        patch, _ = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch, self.assertRaises(EasyAdError):
+            EasyAd(api_key="k").next_ad(user_id=None)
+
+    def test_aucune_annonce_renvoie_none(self):
+        patch, _ = patch_urlopen([(200, {"ad": None, "reason": "no_fill"})])
+        with patch:
+            self.assertIsNone(EasyAd(api_key="k").next_ad(user_id=1))
+
+    def test_la_cle_part_dans_l_entete_authorization(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch:
+            EasyAd(api_key="ea_live_secret").next_ad(user_id=1)
+        self.assertEqual(calls[0]["headers"]["Authorization"], "Bearer ea_live_secret")
+
+    def test_l_adresse_de_base_peut_etre_remplacee(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD)])
+        with patch:
+            EasyAd(api_key="k", base_url="https://api.test.local/sdk/bot/").next_ad(user_id=1)
+        self.assertEqual(calls[0]["url"], "https://api.test.local/sdk/bot/ads/next")
+
+
+class TestErrors(unittest.TestCase):
+    def test_un_quota_atteint_renvoie_none_sans_exception(self):
+        err = urllib.error.HTTPError(
+            "u", 429, "Too Many", {},
+            __import__("io").BytesIO(json.dumps({"error": "frequency_capped", "message": "quota"}).encode()),
+        )
+        patch, _ = patch_urlopen([err])
+        with patch:
+            self.assertIsNone(EasyAd(api_key="k").next_ad(user_id=1))
+
+    def test_une_panne_reseau_ne_casse_pas_le_bot(self):
+        patch, _ = patch_urlopen([urllib.error.URLError("ECONNREFUSED")])
+        with patch:
+            self.assertIsNone(EasyAd(api_key="k").next_ad(user_id=1))
+
+    def test_raise_on_error_laisse_l_appelant_decider(self):
+        patch, _ = patch_urlopen([urllib.error.URLError("ECONNREFUSED")])
+        with patch, self.assertRaises(EasyAdError):
+            EasyAd(api_key="k", raise_on_error=True).next_ad(user_id=1)
+
+    def test_une_cle_invalide_est_signalee(self):
+        err = urllib.error.HTTPError(
+            "u", 401, "Unauthorized", {},
+            __import__("io").BytesIO(json.dumps({"error": "invalid_api_key", "message": "Clé inconnue"}).encode()),
+        )
+        patch, _ = patch_urlopen([err])
+        with patch, self.assertRaises(EasyAdError) as ctx:
+            EasyAd(api_key="mauvaise", raise_on_error=True).next_ad(user_id=1)
+
+        self.assertEqual(ctx.exception.code, "invalid_api_key")
+        self.assertEqual(ctx.exception.status, 401)
+
+
+class TestMarkShown(unittest.TestCase):
+    def test_la_confirmation_appelle_la_bonne_adresse(self):
+        patch, calls = patch_urlopen([(200, {"status": "published"})])
+        with patch:
+            self.assertTrue(EasyAd(api_key="k").mark_shown("pl_abc1234567"))
+        self.assertTrue(calls[0]["url"].endswith("/ads/pl_abc1234567/shown"))
+
+    def test_confirmer_sans_identifiant_ne_fait_rien(self):
+        patch, calls = patch_urlopen([(200, {})])
+        with patch:
+            self.assertFalse(EasyAd(api_key="k").mark_shown(""))
+        self.assertEqual(calls, [])
+
+
+class TestServe(unittest.TestCase):
+    def test_serve_enchaine_demande_envoi_et_confirmation(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD), (200, {"status": "published"})])
+        sent = []
+        with patch:
+            done = EasyAd(api_key="k").serve(user_id=5, send=lambda ad: sent.append(ad.placement_id))
+
+        self.assertTrue(done)
+        self.assertEqual(sent, ["pl_abc1234567"])
+        self.assertEqual(len(calls), 2)
+
+    def test_si_l_envoi_echoue_rien_n_est_confirme(self):
+        patch, calls = patch_urlopen([(200, AD_PAYLOAD)])
+
+        def boom(ad):
+            raise RuntimeError("Telegram 403")
+
+        with patch, self.assertRaises(RuntimeError):
+            EasyAd(api_key="k").serve(user_id=5, send=boom)
+
+        self.assertEqual(len(calls), 1)      # la confirmation n'est jamais partie
+
+    def test_serve_sans_annonce_ne_rappelle_pas_send(self):
+        patch, _ = patch_urlopen([(200, {"ad": None})])
+        called = []
+        with patch:
+            done = EasyAd(api_key="k").serve(user_id=5, send=lambda ad: called.append(1))
+        self.assertFalse(done)
+        self.assertEqual(called, [])
+
+
+class TestHealth(unittest.TestCase):
+    def test_health_renvoie_la_reponse_du_serveur(self):
+        patch, calls = patch_urlopen([(200, {"ok": True, "bot": {"name": "Mon bot"}})])
+        with patch:
+            body = EasyAd(api_key="k").health()
+        self.assertEqual(body["bot"]["name"], "Mon bot")
+        self.assertEqual(calls[0]["method"], "GET")
+        self.assertIsNone(calls[0]["body"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)