nitroping 0.1.3__py3-none-any.whl

nitroping/__init__.py

@@ -0,0 +1,75 @@
+"""Zero-dependency Python SDK for `nitroping <https://nitroping.dev>`_.
+
+Send push notifications, register devices, verify webhook signatures.
+
+Quick start::
+
+    from nitroping import Nitroping
+
+    np = Nitroping(api_key="np_live_...")
+    np.notifications.send(
+        title="Order #4129 shipped",
+        body="On its way",
+        target={"all": True},
+    )
+
+See the project README for the full API reference, framework recipes,
+and error table.
+"""
+
+from __future__ import annotations
+
+from ._client import AsyncNitroping, Nitroping
+from ._devices import DevicesClient
+from ._http import DEFAULT_BASE_URL, HttpClient
+from ._notifications import NotificationsClient
+from .errors import (
+    ApiError,
+    InvalidSignatureError,
+    MissingSignatureHeaderError,
+    NetworkError,
+    NitropingError,
+    TimestampOutOfRangeError,
+)
+from .types import (
+    DeactivateDeviceResult,
+    NotificationAction,
+    NotificationResult,
+    NotificationTarget,
+    Platform,
+    RegisterDeviceResult,
+    SendOptions,
+    TargetAll,
+    TargetDeviceIds,
+    TargetUserIds,
+    WebhookEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "ApiError",
+    "AsyncNitroping",
+    "DeactivateDeviceResult",
+    "DevicesClient",
+    "HttpClient",
+    "InvalidSignatureError",
+    "MissingSignatureHeaderError",
+    "NetworkError",
+    "Nitroping",
+    "NitropingError",
+    "NotificationAction",
+    "NotificationResult",
+    "NotificationTarget",
+    "NotificationsClient",
+    "Platform",
+    "RegisterDeviceResult",
+    "SendOptions",
+    "TargetAll",
+    "TargetDeviceIds",
+    "TargetUserIds",
+    "TimestampOutOfRangeError",
+    "WebhookEvent",
+    "__version__",
+]

nitroping/_client.py

