hackbou-push-notification 0.1.0__py3-none-any.whl

hackbou_push_notification-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: hackbou-push-notification
+Version: 0.1.0
+Summary: Client Python / Django pour l'API Push Notification
+Author-email: hackbou <hackbou@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hardhacklife/push-notification-python-sdk
+Project-URL: Documentation, https://github.com/hardhacklife/push-notification-python-sdk#readme
+Project-URL: Repository, https://github.com/hardhacklife/push-notification-python-sdk
+Project-URL: Issues, https://github.com/hardhacklife/push-notification-python-sdk/issues
+Keywords: push-notification,push,notifications,django,fcm,apns
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing_extensions>=4.5; python_version < "3.11"
+Provides-Extra: django
+Requires-Dist: Django>=4.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# hackbou-push-notification
+
+Client Python / Django pour l’API **Push Notification**.
+
+Typage : PEP 561 (`py.typed`) + `TypedDict` pour les réponses.
+
+**Import :** `push_notification`  
+**Package PyPI :** `hackbou-push-notification`
+
+## Installation
+
+```bash
+pip install hackbou-push-notification
+
+# avec helpers Django
+pip install "hackbou-push-notification[django]"
+```
+
+## Usage Python
+
+```python
+from push_notification import PushNotificationClient, Device, NotificationCreateResult
+
+with PushNotificationClient(
+    api_key="pf_live_…",
+    base_url="https://push.example.com",
+) as push:
+    result: NotificationCreateResult = push.send_notification(
+        title="Nouveau cours",
+        body="Le support est disponible.",
+        user_ids=["student_123"],
+        data={"screen": "course"},
+    )
+    devices: list[Device] = push.list_devices(limit=50)
+    page = push.list_devices_page(q="expo", limit=25, offset=0)
+```
+
+## Usage Django
+
+`settings.py` :
+
+```python
+PUSH_NOTIFICATION_API_KEY = env("PUSH_NOTIFICATION_API_KEY")
+PUSH_NOTIFICATION_BASE_URL = env("PUSH_NOTIFICATION_BASE_URL", default="http://127.0.0.1:8787")
+PUSH_NOTIFICATION_TIMEOUT = 15
+```
+
+```python
+from push_notification.django import send_to_user, get_client
+
+send_to_user(
+    "student_123",
+    title="Nouveau cours",
+    body="Un support vient d’être publié.",
+    data={"course_id": "math_101"},
+)
+
+client = get_client()
+client.login_user("student_123", device_ids=["…"])
+client.set_user_tags("student_123", {"language": "fr"})
+```
+
+## API du client
+
+| Méthode | Endpoint |
+|---------|----------|
+| `register_device(platform=, token=)` | `POST /v1/devices` |
+| `list_devices(q=, limit=, offset=)` | `GET /v1/devices` → `list[Device]` |
+| `list_devices_page(…)` | idem → `{items,total,limit,offset,has_more}` |
+| `delete_device(id)` | `DELETE /v1/devices/{id}` |
+| `login` / `login_user` | `POST /v1/users/…/login` |
+| `set_tags` / `set_user_tags` | `PUT /v1/users/…/tags` |
+| `list_users` / `list_users_page` | `GET /v1/users` |
+| `send_notification(…)` | `POST /v1/notifications` |
+| `get_notification(id)` | `GET /v1/notifications/{id}` |
+| `list_notifications` / `_page` | `GET /v1/notifications` |
+| `health_live()` / `health_ready()` | healthchecks |
+
+Les listes acceptent l’enveloppe paginée **et** un ancien tableau brut (compat).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Licence
+
+Apache-2.0

