feat: add status() method for delivery report lookup (v0.7.21)

Author: boxlinknet

CHANGELOG.md

@@ -11,6 +11,14 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.7.21] - 2026-03-05
+
+### Added
+- `status()` method on `KwtSMS`: looks up delivery status for a sent message via `/report/` endpoint
+- `tests/test_status.py`: three tests covering OK response, error enrichment, and network error handling
+
+---
+
 ## [0.7.20] - 2026-03-05
 
 ### Added

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kwtsms"
-version = "0.7.20"
+version = "0.7.21"
 description = "Python client for kwtSMS, the Kuwait SMS gateway trusted by top businesses to deliver messages worldwide, with private Sender ID, free API testing, and non-expiring credits."
 readme = "README.md"
 requires-python = ">=3.8"

src/kwtsms/__init__.py

@@ -10,6 +10,7 @@
     result = sms.send("96598765432", "Hello", sender="MY-APP")  # override sender
     report = sms.validate(["96598765432", "+96512345678"])
     balance = sms.balance()
+    delivery = sms.status(result["msg-id"])                  # delivery report
 
 Utility functions:
     from kwtsms import normalize_phone, clean_message, validate_phone_input
@@ -18,4 +19,4 @@
 from kwtsms._core import KwtSMS, clean_message, normalize_phone, validate_phone_input
 
 __all__ = ["KwtSMS", "normalize_phone", "clean_message", "validate_phone_input"]
-__version__ = "0.7.20"
+__version__ = "0.7.21"

src/kwtsms/_core.py

@@ -466,6 +466,32 @@ def balance(self) -> Optional[float]:
         ok, bal, _ = self.verify()
         return bal if ok else self._cached_balance
 
+    # ── status ────────────────────────────────────────────────────────────────
+
+    def status(self, msg_id: str) -> dict:
+        """
+        Get delivery status for a sent message via /report/.
+
+        Args:
+            msg_id: The message ID returned by send() in result["msg-id"].
+
+        Returns:
+            OK:    {"result": "OK", "msg-id": "...", "status": "DELIVERED", ...}
+            ERROR: {"result": "ERROR", "code": "ERR020", "description": "...", "action": "..."}
+
+        Common error codes:
+            ERR019: No delivery reports found
+            ERR020: Message ID does not exist
+            ERR021: Report not ready yet
+            ERR022: Try again after 24 hours
+        """
+        try:
+            data = _request("report", {**self._creds(), "msgid": msg_id}, self.log_file)
+        except RuntimeError as e:
+            return {"result": "ERROR", "code": "NETWORK", "description": str(e),
+                    "action": "Check your internet connection and try again."}
+        return _enrich_error(data)
+
     # ── senderids ─────────────────────────────────────────────────────────────
 
     def senderids(self) -> dict:

tests/test_status.py

@@ -0,0 +1,41 @@
+from unittest.mock import patch
+from kwtsms import KwtSMS
+
+def _client(**kwargs) -> KwtSMS:
+    defaults = dict(username="python_username", password="python_password",
+                    sender_id="TEST", log_file="")
+    defaults.update(kwargs)
+    return KwtSMS(**defaults)
+
+OK_RESPONSE = {
+    "result": "OK",
+    "msg-id": "abc123",
+    "status": "DELIVERED",
+    "delivered-at": 1700000000,
+}
+
+ERR020_RESPONSE = {
+    "result": "ERROR",
+    "code": "ERR020",
+    "description": "Message ID does not exist.",
+}
+
+class TestStatus:
+    def test_status_ok_returns_dict_with_result_ok(self):
+        with patch("kwtsms._core._request", return_value=OK_RESPONSE):
+            result = _client().status("abc123")
+        assert result["result"] == "OK"
+        assert result["msg-id"] == "abc123"
+        assert result["status"] == "DELIVERED"
+
+    def test_status_error_has_action(self):
+        with patch("kwtsms._core._request", return_value=ERR020_RESPONSE):
+            result = _client().status("bad-id")
+        assert result["result"] == "ERROR"
+        assert "action" in result
+
+    def test_status_network_error_returns_dict(self):
+        with patch("kwtsms._core._request", side_effect=RuntimeError("Timeout")):
+            result = _client().status("abc123")
+        assert result["result"] == "ERROR"
+        assert result["code"] == "NETWORK"