kalourmade-sailup 0.1.0__tar.gz

kalourmade_sailup-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: kalourmade-sailup
+Version: 0.1.0
+Summary: Official Python SDK for the Sailup SMS gateway
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

kalourmade_sailup-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "kalourmade-sailup"
+version = "0.1.0"
+description = "Official Python SDK for the Sailup SMS gateway"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

kalourmade_sailup-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kalourmade_sailup-0.1.0/src/kalourmade_sailup/__init__.py

@@ -0,0 +1,27 @@
+from .client import SailupClient
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    InvalidSignatureError,
+    NetworkError,
+    RateLimitError,
+    SailupError,
+    ValidationError,
+)
+from .models import DeliveryStatus, Message, Page
+from .webhooks import Webhooks
+
+__all__ = [
+    "SailupClient",
+    "Webhooks",
+    "Message",
+    "Page",
+    "DeliveryStatus",
+    "ApiError",
+    "AuthenticationError",
+    "InvalidSignatureError",
+    "NetworkError",
+    "RateLimitError",
+    "SailupError",
+    "ValidationError",
+]

kalourmade_sailup-0.1.0/src/kalourmade_sailup/client.py

@@ -0,0 +1,13 @@
+from .http import HttpxTransport
+from .sms import SmsResource
+
+
+class SailupClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.sailup.io/v1",
+        timeout: float = 30.0,
+    ):
+        transport = HttpxTransport(api_key, base_url, timeout)
+        self.sms = SmsResource(transport)

kalourmade_sailup-0.1.0/src/kalourmade_sailup/error_mapping.py

@@ -0,0 +1,16 @@
+from .exceptions import ApiError, AuthenticationError, RateLimitError, ValidationError
+
+
+def raise_for_status(status: int, raw_body: str) -> None:
+    if status < 400:
+        return
+
+    message = f"Sailup API error (status {status})"
+
+    if status == 401:
+        raise AuthenticationError(message)
+    if status == 429:
+        raise RateLimitError(message)
+    if status in (400, 422):
+        raise ValidationError(message)
+    raise ApiError(status, raw_body, message)

kalourmade_sailup-0.1.0/src/kalourmade_sailup/exceptions.py

@@ -0,0 +1,31 @@
+class SailupError(Exception):
+    """Base exception for all Sailup SDK errors."""
+
+
+class AuthenticationError(SailupError):
+    """Raised on 401 responses."""
+
+
+class ValidationError(SailupError):
+    """Raised on 400/422 responses."""
+
+
+class RateLimitError(SailupError):
+    """Raised on 429 responses."""
+
+
+class ApiError(SailupError):
+    """Raised on other 4xx/5xx responses."""
+
+    def __init__(self, status_code: int, raw_body: str, message: str):
+        super().__init__(message)
+        self.status_code = status_code
+        self.raw_body = raw_body
+
+
+class NetworkError(SailupError):
+    """Raised when the request could not reach Sailup."""
+
+
+class InvalidSignatureError(SailupError):
+    """Raised when webhook signature verification fails."""

kalourmade_sailup-0.1.0/src/kalourmade_sailup/http.py

@@ -0,0 +1,44 @@
+from typing import Optional, Protocol
+
+import httpx
+
+from .exceptions import NetworkError
+
+
+class Transport(Protocol):
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[dict] = None,
+        json_body: Optional[dict] = None,
+    ) -> tuple[int, str]:
+        ...
+
+
+class HttpxTransport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.sailup.io/v1",
+        timeout: float = 30.0,
+    ):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[dict] = None,
+        json_body: Optional[dict] = None,
+    ) -> tuple[int, str]:
+        try:
+            response = self._client.request(method, path, params=query, json=json_body)
+        except httpx.HTTPError as exc:
+            raise NetworkError(str(exc)) from exc
+
+        return response.status_code, response.text