@@ -0,0 +1,204 @@
+"""Top-level SDK entry points: :class:`Nitroping` and :class:`AsyncNitroping`."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+from ._devices import DevicesClient
+from ._http import DEFAULT_BASE_URL, HttpClient
+from ._notifications import NotificationsClient
+from .errors import NitropingError
+from .types import (
+    DeactivateDeviceResult,
+    NotificationAction,
+    NotificationResult,
+    NotificationTarget,
+    Platform,
+    RegisterDeviceResult,
+)
+
+
+class Nitroping:
+    """Synchronous server-side SDK client.
+
+    Example::
+
+        from nitroping import Nitroping
+
+        np = Nitroping(api_key="np_live_...")
+        result = np.notifications.send(
+            title="Order #4129 shipped",
+            body="On its way",
+            target={"all": True},
+        )
+        print(result["id"], result["status"])
+    """
+
+    #: ``notifications`` resource — send, get.
+    notifications: NotificationsClient
+    #: ``devices`` resource — register, deactivate.
+    devices: DevicesClient
+    #: Internal HTTP client. Exposed for advanced use (custom requests).
+    http: HttpClient
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else os.environ.get(
+            "NITROPING_API_KEY"
+        )
+        if not resolved_key:
+            raise NitropingError(
+                "api_key is required. Pass it to Nitroping(api_key=...) or set "
+                "the NITROPING_API_KEY environment variable.",
+                code="invalid_argument",
+            )
+        self.http = HttpClient(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            user_agent=user_agent,
+        )
+        self.notifications = NotificationsClient(self.http)
+        self.devices = DevicesClient(self.http)
+
+
+class _AsyncNotificationsClient:
+    """Awaitable façade over :class:`NotificationsClient`.
+
+    Each call shells out to the sync client on the default thread pool
+    via :func:`asyncio.get_running_loop().run_in_executor`. This is a
+    pragmatic best-effort — for high-throughput async fanout, run the
+    underlying HTTP calls in a real async client (``httpx``, ``aiohttp``)
+    and skip this wrapper.
+    """
+
+    def __init__(self, inner: NotificationsClient) -> None:
+        self._inner = inner
+
+    async def send(
+        self,
+        *,
+        target: NotificationTarget,
+        title: str | None = None,
+        body: str | None = None,
+        template: str | None = None,
+        vars: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        icon: str | None = None,
+        image: str | None = None,
+        click_action: str | None = None,
+        deep_link: str | None = None,
+        actions: list[NotificationAction] | None = None,
+        scheduled_at: str | None = None,
+        expires_at: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> NotificationResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._inner.send(
+                target=target,
+                title=title,
+                body=body,
+                template=template,
+                vars=vars,
+                data=data,
+                icon=icon,
+                image=image,
+                click_action=click_action,
+                deep_link=deep_link,
+                actions=actions,
+                scheduled_at=scheduled_at,
+                expires_at=expires_at,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    async def get(self, notification_id: str) -> dict[str, Any]:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, self._inner.get, notification_id
+        )
+
+
+class _AsyncDevicesClient:
+    """Awaitable façade over :class:`DevicesClient`."""
+
+    def __init__(self, inner: DevicesClient) -> None:
+        self._inner = inner
+
+    async def register(
+        self,
+        *,
+        platform: Platform,
+        token: str,
+        user_id: str | None = None,
+        web_push_p256dh: str | None = None,
+        web_push_auth: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RegisterDeviceResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._inner.register(
+                platform=platform,
+                token=token,
+                user_id=user_id,
+                web_push_p256dh=web_push_p256dh,
+                web_push_auth=web_push_auth,
+                metadata=metadata,
+            ),
+        )
+
+    async def deactivate(self, device_id: str) -> DeactivateDeviceResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, self._inner.deactivate, device_id
+        )
+
+
+class AsyncNitroping:
+    """Async server-side SDK client.
+
+    Wraps the sync :class:`Nitroping` client and runs each HTTP call on
+    the default thread pool. Convenient when you want to ``await`` an
+    SDK method from inside an async framework (FastAPI, aiohttp,
+    Starlette) without pulling in a separate async HTTP dependency.
+
+    For real-world high-fanout (thousands of concurrent sends) prefer a
+    purpose-built async HTTP client and call the API directly — this
+    wrapper still bottlenecks on the executor pool size.
+    """
+
+    notifications: _AsyncNotificationsClient
+    devices: _AsyncDevicesClient
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        self._sync = Nitroping(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            user_agent=user_agent,
+        )
+        self.notifications = _AsyncNotificationsClient(self._sync.notifications)
+        self.devices = _AsyncDevicesClient(self._sync.devices)
+
+    @property
+    def http(self) -> HttpClient:
+        """Underlying sync HTTP client (advanced use)."""
+        return self._sync.http

nitroping/_devices.py

@@ -0,0 +1,61 @@
+"""``devices`` resource client.
+
+Mounted on :class:`nitroping.Nitroping` as ``np.devices``. Wraps
+``POST /api/v1/devices`` and ``DELETE /api/v1/devices/:id``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+from urllib.parse import quote
+
+from ._http import HttpClient
+from .types import DeactivateDeviceResult, Platform, RegisterDeviceResult
+
+
+class DevicesClient:
+    """Register and deactivate device rows."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def register(
+        self,
+        *,
+        platform: Platform,
+        token: str,
+        user_id: str | None = None,
+        web_push_p256dh: str | None = None,
+        web_push_auth: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RegisterDeviceResult:
+        """Register (or update) a device with the secret API key.
+
+        Idempotent on ``(app_id, token, user_id)``. Returns
+        ``{"id": ..., "created": True}`` when a new row was inserted,
+        ``{"id": ..., "created": False}`` when an existing device matched.
+        """
+        wire: dict[str, Any] = {"token": token, "platform": platform}
+        if user_id is not None:
+            wire["user_id"] = user_id
+        if web_push_p256dh is not None:
+            wire["web_push_p256dh"] = web_push_p256dh
+        if web_push_auth is not None:
+            wire["web_push_auth"] = web_push_auth
+        if metadata is not None:
+            wire["metadata"] = metadata
+
+        response = self._http.request("POST", "/api/v1/devices", body=wire)
+        return cast(RegisterDeviceResult, response)
+
+    def deactivate(self, device_id: str) -> DeactivateDeviceResult:
+        """Soft-delete a device (sets ``status = inactive``).
+
+        Returns ``{"id": ..., "status": "inactive"}``. Raises
+        :class:`~nitroping.errors.ApiError` with ``code = "not_found"``
+        if the id doesn't belong to your app.
+        """
+        response = self._http.request(
+            "DELETE", f"/api/v1/devices/{quote(device_id, safe='')}"
+        )
+        return cast(DeactivateDeviceResult, response)

nitroping/_http.py

@@ -0,0 +1,158 @@
+"""Internal stdlib HTTP wrapper.
+
+Adds the ``Authorization`` header, JSON-serializes the body, parses the
+JSON response, and maps non-2xx envelopes (``{"error": {"code",
+"message", "details"}}``) into :class:`ApiError`. Underlying transport
+failure (DNS / TLS / offline / abort) becomes :class:`NetworkError`.
+
+Zero runtime deps — :mod:`urllib.request` only.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from typing import Any, NoReturn
+
+from .errors import ApiError, NetworkError, NitropingError
+
+#: Default base URL pointing at the hosted nitroping service.
+DEFAULT_BASE_URL = "https://nitroping.dev"
+
+#: SDK version — bumped via ``pyproject.toml``. Used in the User-Agent
+#: header so requests can be attributed during incident investigation.
+SDK_VERSION = "0.1.0"
+
+
+class HttpClient:
+    """Internal structured HTTP client.
+
+    Not part of the public surface — use :class:`nitroping.Nitroping`
+    instead. Exposed for advanced cases where callers need to make raw
+    requests against undocumented endpoints.
+    """
+
+    base_url: str
+    api_key: str
+    timeout: float
+    user_agent: str
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        if not api_key:
+            raise NitropingError("api_key is required", code="invalid_argument")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent or f"nitroping-python/{SDK_VERSION}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Perform an HTTP request and parse the JSON envelope.
+
+        Returns the decoded JSON body (``dict`` for object responses,
+        ``list`` / ``str`` / ``None`` for everything else). Raises
+        :class:`ApiError` on non-2xx with a server envelope,
+        :class:`NetworkError` on transport failure.
+        """
+        url = self._build_url(path)
+        body_bytes: bytes | None = None
+
+        all_headers: dict[str, str] = {
+            "Authorization": f"ApiKey {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        if headers:
+            for k, v in headers.items():
+                all_headers[k] = v
+
+        if body is not None:
+            body_bytes = json.dumps(body).encode("utf-8")
+            all_headers["Content-Type"] = "application/json"
+
+        req = urllib.request.Request(
+            url=url, data=body_bytes, method=method, headers=all_headers
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as http_err:
+            # Non-2xx — try to decode the JSON error envelope, fall back
+            # to ``http_<status>`` if the body is not JSON.
+            err_body = http_err.read()
+            _raise_for_error(http_err.code, err_body)
+        except urllib.error.URLError as url_err:
+            raise NetworkError(
+                f"Request to {url} failed: {url_err.reason}", cause=url_err
+            ) from url_err
+        except TimeoutError as timeout_err:
+            raise NetworkError(
+                f"Request to {url} timed out", cause=timeout_err
+            ) from timeout_err
+        except OSError as os_err:
+            raise NetworkError(
+                f"Request to {url} failed: {os_err}", cause=os_err
+            ) from os_err
+
+        return _decode_body(raw)
+
+    def _build_url(self, path: str) -> str:
+        suffix = path if path.startswith("/") else f"/{path}"
+        return f"{self.base_url}{suffix}"
+
+
+def _decode_body(raw: bytes) -> Any:
+    if not raw:
+        return None
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        # 2xx with a non-JSON body — pass through as a string. We never
+        # hit this for the documented endpoints but it keeps the path
+        # forward-compatible.
+        return text
+
+
+def _raise_for_error(status: int, raw: bytes) -> NoReturn:
+    """Translate an HTTPError body into an :class:`ApiError` with the
+    server's machine-readable code + per-field details."""
+    code = f"http_{status}"
+    message = f"HTTP {status}"
+    details: Any = None
+
+    if raw:
+        text = raw.decode("utf-8", errors="replace")
+        try:
+            envelope = json.loads(text)
+        except json.JSONDecodeError:
+            message = f"HTTP {status}: {text[:200]}"
+        else:
+            if isinstance(envelope, dict):
+                err = envelope.get("error")
+                if isinstance(err, dict):
+                    raw_code = err.get("code")
+                    if isinstance(raw_code, str) and raw_code:
+                        code = raw_code
+                    raw_message = err.get("message")
+                    if isinstance(raw_message, str) and raw_message:
+                        message = raw_message
+                    details = err.get("details")
+
+    raise ApiError(message, status=status, code=code, details=details)

