Add support for sequence ID and clear/delete of notifications (#150)

Author: tr4nt0r

src/aiontfy/ntfy.py

@@ -132,6 +132,54 @@ async def publish(
             await self._request("POST", self.url, json=message.to_dict())
         )
 
+    async def clear(self, topic: str, sequence_id: str) -> Notification:
+        """Clear a notification.
+
+        Clearing a notification means marking it as read and dismissing it from the notification drawer.
+
+        Parameters
+        ----------
+        topic: str
+            The topic from which to clear a notification.
+        sequence_id: str
+            The sequence-ID to identify the notification to be cleared.
+
+        Raises
+        ------
+        NtfyTimeoutError
+            If a timeout occurs during the request.
+        NtfyConnectionError
+            If a client error occurs during the request.
+        """
+
+        url = self.url / topic / sequence_id / "clear"
+
+        return Notification.from_json(await self._request("PUT", url))
+
+    async def delete(self, topic: str, sequence_id: str) -> Notification:
+        """Delete a notification.
+
+        Deleting a notification means removing it from the notification drawer and from the client's database.
+
+        Parameters
+        ----------
+        topic: str
+            The topic from which to delete a notification.
+        sequence_id: str
+            The sequence-ID to identify the notification to be deleted.
+
+        Raises
+        ------
+        NtfyTimeoutError
+            If a timeout occurs during the request.
+        NtfyConnectionError
+            If a client error occurs during the request.
+        """
+
+        url = self.url / topic / sequence_id
+
+        return Notification.from_json(await self._request("DELETE", url))
+
     async def subscribe(  # noqa: PLR0913
         self,
         topics: list[str],

src/aiontfy/types.py

@@ -159,6 +159,8 @@ class Message(DataClassORJSONMixin):
         E-mail address for e-mail notifications.
     call : str or None, optional
         Phone number to use for voice call.
+    sequence_id: str or None, optional
+        Sequence ID for updating/deleting notifications
 
     """
 
@@ -184,6 +186,7 @@ class Message(DataClassORJSONMixin):
     delay: str | None = None
     email: str | None = None
     call: str | None = None
+    sequence_id: str | None = None
 
     def __post_init__(self) -> None:
         """Post-initialization processing to validate attributes.
@@ -217,6 +220,7 @@ def to_x_headers(self) -> dict[str, str]:
             "delay": "X-Delay",
             "email": "X-Email",
             "call": "X-Call",
+            "sequence_id": "X-Sequence-ID",
         }
         data = self.to_dict()
 
@@ -264,6 +268,8 @@ class Event(StrEnum):
     KEEPALIVE = "keepalive"
     MESSAGE = "message"
     POLL_REQUEST = "poll_request"
+    MESSAGE_CLEAR = "message_clear"
+    MESSAGE_DELETE = "message_delete"
 
 
 def timestamp(ts: int) -> datetime:
@@ -310,6 +316,7 @@ class Notification(DataClassORJSONMixin):
     )
     attachment: Attachment | None = None
     content_type: str | None = None
+    sequence_id: str | None = None
 
 
 @dataclass(kw_only=True, frozen=True)

test.ipynb

@@ -2,14 +2,14 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "{'id': 'wUIvpVrClRN4', 'time': 1736379310, 'expires': 1736422510, 'event': 'message', 'topic': 'eratzartehzqwrtzq45634zhsfg', 'title': 'Title', 'message': 'test', 'priority': 5, 'tags': ['octopus'], 'click': 'https://habitica.com/', 'icon': 'https://habitica-assets.s3.amazonaws.com/mobileApp/images/shop_defensiveStance.png', 'content_type': 'text/markdown'}\n"
+      "Notification(id='9kbiJdRntcGB', time=datetime.datetime(2026, 1, 20, 17, 43, 51, tzinfo=datetime.timezone.utc), expires=datetime.datetime(2026, 1, 21, 5, 43, 51, tzinfo=datetime.timezone.utc), event=<Event.MESSAGE: 'message'>, topic='eratzartehzqwrtzq45634zhsfg', message='test', title='Title', tags=[], priority=None, click=URL('https://habitica.com/'), icon=None, actions=[], attachment=None, content_type=None, sequence_id='Mc3otamDNcpJ')\n"
      ]
     }
    ],
@@ -30,9 +30,40 @@
     "        priority=5,\n",
     "        tags=[\"octopus\"],\n",
     "        markdown=True,\n",
