opensms 0.1.0__py3-none-any.whl

opensms/__init__.py

@@ -0,0 +1,30 @@
+"""Official Python client for OpenSMS, the prepaid SMS API.
+
+    from opensms import Opensms
+
+    client = Opensms(api_key="sk_test_...")
+    client.messages.send(to="+254700000012", text="Your order has shipped")
+"""
+
+from ._transport import Transport, TransportRequest, TransportResponse, urllib_transport
+from ._version import __version__
+from .client import Opensms
+from .errors import OpensmsError
+from .models import Page
+from .pagination import paginate
+from .signature import SIGNATURE_HEADER, construct_event, verify_signature
+
+__all__ = [
+    "Opensms",
+    "OpensmsError",
+    "Page",
+    "paginate",
+    "verify_signature",
+    "construct_event",
+    "SIGNATURE_HEADER",
+    "Transport",
+    "TransportRequest",
+    "TransportResponse",
+    "urllib_transport",
+    "__version__",
+]

opensms/_serialize.py

@@ -0,0 +1,60 @@
+"""Internal helpers that turn Python values into the exact wire format the API
+expects: path segments, query strings and JSON bodies. Not part of the public
+API."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote
+
+
+def path_id(value: Any, name: str = "id") -> str:
+    """Validate a non-empty id and URL-escape it as one path segment."""
+    if value is None or str(value).strip() == "":
+        raise ValueError(f"{name} is required")
+    return quote(str(value), safe="")
+
+
+def to_rfc3339(value: Any) -> Any:
+    """Serialize ``datetime`` as RFC 3339 UTC (``2026-09-24T10:00:00Z``).
+
+    A naive ``datetime`` is taken to be UTC. ``date`` becomes ``YYYY-MM-DD``.
+    Strings pass through unchanged.
+    """
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        text = value.astimezone(timezone.utc).isoformat()
+        return text.replace("+00:00", "Z")
+    if isinstance(value, date):
+        return value.isoformat()
+    return value
+
+
+def prune(body: Mapping[str, Any]) -> Dict[str, Any]:
+    """Drop keys whose value is ``None`` so unset optionals are absent, never
+    ``null`` (the API rejects unknown fields and treats null differently)."""
+    return {k: v for k, v in body.items() if v is not None}
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple)):
+        return ",".join(_query_value(v) for v in value)
+    value = to_rfc3339(value)
+    return str(value)
+
+
+def build_query(params: Optional[Mapping[str, Any]]) -> str:
+    """Build ``?a=1&b=2`` from params, skipping ``None``. Lists are joined with
+    commas. ``+`` is encoded as ``%2B``. Returns ``""`` when nothing is set."""
+    if not params:
+        return ""
+    parts = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        parts.append(f"{quote(key, safe='')}={quote(_query_value(value), safe=',')}")
+    return "?" + "&".join(parts) if parts else ""

opensms/_transport.py

@@ -0,0 +1,260 @@
+"""HTTP transport: the only code that touches the network.
+
+Owns authentication headers, JSON encoding, the Idempotency-Key, timeouts,
+retries with backoff, and turning non-2xx responses into
+:class:`~opensms.errors.OpensmsError`. The default network layer uses only the
+standard library (``urllib``); tests inject a transport callable instead.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import http.client
+import json
+import random
+import socket
+import time
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from ._serialize import build_query
+from ._version import __version__
+from .errors import OpensmsError
+
+DEFAULT_BASE_URL = "https://api.opensms.io"
+USER_AGENT = f"opensms-python/{__version__}"
+
+#: Statuses that may be retried (when the request is safe to repeat).
+RETRYABLE_STATUSES = frozenset({429, 500, 502, 503, 504})
+#: A ``Retry-After`` above this many seconds is not waited for.
+MAX_RETRY_AFTER = 60.0
+_BACKOFF_BASE = 0.5
+_BACKOFF_CAP = 8.0
+
+
+@dataclass
+class TransportRequest:
+    """One HTTP attempt handed to a transport callable."""
+
+    method: str
+    url: str
+    headers: Dict[str, str]
+    body: Optional[bytes]
+    timeout: float
+
+
+@dataclass
+class TransportResponse:
+    """What a transport callable returns for any HTTP status (including
+    4xx and 5xx). Header names are matched case-insensitively."""
+
+    status: int
+    headers: Mapping[str, str] = field(default_factory=dict)
+    body: bytes = b""
+
+    def header(self, name: str) -> Optional[str]:
+        lower = name.lower()
+        for key, value in self.headers.items():
+            if key.lower() == lower:
+                return value
+        return None
+
+
+#: A transport performs one HTTP attempt. It returns a response for every
+#: status and raises (any ``OSError``, ``http.client.HTTPException`` or
+#: ``TimeoutError``) only when no response was received.
+Transport = Callable[[TransportRequest], TransportResponse]
+
+_NETWORK_ERRORS = (OSError, http.client.HTTPException, TimeoutError, socket.timeout)
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:  # type: ignore[override]
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def urllib_transport(request: TransportRequest) -> TransportResponse:
+    """Default transport built on ``urllib.request``."""
+    req = urllib.request.Request(
+        request.url, data=request.body, method=request.method, headers=request.headers
+    )
+    try:
+        with _opener.open(req, timeout=request.timeout) as resp:
+            return TransportResponse(resp.status, dict(resp.headers.items()), resp.read())
+    except urllib.error.HTTPError as err:
+        try:
+            body = err.read()
+        finally:
+            err.close()
+        headers = dict(err.headers.items()) if err.headers else {}
+        return TransportResponse(err.code, headers, body)
+
+
+def parse_retry_after(value: Optional[str], now: Optional[float] = None) -> Optional[float]:
+    """Parse ``Retry-After`` as integer seconds or an HTTP date."""
+    if value is None:
+        return None
+    value = value.strip()
+    if not value:
+        return None
+    try:
+        return max(0.0, float(int(value)))
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError, IndexError):
+        return None
+    if when is None:
+        return None
+    current = time.time() if now is None else now
+    return max(0.0, when.timestamp() - current)
+
+
+def error_from_response(resp: TransportResponse) -> OpensmsError:
+    """Map a non-2xx response (problem+json or anything else) to an error."""
+    text = resp.body.decode("utf-8", "replace") if resp.body else ""
+    payload: Any = None
+    if text:
+        try:
+            payload = json.loads(text)
+        except ValueError:
+            payload = None
+    retry_after = parse_retry_after(resp.header("Retry-After"))
+    request_id = resp.header("X-Request-ID") or None
+    if isinstance(payload, dict):
+        detail = payload.get("detail") if isinstance(payload.get("detail"), str) else None
+        title = payload.get("title") if isinstance(payload.get("title"), str) else None
+        message = detail or title or f"OpenSMS request failed with status {resp.status}"
+        errors = payload.get("errors") if isinstance(payload.get("errors"), dict) else None
+        return OpensmsError(
+            resp.status,
+            message,
+            type=payload.get("type"),
+            title=title,
+            detail=detail,
+            code=payload.get("code"),
+            trace_id=payload.get("trace_id"),
+            errors=errors,
+            request_id=request_id,
+            retry_after=retry_after,
+            body=payload,
+        )
+    return OpensmsError(
+        resp.status,
+        f"OpenSMS request failed with status {resp.status}",
+        request_id=request_id,
+        retry_after=retry_after,
+        body=payload if payload is not None else text,
+    )
+
+
+class HttpTransport:
+    """Performs authenticated requests with retries. Shared by all resources."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[Transport] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> None:
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+        self._api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._transport: Transport = transport or urllib_transport
+        self._sleep: Callable[[float], None] = sleep or time.sleep
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        raw_body: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+        idempotent: bool = False,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Send one API call and return the decoded JSON (``None`` for 204).
+
+        ``idempotent=True`` marks a method that supports Idempotency-Key: the
+        caller's key (or a fresh UUIDv4) is sent on every attempt of this call.
+        """
+        url = f"{self.base_url}{path}{build_query(query)}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        body: Optional[bytes] = None
+        if raw_body is not None:
+            body = raw_body
+            headers["Content-Type"] = content_type or "application/octet-stream"
+        elif json_body is not None:
+            body = json.dumps(json_body, separators=(",", ":")).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if idempotent or idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+
+        method = method.upper()
+        can_retry = method in ("GET", "PUT", "PATCH", "DELETE", "HEAD") or (
+            method == "POST" and "Idempotency-Key" in headers
+        )
+
+        attempt = 0
+        while True:
+            attempt += 1
+            req = TransportRequest(method, url, dict(headers), body, self.timeout)
+            try:
+                resp = self._transport(req)
+            except OpensmsError:
+                raise
+            except _NETWORK_ERRORS as exc:
+                if can_retry and attempt <= self.max_retries:
+                    self._sleep(self._backoff(attempt))
+                    continue
+                raise OpensmsError(0, f"OpenSMS request failed: {exc}") from exc
+
+            if 200 <= resp.status < 300:
+                return self._decode(resp)
+
+            error = error_from_response(resp)
+            if not (can_retry and resp.status in RETRYABLE_STATUSES and attempt <= self.max_retries):
+                raise error
+            if error.retry_after is not None:
+                if error.retry_after > MAX_RETRY_AFTER:
+                    raise error
+                delay = error.retry_after
+            else:
+                delay = self._backoff(attempt)
+            self._sleep(delay)
+
+    @staticmethod
+    def _backoff(retry_number: int) -> float:
+        """Exponential backoff with full jitter for retry ``n`` (1-based)."""
+        ceiling = min(_BACKOFF_CAP, _BACKOFF_BASE * (2 ** (retry_number - 1)))
+        return random.uniform(0.0, ceiling)
+
+    @staticmethod
+    def _decode(resp: TransportResponse) -> Any:
+        if resp.status == 204 or not resp.body:
+            return None
+        text = resp.body.decode("utf-8")
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text

