easyyad 1.0.0__py3-none-any.whl

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

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

@@ -0,0 +1,8 @@
+easyyad/__init__.py,sha256=F3_42uSeSNflZYvfrNVusWcfVvTjunC9alkyCqhABeY,902
+easyyad/client.py,sha256=s1nSS3A9_-JYh71TPWIWLaNhbVHuyPx2zW_pjQun9mU,10253
+easyyad/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+easyyad-1.0.0.dist-info/licenses/LICENSE,sha256=ORLBh_OfnGJ3FbasZf5ZzOEcAZLmtEeNro93R8Hz3Do,1095
+easyyad-1.0.0.dist-info/METADATA,sha256=oZI2HB2CdJncvj8xdZj95uwhhebrn2NfN_LgwHYl_3c,6335
+easyyad-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+easyyad-1.0.0.dist-info/top_level.txt,sha256=7fELba3xGTK25seb2CcJY-SOG5_jVU-vL_bgwLnmO8Y,8
+easyyad-1.0.0.dist-info/RECORD,,

easyyad-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

easyyad-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

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