nitroping 0.2.2__tar.gz → 0.2.4__tar.gz

{nitroping-0.2.2 → nitroping-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nitroping
-Version: 0.2.2
+Version: 0.2.4
 Summary: Zero-dependency Python SDK for nitroping push notifications. Send pushes, register devices, verify webhooks.
 Project-URL: Homepage, https://nitroping.dev
 Project-URL: Repository, https://github.com/productdevbook/nitroping-sdk
@@ -24,22 +24,17 @@ Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Description-Content-Type: text/markdown
 
-> Part of the [**nitroping-sdk**](https://github.com/productdevbook/nitroping-sdk) monorepo.
-> The PyPI package name (`nitroping`) is unchanged. See the [top-level README](../README.md) for SDKs in other languages.
+# nitroping (Python SDK)
 
-<p align="center">
-  <br>
-  <b style="font-size: 2em;">nitroping-python</b>
-  <br><br>
-  Zero-dependency Python SDK for <a href="https://nitroping.dev">nitroping</a>.
-  <br>
-  Send push notifications, register devices, verify webhooks. Pure stdlib, runs on Python 3.10+.
-  <br><br>
-  <a href="https://pypi.org/project/nitroping/"><img src="https://img.shields.io/pypi/v/nitroping?style=flat&colorA=18181B&colorB=34d399" alt="PyPI version"></a>
-  <a href="https://pypi.org/project/nitroping/"><img src="https://img.shields.io/pypi/pyversions/nitroping?style=flat&colorA=18181B&colorB=34d399" alt="Python versions"></a>
-  <a href="https://pypi.org/project/nitroping/"><img src="https://img.shields.io/pypi/dm/nitroping?style=flat&colorA=18181B&colorB=34d399" alt="PyPI downloads"></a>
-  <a href="https://github.com/productdevbook/nitroping-sdk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/productdevbook/nitroping-sdk?style=flat&colorA=18181B&colorB=34d399" alt="license"></a>
-</p>
+[![PyPI version](https://img.shields.io/pypi/v/nitroping?logo=pypi&color=3775a9)](https://pypi.org/project/nitroping/)
+[![Python versions](https://img.shields.io/pypi/pyversions/nitroping?logo=python)](https://pypi.org/project/nitroping/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/nitroping?logo=pypi)](https://pypi.org/project/nitroping/)
+[![license MIT](https://img.shields.io/pypi/l/nitroping)](https://github.com/productdevbook/nitroping-sdk/blob/main/LICENSE)
+[![types](https://img.shields.io/pypi/types/nitroping?label=typed&logo=python)](https://pypi.org/project/nitroping/)
+
+> Zero-dependency Python SDK for [nitroping](https://nitroping.dev) push notifications. Send pushes, register devices, verify webhooks. Pure stdlib, runs on Python 3.10+.
+
+> 📦 Part of the [**nitroping-sdk**](https://github.com/productdevbook/nitroping-sdk) monorepo. The PyPI package name (`nitroping`) is unchanged. See the [root README](https://github.com/productdevbook/nitroping-sdk#readme) for SDKs in other languages.
 
 ## Why nitroping?
 
@@ -415,12 +410,12 @@ from nitroping import NotificationResult, RegisterDeviceResult, WebhookEvent
 
 ## License
 
-[MIT](../LICENSE) — Copyright (c) 2026 productdevbook.
+MIT — see [LICENSE](https://github.com/productdevbook/nitroping-sdk/blob/main/LICENSE). Copyright (c) 2026 productdevbook.
 
 ---
 
 <p align="center">
   <sub>
-    Built by <a href="https://github.com/productdevbook">@productdevbook</a> — <a href="https://nitroping.dev">nitroping.dev</a> · <a href="https://github.com/productdevbook/nitroping">OSS core</a>
+    Built by <a href="https://github.com/productdevbook">@productdevbook</a> — <a href="https://nitroping.dev">nitroping.dev</a> · <a href="https://github.com/productdevbook/nitroping-sdk#readme">monorepo</a> · <a href="https://github.com/productdevbook/nitroping">OSS core</a>
   </sub>
 </p>

{nitroping-0.2.2 → nitroping-0.2.4}/README.md

@@ -1,19 +1,14 @@
-> Part of the [**nitroping-sdk**](https://github.com/productdevbook/nitroping-sdk) monorepo.
-> The PyPI package name (`nitroping`) is unchanged. See the [top-level README](../README.md) for SDKs in other languages.
+# nitroping (Python SDK)
 
-<p align="center">
-  <br>
-  <b style="font-size: 2em;">nitroping-python</b>
-  <br><br>
-  Zero-dependency Python SDK for <a href="https://nitroping.dev">nitroping</a>.
-  <br>
-  Send push notifications, register devices, verify webhooks. Pure stdlib, runs on Python 3.10+.
-  <br><br>
-  <a href="https://pypi.org/project/nitroping/"><img src="https://img.shields.io/pypi/v/nitroping?style=flat&colorA=18181B&colorB=34d399" alt="PyPI version"></a>
-  <a href="https://pypi.org/project/nitroping/"><img src="https://img.shields.io/pypi/pyversions/nitroping?style=flat&colorA=18181B&colorB=34d399" alt="Python versions"></a>
-  <a href="https://pypi.org/project/nitroping/"><img src="https://img.shields.io/pypi/dm/nitroping?style=flat&colorA=18181B&colorB=34d399" alt="PyPI downloads"></a>
-  <a href="https://github.com/productdevbook/nitroping-sdk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/productdevbook/nitroping-sdk?style=flat&colorA=18181B&colorB=34d399" alt="license"></a>
-</p>
+[![PyPI version](https://img.shields.io/pypi/v/nitroping?logo=pypi&color=3775a9)](https://pypi.org/project/nitroping/)
+[![Python versions](https://img.shields.io/pypi/pyversions/nitroping?logo=python)](https://pypi.org/project/nitroping/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/nitroping?logo=pypi)](https://pypi.org/project/nitroping/)
+[![license MIT](https://img.shields.io/pypi/l/nitroping)](https://github.com/productdevbook/nitroping-sdk/blob/main/LICENSE)
+[![types](https://img.shields.io/pypi/types/nitroping?label=typed&logo=python)](https://pypi.org/project/nitroping/)
+
+> Zero-dependency Python SDK for [nitroping](https://nitroping.dev) push notifications. Send pushes, register devices, verify webhooks. Pure stdlib, runs on Python 3.10+.
+
+> 📦 Part of the [**nitroping-sdk**](https://github.com/productdevbook/nitroping-sdk) monorepo. The PyPI package name (`nitroping`) is unchanged. See the [root README](https://github.com/productdevbook/nitroping-sdk#readme) for SDKs in other languages.
 
 ## Why nitroping?
 
@@ -389,12 +384,12 @@ from nitroping import NotificationResult, RegisterDeviceResult, WebhookEvent
 
 ## License
 
-[MIT](../LICENSE) — Copyright (c) 2026 productdevbook.
+MIT — see [LICENSE](https://github.com/productdevbook/nitroping-sdk/blob/main/LICENSE). Copyright (c) 2026 productdevbook.
 
 ---
 
 <p align="center">
   <sub>
-    Built by <a href="https://github.com/productdevbook">@productdevbook</a> — <a href="https://nitroping.dev">nitroping.dev</a> · <a href="https://github.com/productdevbook/nitroping">OSS core</a>
+    Built by <a href="https://github.com/productdevbook">@productdevbook</a> — <a href="https://nitroping.dev">nitroping.dev</a> · <a href="https://github.com/productdevbook/nitroping-sdk#readme">monorepo</a> · <a href="https://github.com/productdevbook/nitroping">OSS core</a>
   </sub>
 </p>

{nitroping-0.2.2 → nitroping-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nitroping"
-version = "0.2.2"
+version = "0.2.4"
 description = "Zero-dependency Python SDK for nitroping push notifications. Send pushes, register devices, verify webhooks."
 readme = "README.md"
 license = { text = "MIT" }

{nitroping-0.2.2 → nitroping-0.2.4}/src/nitroping/__init__.py

@@ -21,8 +21,10 @@ from __future__ import annotations
 
 from ._client import AsyncNitroping, Nitroping
 from ._devices import DevicesClient
+from ._events import EventsClient
 from ._http import DEFAULT_BASE_URL, HttpClient
 from ._notifications import NotificationsClient
+from ._track import TrackClient
 from .errors import (
     ApiError,
     InvalidSignatureError,
@@ -32,27 +34,37 @@ from .errors import (
     TimestampOutOfRangeError,
 )
 from .types import (
+    CancelNotificationResult,
     DeactivateDeviceResult,
+    EngagementEvent,
     NotificationAction,
     NotificationResult,
     NotificationTarget,
     Platform,
     RegisterDeviceResult,
+    ReportEventResult,
     SendOptions,
     TargetAll,
     TargetDeviceIds,
+    TargetTags,
     TargetUserIds,
+    TrackEvent,
+    TrackResult,
+    UpdateDeviceResult,
     WebhookEvent,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.4"
 
 __all__ = [
     "DEFAULT_BASE_URL",
     "ApiError",
     "AsyncNitroping",
+    "CancelNotificationResult",
     "DeactivateDeviceResult",
     "DevicesClient",
+    "EngagementEvent",
+    "EventsClient",
     "HttpClient",
     "InvalidSignatureError",
     "MissingSignatureHeaderError",
@@ -65,11 +77,17 @@ __all__ = [
     "NotificationsClient",
     "Platform",
     "RegisterDeviceResult",
+    "ReportEventResult",
     "SendOptions",
     "TargetAll",
     "TargetDeviceIds",
+    "TargetTags",
     "TargetUserIds",
     "TimestampOutOfRangeError",
+    "TrackClient",
+    "TrackEvent",
+    "TrackResult",
+    "UpdateDeviceResult",
     "WebhookEvent",
     "__version__",
 ]

{nitroping-0.2.2 → nitroping-0.2.4}/src/nitroping/_client.py

@@ -7,16 +7,24 @@ import os
 from typing import Any
 
 from ._devices import DevicesClient
+from ._events import EventsClient
 from ._http import DEFAULT_BASE_URL, HttpClient
 from ._notifications import NotificationsClient
+from ._track import TrackClient
 from .errors import NitropingError
 from .types import (
+    CancelNotificationResult,
     DeactivateDeviceResult,
+    EngagementEvent,
     NotificationAction,
     NotificationResult,
     NotificationTarget,
     Platform,
     RegisterDeviceResult,
+    ReportEventResult,
+    TrackEvent,
+    TrackResult,
+    UpdateDeviceResult,
 )
 
 
@@ -36,10 +44,14 @@ class Nitroping:
         print(result["id"], result["status"])
     """
 
-    #: ``notifications`` resource — send, get.
+    #: ``notifications`` resource — send, get, cancel.
     notifications: NotificationsClient
-    #: ``devices`` resource — register, deactivate.
+    #: ``devices`` resource — register, update, deactivate.
     devices: DevicesClient
+    #: ``track`` resource — delivery/open/click callbacks (``POST /track``).
+    track: TrackClient
+    #: ``events`` resource — public engagement events (``POST /events``).
+    events: EventsClient
     #: Internal HTTP client. Exposed for advanced use (custom requests).
     http: HttpClient
 
@@ -68,6 +80,8 @@ class Nitroping:
         )
         self.notifications = NotificationsClient(self.http)
         self.devices = DevicesClient(self.http)
+        self.track = TrackClient(self.http)
+        self.events = EventsClient(self.http)
 
 
 class _AsyncNotificationsClient:
@@ -128,6 +142,12 @@ class _AsyncNotificationsClient:
             None, self._inner.get, notification_id
         )
 
+    async def cancel(self, notification_id: str) -> CancelNotificationResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, self._inner.cancel, notification_id
+        )
+
 
 class _AsyncDevicesClient:
     """Awaitable façade over :class:`DevicesClient`."""
@@ -144,6 +164,7 @@ class _AsyncDevicesClient:
         web_push_p256dh: str | None = None,
         web_push_auth: str | None = None,
         metadata: dict[str, Any] | None = None,
+        tags: list[str] | None = None,
     ) -> RegisterDeviceResult:
         loop = asyncio.get_running_loop()
         return await loop.run_in_executor(
@@ -155,9 +176,22 @@ class _AsyncDevicesClient:
                 web_push_p256dh=web_push_p256dh,
                 web_push_auth=web_push_auth,
                 metadata=metadata,
+                tags=tags,
             ),
         )
 
+    async def update(
+        self,
+        device_id: str,
+        *,
+        tags: list[str] | None = None,
+    ) -> UpdateDeviceResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._inner.update(device_id, tags=tags),
+        )
+
     async def deactivate(self, device_id: str) -> DeactivateDeviceResult:
         loop = asyncio.get_running_loop()
         return await loop.run_in_executor(
@@ -165,6 +199,60 @@ class _AsyncDevicesClient:
         )
 
 
+class _AsyncTrackClient:
+    """Awaitable façade over :class:`TrackClient`."""
+
+    def __init__(self, inner: TrackClient) -> None:
+        self._inner = inner
+
+    async def record(
+        self,
+        *,
+        event: TrackEvent,
+        delivery_log_id: str | None = None,
+        notification_id: str | None = None,
+        device_token: str | None = None,
+    ) -> TrackResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._inner.record(
+                event=event,
+                delivery_log_id=delivery_log_id,
+                notification_id=notification_id,
+                device_token=device_token,
+            ),
+        )
+
+
+class _AsyncEventsClient:
+    """Awaitable façade over :class:`EventsClient`."""
+
+    def __init__(self, inner: EventsClient) -> None:
+        self._inner = inner
+
+    async def report(
+        self,
+        *,
+        notification_id: str,
+        device_id: str,
+        type: EngagementEvent,
+        action_id: str | None = None,
+        happened_at: str | None = None,
+    ) -> ReportEventResult:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._inner.report(
+                notification_id=notification_id,
+                device_id=device_id,
+                type=type,
+                action_id=action_id,
+                happened_at=happened_at,
+            ),
+        )
+
+
 class AsyncNitroping:
     """Async server-side SDK client.
 
@@ -180,6 +268,8 @@ class AsyncNitroping:
 
     notifications: _AsyncNotificationsClient
     devices: _AsyncDevicesClient
+    track: _AsyncTrackClient
+    events: _AsyncEventsClient
 
     def __init__(
         self,
@@ -197,6 +287,8 @@ class AsyncNitroping:
         )
         self.notifications = _AsyncNotificationsClient(self._sync.notifications)
         self.devices = _AsyncDevicesClient(self._sync.devices)
+        self.track = _AsyncTrackClient(self._sync.track)
+        self.events = _AsyncEventsClient(self._sync.events)
 
     @property
     def http(self) -> HttpClient:

{nitroping-0.2.2 → nitroping-0.2.4}/src/nitroping/_devices.py

@@ -1,7 +1,8 @@
 """``devices`` resource client.
 
 Mounted on :class:`nitroping.Nitroping` as ``np.devices``. Wraps
-``POST /api/v1/devices`` and ``DELETE /api/v1/devices/:id``.
+``POST /api/v1/devices``, ``PUT /api/v1/devices/:id``, and
+``DELETE /api/v1/devices/:id``.
 """
 
 from __future__ import annotations
@@ -10,11 +11,16 @@ from typing import Any, cast
 from urllib.parse import quote
 
 from ._http import HttpClient
-from .types import DeactivateDeviceResult, Platform, RegisterDeviceResult
+from .types import (
+    DeactivateDeviceResult,
+    Platform,
+    RegisterDeviceResult,
+    UpdateDeviceResult,
+)
 
 
 class DevicesClient:
-    """Register and deactivate device rows."""
+    """Register, update, and deactivate device rows."""
 
     def __init__(self, http: HttpClient) -> None:
         self._http = http
@@ -28,12 +34,15 @@ class DevicesClient:
         web_push_p256dh: str | None = None,
         web_push_auth: str | None = None,
         metadata: dict[str, Any] | None = None,
+        tags: list[str] | 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.
+
+        ``tags`` enables tag-based targeting (``target={"tags": [...]}``).
         """
         wire: dict[str, Any] = {"token": token, "platform": platform}
         if user_id is not None:
@@ -44,10 +53,34 @@ class DevicesClient:
             wire["web_push_auth"] = web_push_auth
         if metadata is not None:
             wire["metadata"] = metadata
+        if tags is not None:
+            wire["tags"] = tags
 
-        response = self._http.request("POST", "/api/v1/devices", body=wire)
+        path = "/api/v1/public/devices" if self._http.auth_scheme == "Public" else "/api/v1/devices"
+        response = self._http.request("POST", path, body=wire)
         return cast(RegisterDeviceResult, response)
 
+    def update(
+        self,
+        device_id: str,
+        *,
+        tags: list[str] | None = None,
+    ) -> UpdateDeviceResult:
+        """Update a device (e.g. replace its tags).
+
+        Wraps ``PUT /api/v1/devices/:id``. Returns ``{"id": ..., "tags":
+        [...]}``. Raises :class:`~nitroping.errors.ApiError` with
+        ``code = "not_found"`` if the id doesn't belong to your app.
+        """
+        wire: dict[str, Any] = {}
+        if tags is not None:
+            wire["tags"] = tags
+
+        response = self._http.request(
+            "PUT", f"/api/v1/devices/{quote(device_id, safe='')}", body=wire
+        )
+        return cast(UpdateDeviceResult, response)
+
     def deactivate(self, device_id: str) -> DeactivateDeviceResult:
         """Soft-delete a device (sets ``status = inactive``).
 

nitroping-0.2.4/src/nitroping/_events.py

@@ -0,0 +1,53 @@
+"""``events`` resource client.
+
+Mounted on :class:`nitroping.Nitroping` as ``np.events``. Wraps
+``POST /api/v1/events`` — the public, unauthenticated engagement
+endpoint. The ``(notification_id, device_id)`` pair is the bearer
+secret, so no ``Authorization`` header is required (and a ``pk_`` public
+key is fine).
+
+This is the endpoint a client app calls when a notification is opened or
+a notification action is clicked.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from ._http import HttpClient
+from .types import EngagementEvent, ReportEventResult
+
+
+class EventsClient:
+    """Report public engagement events (``opened`` / ``clicked``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def report(
+        self,
+        *,
+        notification_id: str,
+        device_id: str,
+        type: EngagementEvent,
+        action_id: str | None = None,
+        happened_at: str | None = None,
+    ) -> ReportEventResult:
+        """Report an engagement event (``opened`` or ``clicked``).
+
+        Returns ``{"accepted": True}`` on 202. Raises
+        :class:`~nitroping.errors.ApiError` with ``code = "not_found"``
+        (404) if the notification/device pair is unknown.
+        """
+        wire: dict[str, Any] = {
+            "notification_id": notification_id,
+            "device_id": device_id,
+            "type": type,
+        }
+        if action_id is not None:
+            wire["action_id"] = action_id
+        if happened_at is not None:
+            wire["happened_at"] = happened_at
+
+        response = self._http.request("POST", "/api/v1/events", body=wire)
+        return cast(ReportEventResult, response)

{nitroping-0.2.2 → nitroping-0.2.4}/src/nitroping/_http.py

@@ -23,7 +23,7 @@ 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"
+SDK_VERSION = "0.2.3"
 
 
 class HttpClient:
@@ -36,6 +36,7 @@ class HttpClient:
 
     base_url: str
     api_key: str
+    auth_scheme: str
     timeout: float
     user_agent: str
 
@@ -46,10 +47,12 @@ class HttpClient:
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = 30.0,
         user_agent: str | None = None,
+        auth_scheme: str | None = None,
     ) -> None:
         if not api_key:
             raise NitropingError("api_key is required", code="invalid_argument")
         self.api_key = api_key
+        self.auth_scheme = auth_scheme or ("Public" if api_key.startswith("pk_") else "ApiKey")
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self.user_agent = user_agent or f"nitroping-python/{SDK_VERSION}"
@@ -73,7 +76,7 @@ class HttpClient:
         body_bytes: bytes | None = None
 
         all_headers: dict[str, str] = {
-            "Authorization": f"ApiKey {self.api_key}",
+            "Authorization": f"{self.auth_scheme} {self.api_key}",
             "Accept": "application/json",
             "User-Agent": self.user_agent,
         }

{nitroping-0.2.2 → nitroping-0.2.4}/src/nitroping/_notifications.py

@@ -10,7 +10,12 @@ from typing import Any, cast
 from urllib.parse import quote
 
 from ._http import HttpClient
-from .types import NotificationAction, NotificationResult, NotificationTarget
+from .types import (
+    CancelNotificationResult,
+    NotificationAction,
+    NotificationResult,
+    NotificationTarget,
+)
 
 
 class NotificationsClient:
@@ -92,3 +97,17 @@ class NotificationsClient:
             "GET", f"/api/v1/notifications/{quote(notification_id, safe='')}"
         )
         return cast(dict[str, Any], response)
+
+    def cancel(self, notification_id: str) -> CancelNotificationResult:
+        """Cancel a scheduled or in-flight notification.
+
+        Wraps ``DELETE /api/v1/notifications/:id``. Returns
+        ``{"id": ..., "status": "canceled"}``. Raises
+        :class:`~nitroping.errors.ApiError` with ``code = "cannot_cancel"``
+        (409) if the notification already reached a terminal state, or
+        ``code = "not_found"`` (404).
+        """
+        response = self._http.request(
+            "DELETE", f"/api/v1/notifications/{quote(notification_id, safe='')}"
+        )
+        return cast(CancelNotificationResult, response)

nitroping-0.2.4/src/nitroping/_track.py

@@ -0,0 +1,55 @@
+"""``track`` resource client.
+
+Mounted on :class:`nitroping.Nitroping` as ``np.track``. Wraps
+``POST /api/v1/track`` — the server SDK delivery/open/click callback.
+Returns 202 immediately; the write is absorbed by a background worker.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from ._http import HttpClient
+from .errors import NitropingError
+from .types import TrackEvent, TrackResult
+
+
+class TrackClient:
+    """Record delivery/open/click events against a delivery log."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def record(
+        self,
+        *,
+        event: TrackEvent,
+        delivery_log_id: str | None = None,
+        notification_id: str | None = None,
+        device_token: str | None = None,
+    ) -> TrackResult:
+        """Record a delivery/open/click event against a delivery log.
+
+        Identify the target either by ``delivery_log_id``, or by
+        ``notification_id`` + the device's ``device_token``. ``event`` is
+        one of ``delivered | opened | clicked``.
+
+        Returns ``{"accepted": True}`` on 202.
+        """
+        if delivery_log_id is not None:
+            wire = {"delivery_log_id": delivery_log_id, "event": event}
+        elif notification_id is not None and device_token is not None:
+            wire = {
+                "notification_id": notification_id,
+                "device_token": device_token,
+                "event": event,
+            }
+        else:
+            raise NitropingError(
+                "track.record requires either delivery_log_id, or both "
+                "notification_id and device_token",
+                code="invalid_argument",
+            )
+
+        response = self._http.request("POST", "/api/v1/track", body=wire)
+        return cast(TrackResult, response)

{nitroping-0.2.2 → nitroping-0.2.4}/src/nitroping/types.py

@@ -44,8 +44,14 @@ class TargetUserIds(TypedDict):
     user_ids: list[str]
 
 
-#: Target selector for a notification. Exactly one of the three.
-NotificationTarget = TargetAll | TargetDeviceIds | TargetUserIds
+class TargetTags(TypedDict):
+    """Hit every device row tagged with one of the given tags."""
+
+    tags: list[str]
+
+
+#: Target selector for a notification. Exactly one of the four.
+NotificationTarget = TargetAll | TargetDeviceIds | TargetUserIds | TargetTags
 
 
 class SendOptions(TypedDict, total=False):
@@ -79,6 +85,15 @@ class RegisterDeviceResult(TypedDict):
     created: bool
 
 
+class UpdateDeviceResult(TypedDict):
+    """Response from ``PUT /api/v1/devices/:id``."""
+
+    #: UUID of the device row.
+    id: str
+    #: The device's tags after the update.
+    tags: list[str]
+
+
 class DeactivateDeviceResult(TypedDict):
     """Response from ``DELETE /api/v1/devices/:id``."""
 
@@ -86,6 +101,32 @@ class DeactivateDeviceResult(TypedDict):
     status: str
 
 
+class CancelNotificationResult(TypedDict):
+    """Response from ``DELETE /api/v1/notifications/:id``."""
+
+    id: str
+    status: str
+
+
+#: Delivery-tracking event type for ``POST /api/v1/track``.
+TrackEvent = Literal["delivered", "opened", "clicked"]
+
+#: Engagement event type for ``POST /api/v1/events``.
+EngagementEvent = Literal["opened", "clicked"]
+
+
+class TrackResult(TypedDict):
+    """Response from ``POST /api/v1/track``."""
+
+    accepted: bool
+
+
+class ReportEventResult(TypedDict):
+    """Response from ``POST /api/v1/events``."""
+
+    accepted: bool
+
+
 class WebhookEvent(TypedDict):
     """Outbound webhook event envelope (parsed from a
     :func:`nitroping.webhooks.verify` call)."""

{nitroping-0.2.2 → nitroping-0.2.4}/tests/test_devices.py

@@ -52,6 +52,36 @@ def test_register_web_with_p256dh_and_auth(mock_urlopen):
     assert body["web_push_auth"] == "auth_secret_value"
 
 
+def test_register_with_tags(mock_urlopen):
+    """tags kwarg lands on the wire as a `tags` array."""
+    mock_urlopen.enqueue_json(201, {"id": "dev-3", "created": True})
+
+    np = Nitroping(api_key="np_x")
+    np.devices.register(
+        platform="android",
+        token="fcm-token-xyz",
+        tags=["beta", "vip"],
+    )
+
+    body = mock_urlopen.calls[0].body_json
+    assert body is not None
+    assert body["tags"] == ["beta", "vip"]
+
+
+def test_update_sends_put_with_tags(mock_urlopen):
+    """PUT /api/v1/devices/:id with {tags:[...]}, returns {id, tags}."""
+    mock_urlopen.enqueue_json(200, {"id": "dev-1", "tags": ["beta"]})
+
+    np = Nitroping(api_key="np_x")
+    result = np.devices.update("dev-1", tags=["beta"])
+
+    assert result == {"id": "dev-1", "tags": ["beta"]}
+    call = mock_urlopen.calls[0]
+    assert call.method == "PUT"
+    assert call.url == "https://nitroping.dev/api/v1/devices/dev-1"
+    assert call.body_json == {"tags": ["beta"]}
+
+
 def test_deactivate_sends_delete(mock_urlopen):
     """DELETE /api/v1/devices/:id with proper URL-encoded id."""
     mock_urlopen.enqueue_json(200, {"id": "dev-1", "status": "inactive"})

nitroping-0.2.4/tests/test_events.py

@@ -0,0 +1,80 @@
+"""Tests for ``np.events`` — mirrors js/test/events.test.ts."""
+
+from __future__ import annotations
+
+import pytest
+
+from nitroping import ApiError, AsyncNitroping, Nitroping
+
+
+def test_report_opened(mock_urlopen):
+    """events.report(...) → POST /api/v1/events with snake_case body."""
+    mock_urlopen.enqueue_json(202, {"accepted": True})
+
+    np = Nitroping(api_key="np_x")
+    result = np.events.report(
+        notification_id="n1",
+        device_id="d1",
+        type="opened",
+    )
+
+    assert result == {"accepted": True}
+    call = mock_urlopen.calls[0]
+    assert call.method == "POST"
+    assert call.url == "https://nitroping.dev/api/v1/events"
+    assert call.body_json == {
+        "notification_id": "n1",
+        "device_id": "d1",
+        "type": "opened",
+    }
+
+
+def test_report_clicked_with_action_and_timestamp(mock_urlopen):
+    """Optional action_id / happened_at forwarded as snake_case fields."""
+    mock_urlopen.enqueue_json(202, {"accepted": True})
+
+    np = Nitroping(api_key="np_x")
+    np.events.report(
+        notification_id="n1",
+        device_id="d1",
+        type="clicked",
+        action_id="track",
+        happened_at="2026-06-13T10:00:00Z",
+    )
+
+    assert mock_urlopen.calls[0].body_json == {
+        "notification_id": "n1",
+        "device_id": "d1",
+        "type": "clicked",
+        "action_id": "track",
+        "happened_at": "2026-06-13T10:00:00Z",
+    }
+
+
+def test_report_404_raises_apierror(mock_urlopen):
+    """Unknown notification/device pair → ApiError with not_found code."""
+    mock_urlopen.enqueue_error(
+        404,
+        {"error": {"code": "not_found", "message": "Unknown pair"}},
+    )
+
+    np = Nitroping(api_key="np_x")
+    with pytest.raises(ApiError) as exc:
+        np.events.report(notification_id="n1", device_id="d1", type="opened")
+    assert exc.value.code == "not_found"
+    assert exc.value.status == 404
+
+
+async def test_async_events_report(mock_urlopen):
+    """AsyncNitroping.events.report awaits and returns the same result."""
+    mock_urlopen.enqueue_json(202, {"accepted": True})
+
+    np = AsyncNitroping(api_key="np_x")
+    result = await np.events.report(
+        notification_id="n1",
+        device_id="d1",
+        type="opened",
+    )
+
+    assert result == {"accepted": True}
+    assert mock_urlopen.calls[0].url == "https://nitroping.dev/api/v1/events"

{nitroping-0.2.2 → nitroping-0.2.4}/tests/test_notifications.py

@@ -145,6 +145,47 @@ def test_send_target_device_ids(mock_urlopen):
     assert mock_urlopen.calls[0].body_json["target"] == {"device_ids": ["d1", "d2"]}
 
 
+def test_send_target_tags(mock_urlopen):
+    """target={'tags': [...]} passes through unchanged on the wire."""
+    mock_urlopen.enqueue_json(201, {"id": "n1", "status": "queued"})
+
+    np = Nitroping(api_key="np_x")
+    np.notifications.send(
+        title="x",
+        body="y",
+        target={"tags": ["beta", "vip"]},
+    )
+
+    assert mock_urlopen.calls[0].body_json is not None
+    assert mock_urlopen.calls[0].body_json["target"] == {"tags": ["beta", "vip"]}
+
+
+def test_cancel_sends_delete(mock_urlopen):
+    """np.notifications.cancel(id) → DELETE /api/v1/notifications/<id>."""
+    mock_urlopen.enqueue_json(200, {"id": "n1", "status": "canceled"})
+
+    np = Nitroping(api_key="np_x")
+    result = np.notifications.cancel("n1")
+
+    assert result == {"id": "n1", "status": "canceled"}
+    assert mock_urlopen.calls[0].method == "DELETE"
+    assert mock_urlopen.calls[0].url == "https://nitroping.dev/api/v1/notifications/n1"
+
+
+def test_cancel_409_raises_apierror(mock_urlopen):
+    """409 with `cannot_cancel` code is surfaced as ApiError."""
+    mock_urlopen.enqueue_error(
+        409,
+        {"error": {"code": "cannot_cancel", "message": "Already delivered"}},
+    )
+
+    np = Nitroping(api_key="np_x")
+    with pytest.raises(ApiError) as exc:
+        np.notifications.cancel("n1")
+    assert exc.value.code == "cannot_cancel"
+    assert exc.value.status == 409
+
+
 def test_get_notification(mock_urlopen):
     """np.notifications.get(id) → GET /api/v1/notifications/<id>."""
     mock_urlopen.enqueue_json(

nitroping-0.2.4/tests/test_track.py

@@ -0,0 +1,49 @@
+"""Tests for ``np.track`` — mirrors js/test/track.test.ts."""
+
+from __future__ import annotations
+
+import pytest
+
+from nitroping import Nitroping, NitropingError
+
+
+def test_record_by_delivery_log_id(mock_urlopen):
+    """track.record(delivery_log_id=..., event=...) → POST /api/v1/track."""
+    mock_urlopen.enqueue_json(202, {"accepted": True})
+
+    np = Nitroping(api_key="np_x")
+    result = np.track.record(delivery_log_id="dl-1", event="delivered")
+
+    assert result == {"accepted": True}
+    call = mock_urlopen.calls[0]
+    assert call.method == "POST"
+    assert call.url == "https://nitroping.dev/api/v1/track"
+    assert call.body_json == {"delivery_log_id": "dl-1", "event": "delivered"}
+
+
+def test_record_by_notification_and_device_token(mock_urlopen):
+    """The alternative shape: notification_id + device_token."""
+    mock_urlopen.enqueue_json(202, {"accepted": True})
+
+    np = Nitroping(api_key="np_x")
+    result = np.track.record(
+        notification_id="n1",
+        device_token="apns-abc",
+        event="opened",
+    )
+
+    assert result == {"accepted": True}
+    assert mock_urlopen.calls[0].body_json == {
+        "notification_id": "n1",
+        "device_token": "apns-abc",
+        "event": "opened",
+    }
+
+
+def test_record_requires_an_identifier(mock_urlopen):
+    """Missing both identifiers raises NitropingError, no HTTP call made."""
+    np = Nitroping(api_key="np_x")
+    with pytest.raises(NitropingError) as exc:
+        np.track.record(event="clicked")
+    assert exc.value.code == "invalid_argument"
+    assert mock_urlopen.calls == []