hackbou_push_notification-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+push_notification/__init__.py,sha256=QgGvKMraJucRwl8mEibGu6K32ZOV24jPTQKJMOhCtwY,531
+push_notification/_parse.py,sha256=uWFd8pa1m5TkHmv4lQT2SqURAQDWbnAnWhIDJv1RAQ0,4145
+push_notification/client.py,sha256=GmatJAcpw3gcS-jesQLf9oBi6PUNo1y3RGjNjeCxSnM,15469
+push_notification/django.py,sha256=evaderE60-8Y4WsGuy3sksP4_r5DWTk15fOONaJmLX0,2920
+push_notification/exceptions.py,sha256=5Y1kpsM4W5Pf-isLdJYyy30K7SnGd_OT2mzWDWPAtMU,1437
+push_notification/models.py,sha256=PxsD4JvfEBag-di-99DQO9CK1KR0xG7HN4OcQzeXixw,1680
+push_notification/py.typed,sha256=rnYdiA2Ka23H1X4q_PHfFdD9_Z0QiH6cMspLo5NxsTw,21
+hackbou_push_notification-0.1.0.dist-info/METADATA,sha256=2AerHJDAqt7KGQGfODTCznwH3vs5yMA6t0r7Kvf0vhQ,3862
+hackbou_push_notification-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hackbou_push_notification-0.1.0.dist-info/top_level.txt,sha256=S0ykUv766Y1cni7vHhVKWj5BA3wk6qisEP_yQPrbbfY,18
+hackbou_push_notification-0.1.0.dist-info/RECORD,,

hackbou_push_notification-0.1.0.dist-info/WHEEL

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

hackbou_push_notification-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+push_notification

push_notification/__init__.py

@@ -0,0 +1,27 @@
+"""Client Python PushNotification."""
+
+from .client import PushNotificationClient
+from .exceptions import PushNotificationError
+from .models import (
+    DeliverySummary,
+    Device,
+    NotificationCreateResult,
+    NotificationDetail,
+    Page,
+    TagsResponse,
+    User,
+)
+
+__all__ = [
+    "PushNotificationClient",
+    "PushNotificationError",
+    "Device",
+    "User",
+    "Page",
+    "TagsResponse",
+    "DeliverySummary",
+    "NotificationCreateResult",
+    "NotificationDetail",
+    "__version__",
+]
+__version__ = "0.1.1"

push_notification/_parse.py