opensms/_version.py

@@ -0,0 +1,3 @@
+"""Package version, shared by the User-Agent header and packaging metadata."""
+
+__version__ = "0.1.0"

opensms/client.py

@@ -0,0 +1,127 @@
+"""The OpenSMS client: validates the key and wires the transport into every
+resource."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterator, Optional, TypeVar
+
+from ._transport import DEFAULT_BASE_URL, HttpTransport, Transport
+from .models import Page
+from .pagination import paginate
+from .resources.analytics import Analytics
+from .resources.batches import Batches
+from .resources.compliance import Compliance
+from .resources.contact_groups import ContactGroups
+from .resources.contacts import Contacts
+from .resources.countries import Countries
+from .resources.inbound import Inbound
+from .resources.lookups import Lookups
+from .resources.messages import Messages
+from .resources.numbers import Numbers
+from .resources.otp import Otp
+from .resources.pricing import Pricing
+from .resources.sandbox import Sandbox
+from .resources.sender_ids import SenderIds
+from .resources.suppressions import Suppressions
+from .resources.templates import Templates
+from .resources.wallet import Wallet
+from .resources.webhooks import Webhooks
+
+T = TypeVar("T")
+
+_PREFIXES = {"sk_test_": "sandbox", "sk_live_": "live"}
+
+
+def _environment_for(api_key: Any) -> str:
+    """Mirror the server's ``auth.ValidSecret``: a known prefix and more than
+    12 characters after it."""
+    if not isinstance(api_key, str) or not api_key:
+        raise ValueError("api_key is required")
+    for prefix, environment in _PREFIXES.items():
+        if api_key.startswith(prefix):
+            if len(api_key) - len(prefix) > 12:
+                return environment
+            break
+    raise ValueError("api_key must be an OpenSMS secret key (sk_test_... or sk_live_...)")
+
+
+class Opensms:
+    """OpenSMS API client.
+
+    Example::
+
+        from opensms import Opensms
+
+        client = Opensms(api_key="sk_test_...")
+        message = client.messages.send(to="+254700000012", text="Hello")
+        print(message["id"], message["status"])
+
+    Args:
+        api_key: ``sk_test_...`` (sandbox) or ``sk_live_...`` (live). Checked
+            locally; a malformed key raises ``ValueError`` with no request.
+        base_url: API origin, default ``https://api.opensms.io``.
+        timeout: Seconds per attempt (connect and read), default 30.
+        max_retries: Retries after the first attempt, default 2. ``0``
+            disables retries.
+        transport: Optional callable performing one HTTP attempt (see
+            :data:`opensms.Transport`); defaults to the ``urllib`` transport.
+        sleep: Optional replacement for ``time.sleep`` between retries.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[Transport] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> None:
+        self._environment = _environment_for(api_key)
+        self._http = HttpTransport(
+            api_key,
+            base_url=base_url or DEFAULT_BASE_URL,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+            sleep=sleep,
+        )
+        self.messages = Messages(self._http)
+        self.batches = Batches(self._http)
+        self.otp = Otp(self._http)
+        self.lookups = Lookups(self._http)
+        self.contacts = Contacts(self._http)
+        self.contact_groups = ContactGroups(self._http)
+        self.templates = Templates(self._http)
+        self.webhooks = Webhooks(self._http)
+        self.inbound = Inbound(self._http)
+        self.numbers = Numbers(self._http)
+        self.sender_ids = SenderIds(self._http)
+        self.suppressions = Suppressions(self._http)
+        self.compliance = Compliance(self._http)
+        self.wallet = Wallet(self._http)
+        self.pricing = Pricing(self._http)
+        self.analytics = Analytics(self._http)
+        self.sandbox = Sandbox(self._http)
+        self.countries = Countries(self._http)
+
+    @property
+    def environment(self) -> str:
+        """``"sandbox"`` for ``sk_test_`` keys, ``"live"`` for ``sk_live_``."""
+        return self._environment
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def paginate(self, list_method: Callable[..., "Page[T]"], *args: Any, **params: Any) -> Iterator[T]:
+        """Iterate every item of a cursor list lazily::
+
+            for message in client.paginate(client.messages.list, limit=50):
+                ...
+        """
+        return paginate(list_method, *args, **params)
+
+    def __repr__(self) -> str:
+        return f"Opensms(environment={self._environment!r}, base_url={self._http.base_url!r})"