+    "        sequence_id=\"Mc3otamDNcpJ\",\n",
     "    )\n",
     "    print(await ntfy.publish(message))"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Notification(id='ignYrqz75Xcc', time=datetime.datetime(2026, 1, 20, 17, 44, 3, tzinfo=datetime.timezone.utc), expires=datetime.datetime(2026, 1, 21, 5, 44, 3, tzinfo=datetime.timezone.utc), event=<Event.MESSAGE_DELETE: 'message_delete'>, topic='eratzartehzqwrtzq45634zhsfg', message=None, title=None, tags=[], priority=None, click=None, icon=None, actions=[], attachment=None, content_type=None, sequence_id='Mc3otamDNcpJ')\n"
+     ]
+    }
+   ],
+   "source": [
+    "async with ClientSession() as session:\n",
+    "    ntfy = Ntfy(\"https://ntfy.sh\", session)\n",
+    "    print(await ntfy.clear(\"eratzartehzqwrtzq45634zhsfg\", \"Mc3otamDNcpJ\"))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "async with ClientSession() as session:\n",
+    "    ntfy = Ntfy(\"https://ntfy.sh\", session)\n",
+    "    print(await ntfy.delete(\"eratzartehzqwrtzq45634zhsfg\", \"Mc3otamDNcpJ\"))"
+   ]
   }
  ],
  "metadata": {

tests/conftest.py

@@ -9,9 +9,12 @@
 from aiohttp.web_ws import WebSocketResponse
 import pytest
 
-MSG = """{"id": "h6Y2hKA5sy0U", "time": 1743184726, "expires": 1743227926, "event": "message", "topic": "test1", "message": "Hello", "title": "Title", "tags": ["octopus"], "priority": 3, "click": "https://example.com/", "icon": "https://example.com/icon.png", "actions": [], "attachment": null}"""
+MSG = """{"id": "h6Y2hKA5sy0U", "time": 1743184726, "expires": 1743227926, "event": "message", "topic": "test1", "message": "Hello", "title": "Title", "tags": ["octopus"], "priority": 3, "click": "https://example.com/", "icon": "https://example.com/icon.png", "actions": [], "attachment": null, "sequence_id": "Mc3otamDNcpJ"}"""
 MSG_2 = """{"id": "h6Y2hKA5sy0U", "time": 1743184726, "expires": 1743227926, "event": "message", "topic": "test2", "message": "World", "title": "Title", "tags": ["octopus"], "priority": 5, "click": "https://example.com/", "actions": [], "attachment": null}"""
 
+MSG_CLEAR = """{"id": "h6Y2hKA5sy0U", "time": 1743184726, "expires": 1743227926, "event": "message_clear", "topic": "test1", "message": "Hello", "title": "Title", "tags": ["octopus"], "priority": 3, "click": "https://example.com/", "icon": "https://example.com/icon.png", "actions": [], "attachment": null, "sequence_id": "Mc3otamDNcpJ"}"""
+MSG_DELETE = """{"id": "h6Y2hKA5sy0U", "time": 1743184726, "expires": 1743227926, "event": "message_delete", "topic": "test1", "message": "Hello", "title": "Title", "tags": ["octopus"], "priority": 3, "click": "https://example.com/", "icon": "https://example.com/icon.png", "actions": [], "attachment": null, "sequence_id": "Mc3otamDNcpJ"}"""
+
 
 @pytest.fixture
 def mock_session() -> Generator[AsyncMock]:

tests/test_clear.py

@@ -0,0 +1,45 @@
+"""Tests for aiontfy."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock
+
+from yarl import URL
+
+from aiontfy import Event, Notification, Ntfy
+
+from .conftest import MSG_CLEAR
+
+
+async def test_clear_message(mock_session: AsyncMock) -> None:
+    """Test clearing a message to ntfy."""
+
+    mock_session.request.return_value.__aenter__.return_value.status = 200
+    mock_session.request.return_value.__aenter__.return_value.text.return_value = (
+        MSG_CLEAR
+    )
+
+    ntfy = Ntfy("http://example.com", mock_session)
+
+    resp = await ntfy.clear("mytopic", "Mc3otamDNcpJ")
+
+    assert resp == Notification(
+        id="h6Y2hKA5sy0U",
+        time=datetime(2025, 3, 28, 17, 58, 46, tzinfo=UTC),
+        expires=datetime(2025, 3, 29, 5, 58, 46, tzinfo=UTC),
+        event=Event.MESSAGE_CLEAR,
+        topic="test1",
+        message="Hello",
+        title="Title",
+        tags=["octopus"],
+        priority=3,
+        click=URL("https://example.com/"),
+        icon=URL("https://example.com/icon.png"),
+        actions=[],
+        attachment=None,
+        sequence_id="Mc3otamDNcpJ",
+    )
+
+    mock_session.request.assert_called_once_with(
+        "PUT",
+        URL("http://example.com/mytopic/Mc3otamDNcpJ/clear"),
+    )

tests/test_delete.py

@@ -0,0 +1,45 @@
+"""Tests for aiontfy."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock
+
+from yarl import URL
+
+from aiontfy import Event, Notification, Ntfy
+
+from .conftest import MSG_DELETE
+
+
+async def test_delete_message(mock_session: AsyncMock) -> None:
+    """Test deleting a message to ntfy."""
+
+    mock_session.request.return_value.__aenter__.return_value.status = 200
+    mock_session.request.return_value.__aenter__.return_value.text.return_value = (
+        MSG_DELETE
+    )
+
+    ntfy = Ntfy("http://example.com", mock_session)
+
+    resp = await ntfy.delete("mytopic", "Mc3otamDNcpJ")
+
+    assert resp == Notification(
+        id="h6Y2hKA5sy0U",
+        time=datetime(2025, 3, 28, 17, 58, 46, tzinfo=UTC),
+        expires=datetime(2025, 3, 29, 5, 58, 46, tzinfo=UTC),
+        event=Event.MESSAGE_DELETE,
+        topic="test1",
+        message="Hello",
+        title="Title",
+        tags=["octopus"],
+        priority=3,
+        click=URL("https://example.com/"),
+        icon=URL("https://example.com/icon.png"),
+        actions=[],
+        attachment=None,
+        sequence_id="Mc3otamDNcpJ",
+    )
+
+    mock_session.request.assert_called_once_with(
+        "DELETE",
+        URL("http://example.com/mytopic/Mc3otamDNcpJ"),
+    )

tests/test_publish.py

@@ -38,6 +38,7 @@ async def test_publish_message(mock_session: AsyncMock) -> None:
             "delay": None,
             "email": None,
             "call": None,
+            "sequence_id": None,
         },
     )
 