@@ -0,0 +1,127 @@
+"""Helpers de parsing défensifs — ne jamais faire confiance au JSON brut."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from .exceptions import PushNotificationError
+from .models import Device, JsonDict, Page, User
+
+
+def _require_mapping(value: Any, label: str) -> JsonDict:
+    if not isinstance(value, dict):
+        raise PushNotificationError(
+            f"Réponse {label} invalide (objet attendu)",
+            code="invalid_response",
+        )
+    return cast(JsonDict, value)
+
+
+def _require_str(obj: JsonDict, key: str, label: str) -> str:
+    val = obj.get(key)
+    if not isinstance(val, str) or not val:
+        raise PushNotificationError(
+            f"Réponse {label} sans champ '{key}'",
+            code="invalid_response",
+        )
+    return val
+
+
+def parse_device(raw: Any) -> Device:
+    obj = _require_mapping(raw, "appareil")
+    device: Device = {
+        "id": _require_str(obj, "id", "appareil"),
+        "platform": str(obj.get("platform") or "unknown"),
+        "status": str(obj.get("status") or "unknown"),
+        "user_id": obj.get("user_id") if isinstance(obj.get("user_id"), str) else None,
+        "created_at": str(obj.get("created_at") or ""),
+        "updated_at": str(obj.get("updated_at") or ""),
+    }
+    if "last_seen_at" in obj:
+        device["last_seen_at"] = (
+            obj["last_seen_at"] if isinstance(obj["last_seen_at"], str) else None
+        )
+    if "external_user_id" in obj:
+        device["external_user_id"] = (
+            obj["external_user_id"]
+            if isinstance(obj["external_user_id"], str)
+            else None
+        )
+    if isinstance(obj.get("token_preview"), str):
+        device["token_preview"] = obj["token_preview"]
+    if isinstance(obj.get("token_kind"), str):
+        device["token_kind"] = obj["token_kind"]
+    if isinstance(obj.get("push_ready"), bool):
+        device["push_ready"] = obj["push_ready"]
+    return device
+
+
+def parse_user(raw: Any) -> User:
+    obj = _require_mapping(raw, "utilisateur")
+    return {
+        "id": _require_str(obj, "id", "utilisateur"),
+        "external_id": _require_str(obj, "external_id", "utilisateur"),
+        "created_at": str(obj.get("created_at") or ""),
+        "updated_at": str(obj.get("updated_at") or ""),
+    }
+
+
+def parse_tags(raw: Any) -> dict[str, str]:
+    obj = _require_mapping(raw, "tags")
+    tags_raw = obj.get("tags", {})
+    if not isinstance(tags_raw, dict):
+        return {}
+    out: dict[str, str] = {}
+    for key, value in tags_raw.items():
+        if isinstance(key, str) and isinstance(value, str):
+            out[key] = value
+        elif isinstance(key, str) and value is not None:
+            out[key] = str(value)
+    return out
+
+
+def parse_page(raw: Any, *, item_label: str = "item") -> Page:
+    """
+    Accepte l’enveloppe Page moderne **ou** un tableau legacy.
+    Toujours retourne {items,total,limit,offset,has_more}.
+    """
+    if isinstance(raw, list):
+        items = list(raw)
+        return {
+            "items": items,
+            "total": len(items),
+            "limit": len(items) or 25,
+            "offset": 0,
+            "has_more": False,
+        }
+
+    obj = _require_mapping(raw, f"page {item_label}")
+    items_raw = obj.get("items")
+    if not isinstance(items_raw, list):
+        # Ancien shape accidentel : objet unique
+        raise PushNotificationError(
+            f"Réponse page {item_label} sans 'items'",
+            code="invalid_response",
+        )
+
+    total = obj.get("total")
+    limit = obj.get("limit")
+    offset = obj.get("offset")
+    has_more = obj.get("has_more")
+
+    total_i = int(total) if isinstance(total, (int, float)) else len(items_raw)
+    limit_i = int(limit) if isinstance(limit, (int, float)) else max(len(items_raw), 1)
+    offset_i = int(offset) if isinstance(offset, (int, float)) else 0
+    has_more_b = (
+        bool(has_more)
+        if isinstance(has_more, bool)
+        else offset_i + len(items_raw) < total_i
+    )
+
+    return {
+        "items": items_raw,
+        "total": total_i,
+        "limit": limit_i,
+        "offset": offset_i,
+        "has_more": has_more_b,
+    }

push_notification/client.py

@@ -0,0 +1,459 @@
+"""Client HTTP PushNotification — payloads alignés OneSignal, typage strict, BC préservée."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, cast
+from uuid import uuid4
+
+import httpx
+
+from ._parse import parse_device, parse_page, parse_tags, parse_user
+from .exceptions import PushNotificationError, raise_for_status
+from .models import (
+    Device,
+    JsonDict,
+    NotificationCreateResult,
+    NotificationDetail,
+    Page,
+    User,
+)
+
+
+def cast_notification_result(raw: JsonDict) -> NotificationCreateResult:
+    """Cast défensif : exige au minimum un id string si présent."""
+    if "id" in raw and not isinstance(raw.get("id"), str):
+        raise PushNotificationError(
+            "Réponse notification sans id valide",
+            code="invalid_response",
+        )
+    return cast(NotificationCreateResult, raw)
+
+
+class PushNotificationClient:
+    """
+    Client synchrone httpx.
+
+    Méthodes historiques conservées (`login`, `set_tags`, `list_devices` → list).
+    Alias documentés : `login_user`, `set_user_tags`.
+    Pagination : `list_*_page(...)` ou params `q`/`limit`/`offset` sur les listes.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "http://127.0.0.1:8787",
+        timeout: float = 15.0,
+        auth_scheme: str = "Bearer",
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise PushNotificationError("api_key is required", code="validation")
+        if not isinstance(base_url, str) or not base_url.strip():
+            raise PushNotificationError("base_url is required", code="validation")
+
+        self.api_key = api_key.strip()
+        self.base_url = base_url.strip().rstrip("/")
+        # OneSignal utilise `Key` ; PushNotification accepte Bearer et Key.
+        self.auth_scheme = auth_scheme
+        self._client = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> PushNotificationClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Authorization": f"{self.auth_scheme} {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if extra:
+            headers.update(dict(extra))
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: JsonDict | None = None,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, str | int] | None = None,
+    ) -> Any:
+        response = self._client.request(
+            method,
+            path,
+            json=json,
+            headers=self._headers(headers),
+            params=params,
+        )
+        raise_for_status(response)
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise PushNotificationError(
+                "Réponse JSON invalide",
+                status=response.status_code,
+                code="invalid_response",
+            ) from exc
+
+    @staticmethod
+    def _list_params(
+        *,
+        q: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        status: str | None = None,
+        platform: str | None = None,
+    ) -> dict[str, str | int]:
+        params: dict[str, str | int] = {}
+        if q is not None and q.strip():
+            params["q"] = q.strip()
+        if limit is not None:
+            params["limit"] = max(1, min(int(limit), 100))
+        if offset is not None:
+            params["offset"] = max(0, int(offset))
+        if status:
+            params["status"] = status
+        if platform:
+            params["platform"] = platform
+        return params
+
+    # --- Devices ---------------------------------------------------------
+
+    def register_device(self, *, platform: str, token: str) -> Device:
+        if platform not in ("android", "ios", "web"):
+            raise PushNotificationError(
+                "platform must be android | ios | web",
+                code="validation",
+            )
+        if not token or not str(token).strip():
+            raise PushNotificationError("token is required", code="validation")
+        raw = self._request(
+            "POST",
+            "/v1/devices",
+            json={"platform": platform, "token": str(token).strip()},
+        )
+        return parse_device(raw)
+
+    def list_devices_page(
+        self,
+        *,
+        q: str | None = None,
+        limit: int = 25,
+        offset: int = 0,
+        status: str | None = None,
+        platform: str | None = None,
+    ) -> Page:
+        raw = self._request(
+            "GET",
+            "/v1/devices",
+            params=self._list_params(
+                q=q, limit=limit, offset=offset, status=status, platform=platform
+            ),
+        )
+        page = parse_page(raw, item_label="devices")
+        return {
+            "items": [parse_device(item) for item in page["items"]],
+            "total": page["total"],
+            "limit": page["limit"],
+            "offset": page["offset"],
+            "has_more": page["has_more"],
+        }
+
+    def list_devices(
+        self,
+        *,
+        q: str | None = None,
+        limit: int = 25,
+        offset: int = 0,
+        status: str | None = None,
+        platform: str | None = None,
+    ) -> list[Device]:
+        """
+        Retourne les items de la page (BC historique).
+        Pour total / has_more, utilisez `list_devices_page`.
+        """
+        return self.list_devices_page(
+            q=q, limit=limit, offset=offset, status=status, platform=platform
+        )["items"]
+
+    def delete_device(self, device_id: str) -> Device:
+        if not device_id or not str(device_id).strip():
+            raise PushNotificationError("device_id is required", code="validation")
+        raw = self._request("DELETE", f"/v1/devices/{device_id}")
+        return parse_device(raw)
+
+    # --- Users -----------------------------------------------------------
+
+    def login(
+        self, external_id: str, device_ids: list[str] | None = None
+    ) -> User:
+        if not external_id or not str(external_id).strip():
+            raise PushNotificationError("external_id is required", code="validation")
+        raw = self._request(
+            "POST",
+            f"/v1/users/{str(external_id).strip()}/login",
+            json={"device_ids": list(device_ids or [])},
+        )
+        return parse_user(raw)
+
+    def login_user(
+        self, external_id: str, device_ids: list[str] | None = None
+    ) -> User:
+        """Alias documenté de `login`."""
+        return self.login(external_id, device_ids)
+
+    def set_tags(self, external_id: str, tags: dict[str, str]) -> dict[str, str]:
+        if not external_id or not str(external_id).strip():
+            raise PushNotificationError("external_id is required", code="validation")
+        if not isinstance(tags, dict):
+            raise PushNotificationError("tags must be a dict", code="validation")
+        raw = self._request(
+            "PUT",
+            f"/v1/users/{str(external_id).strip()}/tags",
+            json={"tags": tags},
+        )
+        return parse_tags(raw)
+
+    def set_user_tags(
+        self, external_id: str, tags: dict[str, str]
+    ) -> dict[str, str]:
+        """Alias documenté de `set_tags`."""
+        return self.set_tags(external_id, tags)
+
+    def list_users_page(
+        self,
+        *,
+        q: str | None = None,
+        limit: int = 25,
+        offset: int = 0,
+    ) -> Page:
+        raw = self._request(
+            "GET",
+            "/v1/users",
+            params=self._list_params(q=q, limit=limit, offset=offset),
+        )
+        page = parse_page(raw, item_label="users")
+        return {
+            "items": [parse_user(item) for item in page["items"]],
+            "total": page["total"],
+            "limit": page["limit"],
+            "offset": page["offset"],
+            "has_more": page["has_more"],
+        }
+
+    def list_users(
+        self,
+        *,
+        q: str | None = None,
+        limit: int = 25,
+        offset: int = 0,
+    ) -> list[User]:
+        return self.list_users_page(q=q, limit=limit, offset=offset)["items"]
+
+    # --- Notifications (OneSignal-compatible) ----------------------------
+
+    def create_notification(
+        self, payload: JsonDict
+    ) -> NotificationCreateResult:
+        """Envoi brut au format OneSignal / legacy PushNotification."""
+        if not isinstance(payload, dict):
+            raise PushNotificationError("payload must be a dict", code="validation")
+        headers: dict[str, str] = {}
+        idem = payload.get("idempotency_key") or payload.get("external_id")
+        if idem:
+            headers["Idempotency-Key"] = str(idem)
+        raw = self._request(
+            "POST",
+            "/v1/notifications",
+            json=payload,
+            headers=headers or None,
+        )
+        if not isinstance(raw, dict):
+            raise PushNotificationError(
+                "Réponse notification invalide",
+                code="invalid_response",
+            )
+        return cast_notification_result(raw)
+
+    def send_notification(
+        self,
+        *,
+        title: str = "",
+        body: str = "",
+        contents: dict[str, str] | None = None,
+        headings: dict[str, str] | None = None,
+        user_ids: list[str] | None = None,
+        include_external_user_ids: list[str] | None = None,
+        include_aliases: dict[str, list[str]] | None = None,
+        device_ids: list[str] | None = None,
+        include_subscription_ids: list[str] | None = None,
+        data: dict[str, Any] | None = None,
+        priority: str | int = "normal",
+        ttl_seconds: int | None = None,
+        ttl: int | None = None,
+        url: str | None = None,
+        name: str | None = None,
+        idempotency_key: str | None = None,
+        # legacy kwargs
+        target: dict[str, Any] | None = None,
+        notification: dict[str, Any] | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> NotificationCreateResult:
+        """
+        Envoie une notification.
+
+        Par défaut construit un payload **OneSignal**. Le chemin legacy
+        (`target` / `notification`) reste supporté.
+        """
+        if target is not None or notification is not None:
+            legacy: JsonDict = {
+                "target": target
+                or {
+                    "user_ids": user_ids or [],
+                    "device_ids": device_ids or [],
+                },
+                "notification": notification
+                or {
+                    "title": title,
+                    "body": body,
+                    "data": data or {},
+                },
+                "options": options
+                or {
+                    "priority": priority
+                    if isinstance(priority, str)
+                    else ("high" if int(priority) >= 10 else "normal"),
+                    "ttl_seconds": ttl_seconds if ttl_seconds is not None else ttl,
+                },
+            }
+            return self.create_notification(legacy)
+
+        contents_map = contents or {"en": body, "fr": body}
+        headings_map = headings or ({"en": title, "fr": title} if title else None)
+
+        aliases = include_aliases
+        if aliases is None and (user_ids or include_external_user_ids):
+            aliases = {
+                "external_id": list(
+                    dict.fromkeys(
+                        (user_ids or []) + (include_external_user_ids or [])
+                    )
+                )
+            }
+
+        subs = include_subscription_ids or device_ids
+
+        if not aliases and not subs:
+            raise PushNotificationError(
+                "include_aliases.external_id / user_ids or include_subscription_ids required",
+                code="validation",
+            )
+
+        if isinstance(priority, str):
+            os_priority = 10 if priority.lower() == "high" else 5
+        else:
+            os_priority = int(priority)
+
+        payload: JsonDict = {
+            "target_channel": "push",
+            "contents": contents_map,
+            "data": data or {},
+            "priority": os_priority,
+        }
+        if headings_map:
+            payload["headings"] = headings_map
+        if aliases:
+            payload["include_aliases"] = aliases
+        if include_external_user_ids and "include_aliases" not in payload:
+            payload["include_external_user_ids"] = include_external_user_ids
+        if subs:
+            payload["include_subscription_ids"] = subs
+        if ttl is not None:
+            payload["ttl"] = ttl
+        elif ttl_seconds is not None:
+            payload["ttl"] = ttl_seconds
+        if url:
+            payload["url"] = url
+        if name:
+            payload["name"] = name
+        payload["idempotency_key"] = (
+            idempotency_key if idempotency_key else str(uuid4())
+        )
+
+        return self.create_notification(payload)
+
+    def get_notification(self, notification_id: str) -> NotificationDetail:
+        if not notification_id or not str(notification_id).strip():
+            raise PushNotificationError("notification_id is required", code="validation")
+        raw = self._request("GET", f"/v1/notifications/{notification_id}")
+        if not isinstance(raw, dict):
+            raise PushNotificationError(
+                "Réponse notification invalide",
+                code="invalid_response",
+            )
+        return cast(NotificationDetail, raw)  # detail riche — champs NotRequired
+
+    def list_notifications_page(
+        self,
+        *,
+        q: str | None = None,
+        limit: int = 25,
+        offset: int = 0,
+        status: str | None = None,
+    ) -> Page:
+        raw = self._request(
+            "GET",
+            "/v1/notifications",
+            params=self._list_params(
+                q=q, limit=limit, offset=offset, status=status
+            ),
+        )
+        page = parse_page(raw, item_label="notifications")
+        items: list[NotificationDetail] = []
+        for item in page["items"]:
+            if isinstance(item, dict):
+                items.append(cast(NotificationDetail, item))
+        return {
+            "items": items,
+            "total": page["total"],
+            "limit": page["limit"],
+            "offset": page["offset"],
+            "has_more": page["has_more"],
+        }
+
+    def list_notifications(
+        self,
+        *,
+        q: str | None = None,
+        limit: int = 25,
+        offset: int = 0,
+        status: str | None = None,
+    ) -> list[NotificationDetail]:
+        return self.list_notifications_page(
+            q=q, limit=limit, offset=offset, status=status
+        )["items"]
+
+    # --- Health ----------------------------------------------------------
+
+    def health_live(self) -> bool:
+        try:
+            response = self._client.get("/health/live")
+            return response.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    def health_ready(self) -> bool:
+        try:
+            response = self._client.get("/health/ready")
+            return response.status_code == 200
+        except httpx.HTTPError:
+            return False

push_notification/django.py

@@ -0,0 +1,101 @@
+"""Intégration Django : settings + helper `get_client()`."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+from django.conf import settings
+
+from .client import PushNotificationClient
+from .exceptions import PushNotificationError
+from .models import NotificationCreateResult
+
+
+def _setting(name: str, default: Any = None) -> Any:
+    return getattr(settings, name, default)
+
+
+@lru_cache(maxsize=1)
+def get_client() -> PushNotificationClient:
+    """
+    Client singleton basé sur Django settings :
+
+    - PUSH_NOTIFICATION_API_KEY (requis)
+    - PUSH_NOTIFICATION_BASE_URL (défaut http://127.0.0.1:8787)
+    - PUSH_NOTIFICATION_TIMEOUT (défaut 15)
+    """
+    api_key = _setting("PUSH_NOTIFICATION_API_KEY") or _setting("PUSHFORGE_API_KEY")
+    if not api_key or not isinstance(api_key, str):
+        raise PushNotificationError(
+            "Définissez PUSH_NOTIFICATION_API_KEY dans vos settings Django",
+            code="missing_settings",
+        )
+
+    base_url = _setting(
+        "PUSH_NOTIFICATION_BASE_URL",
+        _setting("PUSHFORGE_BASE_URL", "http://127.0.0.1:8787"),
+    )
+    timeout_raw = _setting(
+        "PUSH_NOTIFICATION_TIMEOUT",
+        _setting("PUSHFORGE_TIMEOUT", 15),
+    )
+    try:
+        timeout = float(timeout_raw)
+    except (TypeError, ValueError) as exc:
+        raise PushNotificationError(
+            "PUSH_NOTIFICATION_TIMEOUT must be a number",
+            code="missing_settings",
+        ) from exc
+
+    return PushNotificationClient(
+        api_key=api_key,
+        base_url=str(base_url),
+        timeout=timeout,
+    )
+
+
+def clear_client_cache() -> None:
+    """Invalide le singleton (tests / reload settings)."""
+    get_client.cache_clear()
+
+
+def send_to_user(
+    external_id: str,
+    *,
+    title: str,
+    body: str,
+    data: dict[str, Any] | None = None,
+    priority: str = "normal",
+) -> NotificationCreateResult:
+    """Raccourci Django : envoi à un utilisateur externe."""
+    if not external_id or not str(external_id).strip():
+        raise PushNotificationError("external_id is required", code="validation")
+    return get_client().send_notification(
+        title=title,
+        body=body,
+        user_ids=[str(external_id).strip()],
+        data=data,
+        priority=priority,
+    )
+
+
+def send_to_users(
+    external_ids: list[str],
+    *,
+    title: str,
+    body: str,
+    data: dict[str, Any] | None = None,
+    priority: str = "normal",
+) -> NotificationCreateResult:
+    """Demande à PushNotification d'envoyer aux utilisateurs (external_id)."""
+    cleaned = [str(x).strip() for x in external_ids if x and str(x).strip()]
+    if not cleaned:
+        raise PushNotificationError("external_ids must not be empty", code="validation")
+    return get_client().send_notification(
+        title=title,
+        body=body,
+        user_ids=cleaned,
+        data=data,
+        priority=priority,
+    )

