fix: AsyncKwtSMS error handling, 200-number limit, logging, docstrings

Author: boxlinknet

pyproject.toml

@@ -47,3 +47,6 @@ dev = [
     "pytest-asyncio>=0.24.0",
     "pytest>=7.0",
 ]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"

src/kwtsms/_async.py

@@ -16,12 +16,14 @@ async def main():
 
 import json
 import os
+from datetime import datetime, timezone
 from typing import List, Optional, Union
 
 from kwtsms._core import (
     BASE_URL,
     _enrich_error,
     _load_env_file,
+    _write_log,
     clean_message,
     validate_phone_input,
 )
@@ -40,14 +42,34 @@ async def _async_request(endpoint: str, payload: dict, log_file: str = "") -> di
             "aiohttp is required for async usage. Install with: pip install kwtsms[async]"
         )
     url = BASE_URL + endpoint + "/"
-    async with aiohttp.ClientSession() as session:
-        async with session.post(url, json=payload,
-                                timeout=aiohttp.ClientTimeout(total=15)) as resp:
-            text = await resp.text()
-            try:
-                return json.loads(text)
-            except json.JSONDecodeError as exc:
-                raise RuntimeError(f"Invalid JSON response: {exc}") from exc
+    safe_payload = {k: ("***" if k == "password" else v) for k, v in payload.items()}
+    log_entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "endpoint": endpoint,
+        "request": safe_payload,
+        "response": None,
+        "ok": False,
+        "error": None,
+    }
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, json=payload,
+                                    timeout=aiohttp.ClientTimeout(total=15)) as resp:
+                text = await resp.text()
+                try:
+                    data = json.loads(text)
+                except json.JSONDecodeError as exc:
+                    log_entry["error"] = f"Invalid JSON response: {exc}"
+                    _write_log(log_file, log_entry)
+                    raise RuntimeError(f"Invalid JSON response: {exc}") from exc
+                log_entry["response"] = data
+                log_entry["ok"] = data.get("result") == "OK"
+                _write_log(log_file, log_entry)
+                return data
+    except aiohttp.ClientError as exc:
+        log_entry["error"] = f"Network error: {exc}"
+        _write_log(log_file, log_entry)
+        raise RuntimeError(f"Network error: {exc}") from exc
 
 
 class AsyncKwtSMS:
@@ -64,6 +86,16 @@ class AsyncKwtSMS:
 
     def __init__(self, username: str, password: str, sender_id: str = "KWT-SMS",
                  test_mode: bool = False, log_file: str = "kwtsms.log"):
+        """
+        Create an AsyncKwtSMS client.
+
+        Args:
+            username:  kwtSMS API username
+            password:  kwtSMS API password
+            sender_id: default Sender ID shown on recipient's phone
+            test_mode: if True, sends are billed as test (no credits consumed)
+            log_file:  path to JSONL request log file, or "" to disable logging
+        """
         if not username or not password:
             raise ValueError("username and password are required")
         self.username   = username
@@ -107,6 +139,7 @@ def _creds(self) -> dict:
 
     @property
     def purchased(self) -> Optional[float]:
+        """Total credits purchased. None before the first successful verify() call."""
         return self._cached_purchased
 
     async def verify(self) -> tuple:
@@ -125,7 +158,7 @@ async def verify(self) -> tuple:
             return False, None, str(exc)
 
     async def balance(self) -> Optional[float]:
-        """Get current balance. Returns None on error."""
+        """Get current balance. Returns None on error (or last cached value if available)."""
         ok, bal, _ = await self.verify()
         return bal if ok else self._cached_balance
 
@@ -134,6 +167,8 @@ async def send(self, mobile: Union[str, List[str]], message: str,
         """
         Send SMS to one or more numbers. Same contract as KwtSMS.send().
 
+        Note: Maximum 200 numbers per call. For larger lists, split into batches.
+
         Returns OK or ERROR dict; never raises.
         """
         effective_sender = sender or self.sender_id
@@ -154,6 +189,13 @@ async def send(self, mobile: Union[str, List[str]], message: str,
             return _enrich_error({"result": "ERROR", "code": "ERR_INVALID_INPUT",
                                   "description": description, "invalid": invalid})
 
+        if len(valid_numbers) > 200:
+            return _enrich_error({
+                "result": "ERROR",
+                "code": "ERR007",
+                "description": f"Too many numbers ({len(valid_numbers)}). Maximum 200 per call. For larger lists, call send() in batches.",
+            })
+
         cleaned = clean_message(message)
         if not cleaned:
             return _enrich_error({"result": "ERROR", "code": "ERR009",

tests/test_async.py

@@ -53,3 +53,10 @@ async def test_verify_network_error_returns_false(self):
             ok, balance, error = await _async_client().verify()
         assert ok is False
         assert "Timeout" in error
+
+    @pytest.mark.asyncio
+    async def test_send_too_many_numbers_returns_err007(self):
+        numbers = [f"9659{i:07d}" for i in range(201)]
+        result = await _async_client().send(numbers, "Hello")
+        assert result["result"] == "ERROR"
+        assert result["code"] == "ERR007"