kalourmade_sailup-0.1.0/src/kalourmade_sailup/models.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+
+class DeliveryStatus(str, Enum):
+    PENDING = "pending"
+    DELIVERED = "delivered"
+    FAILED = "failed"
+    EXPIRED = "expired"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True)
+class Message:
+    id: str
+    to: List[str]
+    sender: Optional[str]
+    body: str
+    quantity: int
+    delivery_status: DeliveryStatus
+    created_at: str
+
+    @staticmethod
+    def from_dict(data: dict) -> "Message":
+        to = data["to"] if isinstance(data["to"], list) else [data["to"]]
+        return Message(
+            id=data["id"],
+            to=to,
+            sender=data.get("sender"),
+            body=data["body"],
+            quantity=data["quantity"],
+            delivery_status=DeliveryStatus(data["delivery_status"]),
+            created_at=data["created_at"],
+        )
+
+
+@dataclass(frozen=True)
+class Page:
+    count: int
+    next: Optional[str]
+    previous: Optional[str]
+    results: List[Message]
+
+    @staticmethod
+    def from_dict(data: dict) -> "Page":
+        return Page(
+            count=data["count"],
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=[Message.from_dict(m) for m in data["results"]],
+        )

kalourmade_sailup-0.1.0/src/kalourmade_sailup/sms.py

@@ -0,0 +1,29 @@
+import json
+
+from .error_mapping import raise_for_status
+from .http import Transport
+from .models import Message, Page
+
+
+class SmsResource:
+    def __init__(self, transport: Transport):
+        self._transport = transport
+
+    def send(self, from_: str, to: list, body: str) -> Message:
+        status, raw = self._transport.request(
+            "POST", "/sms/", json_body={"from": from_, "to": to, "body": body}
+        )
+        raise_for_status(status, raw)
+        return Message.from_dict(json.loads(raw))
+
+    def list(self, page: int = 1, page_size: int = 30) -> Page:
+        status, raw = self._transport.request(
+            "GET", "/sms/", query={"page": page, "page_size": page_size}
+        )
+        raise_for_status(status, raw)
+        return Page.from_dict(json.loads(raw))
+
+    def get(self, message_id: str) -> Message:
+        status, raw = self._transport.request("GET", f"/sms/{message_id}/")
+        raise_for_status(status, raw)
+        return Message.from_dict(json.loads(raw))

kalourmade_sailup-0.1.0/src/kalourmade_sailup/webhooks.py

@@ -0,0 +1,26 @@
+import hashlib
+import hmac
+import json
+from typing import Mapping
+
+from .exceptions import InvalidSignatureError
+
+
+class Webhooks:
+    @staticmethod
+    def verify(raw_body: str, headers: Mapping[str, str], secret: str) -> dict:
+        headers_lower = {k.lower(): v for k, v in headers.items()}
+        signature = headers_lower.get("x-sailup-signature")
+        timestamp = headers_lower.get("x-sailup-timestamp")
+
+        if not signature or not timestamp:
+            raise InvalidSignatureError("Missing signature headers")
+
+        expected = hmac.new(
+            secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256
+        ).hexdigest()
+
+        if not hmac.compare_digest(expected, signature):
+            raise InvalidSignatureError("Signature mismatch")
+
+        return json.loads(raw_body)

kalourmade_sailup-0.1.0/src/kalourmade_sailup.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: kalourmade-sailup
+Version: 0.1.0
+Summary: Official Python SDK for the Sailup SMS gateway
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

kalourmade_sailup-0.1.0/src/kalourmade_sailup.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+pyproject.toml
+src/kalourmade_sailup/__init__.py
+src/kalourmade_sailup/client.py
+src/kalourmade_sailup/error_mapping.py
+src/kalourmade_sailup/exceptions.py
+src/kalourmade_sailup/http.py
+src/kalourmade_sailup/models.py
+src/kalourmade_sailup/sms.py
+src/kalourmade_sailup/webhooks.py
+src/kalourmade_sailup.egg-info/PKG-INFO
+src/kalourmade_sailup.egg-info/SOURCES.txt
+src/kalourmade_sailup.egg-info/dependency_links.txt
+src/kalourmade_sailup.egg-info/requires.txt
+src/kalourmade_sailup.egg-info/top_level.txt
+tests/test_client.py
+tests/test_error_mapping.py
+tests/test_exceptions.py
+tests/test_models.py
+tests/test_sms.py
+tests/test_webhooks.py