@@ -72,6 +73,7 @@ async def test_publish_basic_auth(mock_session: AsyncMock) -> None:
             "delay": None,
             "email": None,
             "call": None,
+            "sequence_id": None,
         },
     )
 
@@ -106,5 +108,6 @@ async def test_publish_bearer_auth(mock_session: AsyncMock) -> None:
             "delay": None,
             "email": None,
             "call": None,
+            "sequence_id": None,
         },
     )

tests/test_subscribe.py

@@ -45,6 +45,7 @@ async def test_subscribe_success(mock_ws: AsyncMock) -> None:
             icon=URL("https://example.com/icon.png"),
             actions=[],
             attachment=None,
+            sequence_id="Mc3otamDNcpJ",
         )
     )
 
@@ -112,6 +113,7 @@ async def test_subscribe_with_filters(mock_ws: AsyncMock) -> None:
             icon=URL("https://example.com/icon.png"),
             actions=[],
             attachment=None,
+            sequence_id="Mc3otamDNcpJ",
         )
     )
 
@@ -150,6 +152,7 @@ async def test_subscribe_multiple_topics(mock_ws: AsyncMock) -> None:
             icon=URL("https://example.com/icon.png"),
             actions=[],
             attachment=None,
+            sequence_id="Mc3otamDNcpJ",
         )
     )
     callback_mock.assert_any_call(
@@ -244,6 +247,7 @@ async def test_subscribe_basic_auth(mock_ws: AsyncMock) -> None:
             icon=URL("https://example.com/icon.png"),
             actions=[],
             attachment=None,
+            sequence_id="Mc3otamDNcpJ",
         )
     )
 
@@ -278,5 +282,6 @@ async def test_subscribe_bearer_auth(mock_ws: AsyncMock) -> None:
             icon=URL("https://example.com/icon.png"),
             actions=[],
             attachment=None,
+            sequence_id="Mc3otamDNcpJ",
         )
     )