push_notification/exceptions.py

@@ -0,0 +1,55 @@
+"""Erreurs PushNotification."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class PushNotificationError(Exception):
+    """Erreur API ou client PushNotification."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"code={self.code}")
+        if self.status is not None:
+            parts.append(f"status={self.status}")
+        return " ".join(parts)
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Convertit une réponse HTTP d’erreur en PushNotificationError typée."""
+    if response.is_success:
+        return
+
+    code = "http_error"
+    message = response.reason_phrase or f"HTTP {response.status_code}"
+
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = None
+
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            if isinstance(err.get("code"), str):
+                code = err["code"]
+            if isinstance(err.get("message"), str):
+                message = err["message"]
+
+    raise PushNotificationError(message, status=response.status_code, code=code)

push_notification/models.py

@@ -0,0 +1,83 @@
+"""Modèles typés (TypedDict) — compatibles dict à l’exécution."""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+try:
+    from typing import NotRequired  # py3.11+
+except ImportError:  # pragma: no cover
+    from typing_extensions import NotRequired
+
+
+class Device(TypedDict):
+    id: str
+    platform: str
+    status: str
+    user_id: str | None
+    created_at: str
+    updated_at: str
+    last_seen_at: NotRequired[str | None]
+    external_user_id: NotRequired[str | None]
+    token_preview: NotRequired[str]
+    token_kind: NotRequired[str]
+    push_ready: NotRequired[bool]
+
+
+class User(TypedDict):
+    id: str
+    external_id: str
+    created_at: str
+    updated_at: str
+
+
+class TagsResponse(TypedDict):
+    tags: dict[str, str]
+
+
+class DeliverySummary(TypedDict, total=False):
+    expo_tokens: int
+    expo_sent: int
+    skipped_reason: str
+    error: str
+    expo_response: Any
+
+
+class NotificationCreateResult(TypedDict, total=False):
+    id: str
+    external_id: str | None
+    recipients: int
+    status: str
+    created_at: str
+    delivery: DeliverySummary
+    errors: Any
+    successful: int
+    failed: int
+    remaining: int
+
+
+class NotificationDetail(TypedDict, total=False):
+    id: str
+    status: str
+    target: dict[str, Any]
+    notification: dict[str, Any]
+    options: dict[str, Any]
+    successful: int
+    failed: int
+    remaining: int
+    queued_at: str | None
+    created_at: str
+    updated_at: str
+
+
+class Page(TypedDict):
+    """Enveloppe liste paginée (API stable). `items` typés au call-site."""
+
+    items: list[Any]
+    total: int
+    limit: int
+    offset: int
+    has_more: bool
+
+
+JsonDict = dict[str, Any]

push_notification/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561