kalourmade_sailup-0.1.0/src/kalourmade_sailup.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kalourmade_sailup-0.1.0/src/kalourmade_sailup.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.24
+
+[dev]
+pytest>=7.0

kalourmade_sailup-0.1.0/src/kalourmade_sailup.egg-info/top_level.txt

@@ -0,0 +1 @@
+kalourmade_sailup

kalourmade_sailup-0.1.0/tests/test_client.py

@@ -0,0 +1,8 @@
+from kalourmade_sailup.client import SailupClient
+from kalourmade_sailup.sms import SmsResource
+
+
+def test_client_exposes_sms_resource():
+    client = SailupClient("sailup_test_key")
+
+    assert isinstance(client.sms, SmsResource)

kalourmade_sailup-0.1.0/tests/test_error_mapping.py

@@ -0,0 +1,36 @@
+import pytest
+
+from kalourmade_sailup.error_mapping import raise_for_status
+from kalourmade_sailup.exceptions import (
+    ApiError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+def test_ok_status_does_not_raise():
+    raise_for_status(200, "{}")
+
+
+def test_401_raises_authentication_error():
+    with pytest.raises(AuthenticationError):
+        raise_for_status(401, "{}")
+
+
+def test_429_raises_rate_limit_error():
+    with pytest.raises(RateLimitError):
+        raise_for_status(429, "{}")
+
+
+def test_400_and_422_raise_validation_error():
+    with pytest.raises(ValidationError):
+        raise_for_status(422, "{}")
+
+
+def test_other_4xx_5xx_raises_api_error_with_status_and_body():
+    with pytest.raises(ApiError) as exc_info:
+        raise_for_status(503, '{"detail":"down"}')
+
+    assert exc_info.value.status_code == 503
+    assert exc_info.value.raw_body == '{"detail":"down"}'

kalourmade_sailup-0.1.0/tests/test_exceptions.py

@@ -0,0 +1,26 @@
+from kalourmade_sailup.exceptions import (
+    ApiError,
+    AuthenticationError,
+    InvalidSignatureError,
+    NetworkError,
+    RateLimitError,
+    SailupError,
+    ValidationError,
+)
+
+
+def test_all_exceptions_extend_sailup_error():
+    assert issubclass(AuthenticationError, SailupError)
+    assert issubclass(ValidationError, SailupError)
+    assert issubclass(RateLimitError, SailupError)
+    assert issubclass(NetworkError, SailupError)
+    assert issubclass(InvalidSignatureError, SailupError)
+    assert issubclass(ApiError, SailupError)
+
+
+def test_api_error_carries_status_and_raw_body():
+    error = ApiError(503, '{"detail":"down"}', "Sailup API error (status 503)")
+
+    assert error.status_code == 503
+    assert error.raw_body == '{"detail":"down"}'
+    assert str(error) == "Sailup API error (status 503)"

kalourmade_sailup-0.1.0/tests/test_models.py

@@ -0,0 +1,44 @@
+from kalourmade_sailup.models import DeliveryStatus, Message, Page
+
+
+def message_dict(**overrides):
+    base = {
+        "id": "msg_123",
+        "to": ["233241234567"],
+        "sender": "MyBrand",
+        "body": "Hello",
+        "quantity": 1,
+        "delivery_status": "delivered",
+        "created_at": "2026-09-12T10:00:00Z",
+    }
+    base.update(overrides)
+    return base
+
+
+def test_message_from_dict_maps_all_fields():
+    message = Message.from_dict(message_dict())
+
+    assert message.id == "msg_123"
+    assert message.to == ["233241234567"]
+    assert message.delivery_status == DeliveryStatus.DELIVERED
+
+
+def test_message_from_dict_wraps_scalar_to_in_list():
+    message = Message.from_dict(message_dict(to="233241234567", sender=None))
+
+    assert message.to == ["233241234567"]
+    assert message.sender is None
+
+
+def test_page_from_dict_maps_envelope_and_results():
+    page = Page.from_dict({
+        "count": 1,
+        "next": None,
+        "previous": None,
+        "results": [message_dict()],
+    })
+
+    assert page.count == 1
+    assert page.next is None
+    assert len(page.results) == 1
+    assert isinstance(page.results[0], Message)

kalourmade_sailup-0.1.0/tests/test_sms.py

@@ -0,0 +1,70 @@
+import json
+
+import pytest
+
+from kalourmade_sailup.exceptions import AuthenticationError
+from kalourmade_sailup.sms import SmsResource
+from tests.fakes import FakeTransport
+
+
+def message_json():
+    return json.dumps({
+        "id": "msg_123",
+        "to": ["233241234567"],
+        "sender": "MyBrand",
+        "body": "Hello",
+        "quantity": 1,
+        "delivery_status": "pending",
+        "created_at": "2026-09-12T10:00:00Z",
+    })
+
+
+def test_send_posts_to_sms_and_returns_message():
+    transport = FakeTransport([(202, message_json())])
+    resource = SmsResource(transport)
+
+    message = resource.send("MyBrand", ["233241234567"], "Hello")
+
+    assert message.id == "msg_123"
+    assert transport.requests[0]["method"] == "POST"
+    assert transport.requests[0]["path"] == "/sms/"
+    assert transport.requests[0]["json_body"] == {
+        "from": "MyBrand",
+        "to": ["233241234567"],
+        "body": "Hello",
+    }
+
+
+def test_list_gets_sms_with_pagination_query():
+    envelope = json.dumps({
+        "count": 1,
+        "next": None,
+        "previous": None,
+        "results": [json.loads(message_json())],
+    })
+    transport = FakeTransport([(200, envelope)])
+    resource = SmsResource(transport)
+
+    page = resource.list(page=2, page_size=50)
+
+    assert page.count == 1
+    assert len(page.results) == 1
+    assert transport.requests[0]["query"] == {"page": 2, "page_size": 50}
+
+
+def test_get_fetches_single_message_by_id():
+    transport = FakeTransport([(200, message_json())])
+    resource = SmsResource(transport)
+
+    message = resource.get("msg_123")
+
+    assert message.id == "msg_123"
+    assert transport.requests[0]["path"] == "/sms/msg_123/"
+
+
+def test_error_status_raises_mapped_exception():
+    transport = FakeTransport([(401, "{}")])
+    resource = SmsResource(transport)
+
+    with pytest.raises(AuthenticationError):
+        resource.get("msg_123")

kalourmade_sailup-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,47 @@
+import hashlib
+import hmac
+import json
+
+import pytest
+
+from kalourmade_sailup.exceptions import InvalidSignatureError
+from kalourmade_sailup.webhooks import Webhooks
+
+SECRET = "whsec_test"
+
+
+def sign(timestamp: str, raw_body: str) -> str:
+    return hmac.new(SECRET.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
+
+
+def test_verify_returns_decoded_payload_for_valid_signature():
+    raw_body = json.dumps({"event": "message.delivered", "data": {"message_id": "msg_123"}})
+    timestamp = "1700000000"
+    signature = sign(timestamp, raw_body)
+
+    event = Webhooks.verify(
+        raw_body,
+        {"X-Sailup-Signature": signature, "X-Sailup-Timestamp": timestamp},
+        SECRET,
+    )
+
+    assert event["event"] == "message.delivered"
+
+
+def test_verify_raises_on_tampered_body():
+    raw_body = json.dumps({"event": "message.delivered"})
+    timestamp = "1700000000"
+    signature = sign(timestamp, raw_body)
+    tampered = json.dumps({"event": "message.failed"})
+
+    with pytest.raises(InvalidSignatureError):
+        Webhooks.verify(
+            tampered,
+            {"X-Sailup-Signature": signature, "X-Sailup-Timestamp": timestamp},
+            SECRET,
+        )
+
+
+def test_verify_raises_on_missing_headers():
+    with pytest.raises(InvalidSignatureError):
+        Webhooks.verify("{}", {}, SECRET)