nitroping/_notifications.py

@@ -0,0 +1,94 @@
+"""``notifications`` resource client.
+
+Mounted on :class:`nitroping.Nitroping` as ``np.notifications``. Wraps
+``POST /api/v1/notifications`` and ``GET /api/v1/notifications/:id``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+from urllib.parse import quote
+
+from ._http import HttpClient
+from .types import NotificationAction, NotificationResult, NotificationTarget
+
+
+class NotificationsClient:
+    """Send and inspect notifications."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def send(
+        self,
+        *,
+        target: NotificationTarget,
+        title: str | None = None,
+        body: str | None = None,
+        template: str | None = None,
+        vars: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        icon: str | None = None,
+        image: str | None = None,
+        click_action: str | None = None,
+        deep_link: str | None = None,
+        actions: list[NotificationAction] | None = None,
+        scheduled_at: str | None = None,
+        expires_at: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> NotificationResult:
+        """Enqueue a new notification.
+
+        Either ``title + body`` (raw payload) or ``template + vars``
+        (Pro plan). Mixing the two is a 422.
+
+        Returns ``{"id": ..., "status": ...}`` on ``201 Created``. On
+        non-2xx the SDK raises :class:`~nitroping.errors.ApiError`
+        carrying the server's ``code``, ``message``, and (for validation
+        failures) the per-field ``details`` map.
+        """
+        wire: dict[str, Any] = {"target": dict(target)}
+        if title is not None:
+            wire["title"] = title
+        if body is not None:
+            wire["body"] = body
+        if template is not None:
+            wire["template"] = template
+        if vars is not None:
+            wire["vars"] = vars
+        if data is not None:
+            wire["data"] = data
+        if icon is not None:
+            wire["icon"] = icon
+        if image is not None:
+            wire["image"] = image
+        if click_action is not None:
+            wire["click_action"] = click_action
+        if deep_link is not None:
+            wire["deep_link"] = deep_link
+        if actions is not None:
+            wire["actions"] = actions
+        if scheduled_at is not None:
+            wire["scheduled_at"] = scheduled_at
+        if expires_at is not None:
+            wire["expires_at"] = expires_at
+
+        headers: dict[str, str] = {}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        response = self._http.request(
+            "POST", "/api/v1/notifications", body=wire, headers=headers
+        )
+        return cast(NotificationResult, response)
+
+    def get(self, notification_id: str) -> dict[str, Any]:
+        """Fetch a previously-enqueued notification by id.
+
+        Returns the full row (including counters: ``total_sent``,
+        ``total_delivered``, ``total_failed``, etc.).
+        """
+        response = self._http.request(
+            "GET", f"/api/v1/notifications/{quote(notification_id, safe='')}"
+        )
+        return cast(dict[str, Any], response)

