silon-sdk 0.2.0__py3-none-any.whl

silon/__init__.py

@@ -0,0 +1,63 @@
+"""Python SDK for the Silon messaging platform API.
+
+Quickstart::
+
+    from silon import Silon
+
+    client = Silon(api_key="sk_live_...", workspace="acme")
+    sent = client.messages.send(
+        channel="whatsapp",
+        to={"client_id": "cust_001"},
+        content={"body": "Your order has shipped"},
+    )
+    print(sent.id, sent.status)
+"""
+
+from . import types, webhooks
+from ._client import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, AsyncSilon, Silon
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    ErrorDetail,
+    GoneError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SilonError,
+    UnprocessableEntityError,
+    WebhookSignatureVerificationError,
+)
+from ._pagination import AsyncCursorPage, SyncCursorPage
+from ._version import __version__
+
+__all__ = [
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_TIMEOUT",
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncCursorPage",
+    "AsyncSilon",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "ErrorDetail",
+    "GoneError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Silon",
+    "SilonError",
+    "SyncCursorPage",
+    "UnprocessableEntityError",
+    "WebhookSignatureVerificationError",
+    "__version__",
+    "types",
+    "webhooks",
+]

silon/_client.py

@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import random
+import time
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._exceptions import APIConnectionError, APITimeoutError, SilonError, make_status_error
+from ._utils import parse_retry_after
+from ._version import __version__
+
+__all__ = ["DEFAULT_MAX_RETRIES", "DEFAULT_TIMEOUT", "AsyncSilon", "Silon"]
+
+DEFAULT_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+DEFAULT_MAX_RETRIES = 2
+
+_RETRYABLE_STATUSES = frozenset({429, 500, 502, 503, 504})
+_IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+_MAX_RETRY_DELAY = 30.0
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        workspace: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("SILON_API_KEY")
+        if not self.api_key:
+            raise SilonError(
+                "No API key provided. Pass api_key=... or set the SILON_API_KEY environment "
+                "variable. Create a key in the dashboard under Settings > API keys."
+            )
+        base_url = base_url or os.environ.get("SILON_BASE_URL")
+        workspace = workspace or os.environ.get("SILON_WORKSPACE")
+        if base_url is None and workspace:
+            base_url = f"https://{workspace}.silon.tech"
+        if base_url is None:
+            raise SilonError(
+                "No base URL. Pass workspace='<your-workspace>' (=> https://<workspace>"
+                ".silon.tech), base_url=..., or set SILON_WORKSPACE / SILON_BASE_URL."
+            )
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.default_headers = dict(default_headers or {})
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"silon-python/{__version__} python/{platform.python_version()}",
+        }
+        headers.update(self.default_headers)
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _should_retry(
+        self,
+        *,
+        method: str,
+        headers: Mapping[str, str],
+        attempt: int,
+        response: httpx.Response | None = None,
+    ) -> bool:
+        if attempt >= self.max_retries:
+            return False
+        # POST/PATCH are only replayed when the request carries an
+        # Idempotency-Key, so a retry can never double-send.
+        if method.upper() not in _IDEMPOTENT_METHODS and "Idempotency-Key" not in headers:
+            return False
+        return response is None or response.status_code in _RETRYABLE_STATUSES
+
+    def _retry_delay(self, response: httpx.Response | None, attempt: int) -> float:
+        delay = min(0.5 * 2**attempt, 8.0) + random.uniform(0, 0.25)
+        if response is not None:
+            advertised = parse_retry_after(response)
+            if advertised is not None:
+                delay = max(delay, advertised)
+        return max(0.0, min(delay, _MAX_RETRY_DELAY))
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Any:
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise SilonError(
+                f"Could not parse response body as JSON (HTTP {response.status_code})."
+            ) from exc
+
+
+class Silon(_BaseClient):
+    """Synchronous client for the Silon API.
+
+    Usage::
+
+        from silon import Silon
+
+        client = Silon(api_key="sk_live_...", workspace="acme")
+        sent = client.messages.send(
+            channel="whatsapp",
+            to={"client_id": "cust_001"},
+            content={"body": "Your order has shipped"},
+        )
+
+    Configuration falls back to the ``SILON_API_KEY``, ``SILON_WORKSPACE``
+    and ``SILON_BASE_URL`` environment variables.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        workspace: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            workspace=workspace,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+
+        from .resources import (
+            Auth,
+            Broadcasts,
+            Bulk,
+            ClientGroups,
+            Clients,
+            Events,
+            Messages,
+            Otp,
+            Profile,
+            Push,
+            Reports,
+            Suppressions,
+            Templates,
+            WebhookEndpoints,
+            WhatsAppTemplates,
+        )
+
+        self.messages = Messages(self)
+        self.broadcasts = Broadcasts(self)
+        self.otp = Otp(self)
+        self.clients = Clients(self)
+        self.client_groups = ClientGroups(self)
+        self.bulk = Bulk(self)
+        self.reports = Reports(self)
+        self.whatsapp_templates = WhatsAppTemplates(self)
+        self.templates = Templates(self)
+        self.webhook_endpoints = WebhookEndpoints(self)
+        self.events = Events(self)
+        self.suppressions = Suppressions(self)
+        self.push = Push(self)
+        self.profile = Profile(self)
+        self.auth = Auth(self)
+
+    # -- transport ---------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        files: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        request_headers = self._headers(headers)
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    method,
+                    self._url(path),
+                    params=params,
+                    json=json,
+                    files=files,
+                    headers=request_headers,
+                )
+            except httpx.TimeoutException as exc:
+                if self._should_retry(method=method, headers=request_headers, attempt=attempt):
+                    self._sleep(self._retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError() from exc
+            except httpx.HTTPError as exc:
+                if self._should_retry(method=method, headers=request_headers, attempt=attempt):
+                    self._sleep(self._retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                message = f"Connection error while requesting {path}: {exc}"
+                raise APIConnectionError(message) from exc
+
+            if response.status_code >= 400:
+                if self._should_retry(
+                    method=method, headers=request_headers, attempt=attempt, response=response
+                ):
+                    self._sleep(self._retry_delay(response, attempt))
+                    attempt += 1
+                    continue
+                raise make_status_error(response)
+            return self._parse(response)
+
+    def get(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        files: Any = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        return self.request("POST", path, json=json, files=files, params=params, headers=headers)
+
+    def patch(self, path: str, *, json: Any = None) -> Any:
+        return self.request("PATCH", path, json=json)
+
+    def put(self, path: str, *, json: Any = None) -> Any:
+        return self.request("PUT", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    # -- lifecycle ---------------------------------------------------------
+
+    @staticmethod
+    def _sleep(seconds: float) -> None:
+        time.sleep(seconds)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Silon:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncSilon(_BaseClient):
+    """Asynchronous client for the Silon API.
+
+    Usage::
+
+        from silon import AsyncSilon
+
+        async with AsyncSilon(api_key="sk_live_...", workspace="acme") as client:
+            sent = await client.messages.send(
+                channel="sms",
+                to={"phone_number": "+96512345678"},
+                content={"body": "Your code is 424242"},
+            )
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        workspace: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            workspace=workspace,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
+
+        from .resources import (
+            AsyncAuth,
+            AsyncBroadcasts,
+            AsyncBulk,
+            AsyncClientGroups,
+            AsyncClients,
+            AsyncEvents,
+            AsyncMessages,
+            AsyncOtp,
+            AsyncProfile,
+            AsyncPush,
+            AsyncReports,
+            AsyncSuppressions,
+            AsyncTemplates,
+            AsyncWebhookEndpoints,
+            AsyncWhatsAppTemplates,
+        )
+
+        self.messages = AsyncMessages(self)
+        self.broadcasts = AsyncBroadcasts(self)
+        self.otp = AsyncOtp(self)
+        self.clients = AsyncClients(self)
+        self.client_groups = AsyncClientGroups(self)
+        self.bulk = AsyncBulk(self)
+        self.reports = AsyncReports(self)
+        self.whatsapp_templates = AsyncWhatsAppTemplates(self)
+        self.templates = AsyncTemplates(self)
+        self.webhook_endpoints = AsyncWebhookEndpoints(self)
+        self.events = AsyncEvents(self)
+        self.suppressions = AsyncSuppressions(self)
+        self.push = AsyncPush(self)
+        self.profile = AsyncProfile(self)
+        self.auth = AsyncAuth(self)
+
+    # -- transport ---------------------------------------------------------
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        files: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        request_headers = self._headers(headers)
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    method,
+                    self._url(path),
+                    params=params,
+                    json=json,
+                    files=files,
+                    headers=request_headers,
+                )
+            except httpx.TimeoutException as exc:
+                if self._should_retry(method=method, headers=request_headers, attempt=attempt):
+                    await self._sleep(self._retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError() from exc
+            except httpx.HTTPError as exc:
+                if self._should_retry(method=method, headers=request_headers, attempt=attempt):
+                    await self._sleep(self._retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                message = f"Connection error while requesting {path}: {exc}"
+                raise APIConnectionError(message) from exc
+
+            if response.status_code >= 400:
+                if self._should_retry(
+                    method=method, headers=request_headers, attempt=attempt, response=response
+                ):
+                    await self._sleep(self._retry_delay(response, attempt))
+                    attempt += 1
+                    continue
+                raise make_status_error(response)
+            return self._parse(response)
+
+    async def get(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        files: Any = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        return await self.request(
+            "POST", path, json=json, files=files, params=params, headers=headers
+        )
+
+    async def patch(self, path: str, *, json: Any = None) -> Any:
+        return await self.request("PATCH", path, json=json)
+
+    async def put(self, path: str, *, json: Any = None) -> Any:
+        return await self.request("PUT", path, json=json)
+
+    async def delete(self, path: str) -> Any:
+        return await self.request("DELETE", path)
+
+    # -- lifecycle ---------------------------------------------------------
+
+    @staticmethod
+    async def _sleep(seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSilon:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()