joinsimplesms 2.8.0__py3-none-any.whl

joinsimplesms/__init__.py

@@ -0,0 +1,131 @@
+"""joinsimplesms - the official Python client for SimpleSMS (joinsimplesms.com).
+
+SMS, phone verification, and phone numbers. Standard library only.
+
+    from joinsimplesms import SimpleSMS
+
+    client = SimpleSMS()  # reads SIMPLESMS_API_KEY
+    client.messages.send(to="+15005550006", text="Hello from SimpleSMS")
+
+SimpleSMS was called Delivered until 2026-10. ``Delivered`` and
+``DeliveredError`` are kept as deprecated aliases of ``SimpleSMS`` and
+``SimpleSMSError``, and ``DELIVERED_API_KEY`` / ``DELIVERED_BASE_URL`` /
+``DELIVERED_FROM`` are still read when the ``SIMPLESMS_*`` names are unset.
+"""
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Any, Callable, Dict, Optional, Union
+
+from ._client import BaseClient, Response, Transport, _env, urllib_transport
+from ._errors import SimpleSMSError
+from ._resources import (
+    Automations,
+    BalanceResource,
+    Consent,
+    Contacts,
+    Customers,
+    Events,
+    LookupResource,
+    Messages,
+    Numbers,
+    Registrations,
+    Schedules,
+    Verify,
+    Webhooks,
+)
+from ._version import VERSION
+from .webhooks import EVENT_ID_HEADERS, SIGNATURE_HEADERS, event_id_from_headers, signature_from_headers, verify_webhook
+
+
+class SimpleSMS(BaseClient):
+    """The SimpleSMS client.
+
+    :param api_key: defaults to the ``SIMPLESMS_API_KEY`` environment variable.
+    :param default_from: the number ``messages.send`` uses when you omit
+        ``from_``. Defaults to ``SIMPLESMS_FROM``, else your account's only
+        active number (looked up once; an error if you have several).
+    :param base_url: defaults to ``https://api.joinsimplesms.com``.
+    :param max_retries: retries for transient failures (429, 5xx, network).
+    :param timeout: per-request timeout, seconds.
+    :param transport: swap the HTTP layer (tests, tracing, proxies).
+    """
+
+    #: ``SimpleSMS.webhooks.verify(...)`` works without a client; an instance
+    #: gets its own ``webhooks`` with the endpoint methods too.
+    webhooks: Webhooks = Webhooks()
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        default_from: Optional[str] = None,
+        base_url: Optional[str] = None,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        transport: Optional[Transport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        super().__init__(
+            api_key, base_url=base_url, max_retries=max_retries, timeout=timeout, transport=transport, sleep=sleep
+        )
+        self._default_from = default_from or _env("SIMPLESMS_FROM", "DELIVERED_FROM")
+        self._from_lock = threading.Lock()
+        self.messages = Messages(self)
+        self.verify = Verify(self)
+        self.numbers = Numbers(self)
+        self.lookup = LookupResource(self)
+        self.balance = BalanceResource(self)
+        self.events = Events(self)
+        self.consent = Consent(self)
+        self.customers = Customers(self)
+        self.contacts = Contacts(self)
+        self.automations = Automations(self)
+        self.schedules = Schedules(self)
+        self.registrations = Registrations(self)
+        self.webhooks = Webhooks(self)
+
+    def _resolve_from(self) -> str:
+        if self._default_from:
+            return self._default_from
+        with self._from_lock:
+            if not self._default_from:
+                active = [n["phone_number"] for n in self.numbers.list()["data"] if n.get("status") == "active"]
+                if len(active) != 1:
+                    raise SimpleSMSError(
+                        "Pass from_=... (or set SIMPLESMS_FROM): your account has "
+                        + (f"{len(active)} numbers." if active else "no numbers yet."),
+                        code="invalid_request",
+                        status=0,
+                        param="from",
+                    )
+                self._default_from = active[0]
+        return self._default_from
+
+
+#: Deprecated alias of :class:`SimpleSMS` (the product's name until 2026-10).
+#: The same class, so existing ``from ... import Delivered`` code keeps working.
+Delivered = SimpleSMS
+#: Deprecated alias of :class:`SimpleSMSError`; ``except DeliveredError`` still catches.
+DeliveredError = SimpleSMSError
+
+__version__ = VERSION
+
+__all__ = [
+    "SimpleSMS",
+    "SimpleSMSError",
+    "Delivered",
+    "DeliveredError",
+    "verify_webhook",
+    "signature_from_headers",
+    "event_id_from_headers",
+    "SIGNATURE_HEADERS",
+    "EVENT_ID_HEADERS",
+    "Response",
+    "Transport",
+    "urllib_transport",
+    "VERSION",
+    "__version__",
+]

joinsimplesms/_client.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import json
+import os
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Mapping, NamedTuple, Optional
+
+from ._errors import SimpleSMSError
+from ._version import VERSION
+
+DEFAULT_BASE_URL = "https://api.joinsimplesms.com"
+
+
+class Response(NamedTuple):
+    status: int
+    #: Header names lowercased.
+    headers: Mapping[str, str]
+    body: bytes
+
+
+#: (method, url, headers, body, timeout) -> Response. Raise on network failure.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Response]
+
+
+def urllib_transport(
+    method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float
+) -> Response:
+    """The default transport: the standard library, nothing to install."""
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # noqa: S310 (https by default)
+            return Response(res.status, {k.lower(): v for k, v in res.headers.items()}, res.read())
+    except urllib.error.HTTPError as err:
+        # 4xx/5xx still carry the API's JSON error body.
+        return Response(err.code, {k.lower(): v for k, v in err.headers.items()}, err.read())
+
+
+def _query(params: Mapping[str, Any]) -> str:
+    pairs = {k: v for k, v in params.items() if v is not None}
+    if not pairs:
+        return ""
+    return "?" + urllib.parse.urlencode({k: str(v).lower() if isinstance(v, bool) else v for k, v in pairs.items()})
+
+
+def _quote(segment: str) -> str:
+    return urllib.parse.quote(segment, safe="")
+
+
+def _env(*names: str) -> Optional[str]:
+    """The first of these environment variables that is set and non-empty.
+
+    The first name is the current one; the rest are deprecated names kept so
+    that deployments configured before a rename keep working.
+    """
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+class BaseClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        transport: Optional[Transport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        # SIMPLESMS_API_KEY first; names from before the rename still work.
+        key = api_key or _env("SIMPLESMS_API_KEY", "DELIVERED_API_KEY", "RESMS_API_KEY")
+        if not key:
+            raise SimpleSMSError(
+                "No SimpleSMS key. Pass one to SimpleSMS(...) or set SIMPLESMS_API_KEY. "
+                "Get one free at https://joinsimplesms.com/console",
+                code="invalid_api_key",
+                status=0,
+            )
+        self._api_key = key
+        self.base_url = (
+            base_url or _env("SIMPLESMS_BASE_URL", "DELIVERED_BASE_URL", "RESMS_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._transport: Transport = transport or urllib_transport
+        self._sleep = sleep
+
+    @property
+    def is_test_mode(self) -> bool:
+        """True when this client is using a sandbox key."""
+        return self._api_key.startswith((
+            ("ssms_sk_test_", "dsms_sk_test_", "resms_sk_test_")
+        ))
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        retryable: bool = False,
+        raw: bool = False,
+    ) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"joinsimplesms-python/{VERSION}",
+            "Accept": "application/json",
+        }
+        data: Optional[bytes] = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            # Sent as given: resources omit unset fields themselves, so an
+            # explicit None (e.g. unassigning a number) reaches the API as null.
+            data = json.dumps(dict(body)).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        url = f"{self.base_url}/v1{path}"
+
+        last: Optional[SimpleSMSError] = None
+        for attempt in range(self.max_retries + 1):
+            if attempt > 0 and last is not None:
+                self._sleep(self._backoff(attempt, last))
+            try:
+                res = self._transport(method, url, dict(headers), data, self.timeout)
+            except (socket.timeout, TimeoutError) as exc:
+                last = SimpleSMSError(f"Request timed out after {self.timeout}s", code="connection_error", status=0)
+                last.__cause__ = exc
+            except (urllib.error.URLError, OSError, ConnectionError) as exc:
+                last = SimpleSMSError(f"Could not reach the SimpleSMS API: {exc}", code="connection_error", status=0)
+                last.__cause__ = exc
+            else:
+                if 200 <= res.status < 300:
+                    if raw:
+                        return res.body.decode("utf-8")
+                    return json.loads(res.body.decode("utf-8")) if res.body else {}
+                last = self._error_from(res)
+
+            # Retry only what is safe: a POST without an idempotency key is
+            # never resent, and a verification cooldown is policy, not a blip.
+            if not retryable or not last.retryable:
+                break
+            if last.code == "rate_limited" and path.startswith("/verify"):
+                break
+        assert last is not None
+        raise last
+
+    @staticmethod
+    def _backoff(attempt: int, err: SimpleSMSError) -> float:
+        if err.retry_after is not None and err.retry_after >= 0:
+            return float(err.retry_after)
+        base: float = min(0.25 * float(2**attempt), 4.0)
+        return base + random.uniform(0, base / 4)
+
+    @staticmethod
+    def _error_from(res: Response) -> SimpleSMSError:
+        try:
+            payload = json.loads(res.body.decode("utf-8")) if res.body else {}
+        except ValueError:
+            payload = {}
+        err = payload.get("error") if isinstance(payload, dict) else None
+        err = err if isinstance(err, dict) else {}
+        retry_after: Optional[float] = None
+        if err.get("retry_after") is not None:
+            retry_after = float(err["retry_after"])
+        elif res.headers.get("retry-after"):
+            try:
+                retry_after = float(res.headers["retry-after"])
+            except ValueError:
+                retry_after = None
+        return SimpleSMSError(
+            err.get("message") or f"Request failed with status {res.status}",
+            code=err.get("code") or ("internal_error" if res.status >= 500 else "invalid_request"),
+            status=res.status,
+            param=err.get("param"),
+            retry_after=retry_after,
+            reason=err.get("reason"),
+            balance_micro_usd=err.get("balance_micro_usd"),
+            required_micro_usd=err.get("required_micro_usd"),
+            top_up_url=err.get("top_up_url"),
+            send_after=err.get("send_after"),
+            recipient_local_time=err.get("recipient_local_time"),
+            timezone=err.get("timezone"),
+            message_id=err.get("message_id"),
+        )
+
+
+def new_idempotency_key() -> str:
+    return f"sdk_{uuid.uuid4().hex}"
+
+
+__all__ = ["BaseClient", "Response", "Transport", "urllib_transport", "new_idempotency_key", "_query", "_quote"]

joinsimplesms/_errors.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SimpleSMSError(Exception):
+    """Every failure the client raises.
+
+    ``code`` is the API's machine-readable error code (``"rate_limited"``,
+    ``"invalid_request"``, ...), plus two the client adds itself:
+    ``"connection_error"`` (the API was unreachable or timed out) and
+    ``"invalid_signature"`` (a webhook failed verification).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        status: int,
+        param: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        reason: Optional[str] = None,
+        balance_micro_usd: Optional[int] = None,
+        required_micro_usd: Optional[int] = None,
+        top_up_url: Optional[str] = None,
+        send_after: Optional[str] = None,
+        recipient_local_time: Optional[str] = None,
+        timezone: Optional[str] = None,
+        message_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        #: Which request field was wrong, when the API could tell.
+        self.param = param
+        #: Seconds to wait, on rate limits.
+        self.retry_after = retry_after
+        #: Why a verification was blocked.
+        self.reason = reason
+        #: ``insufficient_credits`` only: your balance, in millionths of a dollar.
+        self.balance_micro_usd = balance_micro_usd
+        #: ``insufficient_credits`` only: what the call costs, in millionths of a dollar.
+        self.required_micro_usd = required_micro_usd
+        #: ``insufficient_credits`` only: where to add credits.
+        self.top_up_url = top_up_url
+        #: ``quiet_hours`` only: when the message may be sent (ISO timestamp).
+        self.send_after = send_after
+        #: ``quiet_hours`` only: the recipient's local time, 24-hour "HH:MM".
+        self.recipient_local_time = recipient_local_time
+        #: ``quiet_hours`` only: the IANA time zone read from the number's area code.
+        self.timezone = timezone
+        #: The blocked message stored in your log for this refusal, when there is one.
+        self.message_id = message_id
+
+    @property
+    def retryable(self) -> bool:
+        """True when retrying the same call later could plausibly succeed."""
+        return (
+            self.status >= 500
+            or self.code in ("rate_limited", "idempotency_in_progress", "carrier_error", "connection_error")
+        )
+
+    def __repr__(self) -> str:
+        return f"SimpleSMSError(code={self.code!r}, status={self.status}, message={self.message!r})"