nitroping/errors.py

@@ -0,0 +1,110 @@
+"""Error hierarchy for the nitroping SDK.
+
+All public functions raise subclasses of :class:`NitropingError`. Catch the
+base class to handle every error, or narrow by ``isinstance`` on the
+specific subclass when you want to switch on a known failure mode (e.g.
+retry on :class:`NetworkError`, surface an HTTP 400 on
+:class:`InvalidSignatureError`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class NitropingError(Exception):
+    """Base error raised by every SDK function.
+
+    Subclasses set :attr:`code` and may add structured fields
+    (:attr:`status`, :attr:`details`).
+    """
+
+    #: Optional HTTP status if this error originated from a response.
+    status: int | None
+
+    #: Stable machine-readable code, mirrored from the server envelope
+    #: (``error.code``). Examples: ``"invalid_api_key"``,
+    #: ``"validation_failed"``, ``"quota_exceeded"``. SDK-internal failures
+    #: use codes like ``"network_error"`` or ``"invalid_signature"``.
+    code: str
+
+    #: Free-form details object — typically the server's ``error.details``
+    #: (field-level validation errors).
+    details: Any
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str = "error",
+        details: Any = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.details = details
+        if cause is not None:
+            self.__cause__ = cause
+
+
+class ApiError(NitropingError):
+    """Raised when the server returns a non-2xx response.
+
+    Carries the server's ``code``, ``message``, and (for validation
+    failures) the per-field ``details`` map.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str = "error",
+        details: Any = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code, details=details)
+
+
+class NetworkError(NitropingError):
+    """Raised when the HTTP transport itself fails.
+
+    Wraps DNS / TLS / offline / abort errors. The underlying exception is
+    attached via :attr:`__cause__`.
+    """
+
+    def __init__(self, message: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(message, code="network_error", cause=cause)
+
+
+class InvalidSignatureError(NitropingError):
+    """Raised by :func:`nitroping.webhooks.verify` when the HMAC does not
+    match the request body, or the signature header is malformed."""
+
+    def __init__(
+        self, message: str = "Webhook signature does not match request body"
+    ) -> None:
+        super().__init__(message, code="invalid_signature")
+
+
+class TimestampOutOfRangeError(NitropingError):
+    """Raised by :func:`nitroping.webhooks.verify` when the signature is
+    well-formed and matches the body, but its ``t=`` timestamp is outside
+    the tolerance window. Defends against signature replay."""
+
+    def __init__(
+        self,
+        message: str = "Webhook timestamp is outside the allowed tolerance",
+    ) -> None:
+        super().__init__(message, code="timestamp_out_of_range")
+
+
+class MissingSignatureHeaderError(NitropingError):
+    """Raised by :func:`nitroping.webhooks.verify` when the
+    ``X-Nitroping-Signature`` header is absent."""
+
+    def __init__(
+        self, message: str = "Missing X-Nitroping-Signature header"
+    ) -> None:
+        super().__init__(message, code="missing_signature_header")