opensms/errors.py

@@ -0,0 +1,62 @@
+"""Error type raised by the SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class OpensmsError(Exception):
+    """Raised for every non-2xx API response, for transport failures that
+    survive all retries, and for webhook signature failures.
+
+    The fields mirror the API's RFC 9457 problem+json body. Most API errors
+    carry no ``code``, so branch on :attr:`status` first and use
+    :attr:`detail` for display. Insufficient scope is ``401`` on messages and
+    OTP but ``403`` everywhere else.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        *,
+        type: Optional[str] = None,
+        title: Optional[str] = None,
+        detail: Optional[str] = None,
+        code: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        errors: Optional[Dict[str, List[str]]] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        #: HTTP status code. ``0`` means no response (network error, timeout,
+        #: or a webhook signature failure).
+        self.status = status
+        #: Human readable message: ``detail``, else ``title``, else a generic text.
+        self.message = message
+        #: Problem ``type`` URI, usually ``about:blank``.
+        self.type = type
+        #: Problem ``title`` such as ``Bad Request``.
+        self.title = title
+        #: Problem ``detail``, the specific human readable reason.
+        self.detail = detail
+        #: Machine readable ``code`` when the handler sets one (most do not).
+        self.code = code
+        #: Problem ``trace_id``, when present.
+        self.trace_id = trace_id
+        #: Field validation errors, ``{field: [messages]}``, when present.
+        self.errors = errors
+        #: ``X-Request-ID`` response header (message and OTP admission rejections).
+        self.request_id = request_id
+        #: ``Retry-After`` in seconds, when the server sent it.
+        self.retry_after = retry_after
+        #: Raw decoded body (dict) or raw text when the body was not JSON.
+        self.body = body
+
+    def __repr__(self) -> str:
+        return (
+            f"OpensmsError(status={self.status!r}, message={self.message!r}, "
+            f"code={self.code!r})"
+        )