sendara 0.2.0__py3-none-any.whl

sendara/__init__.py

@@ -0,0 +1,79 @@
+from . import models, webhooks
+from .async_client import AsyncSendara
+from .client import Sendara
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PermissionError_,
+    RateLimitError,
+    SendaraError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    ApiKey,
+    BillingState,
+    BimiDmarc,
+    BimiRecord,
+    BimiStatus,
+    Broadcast,
+    Channel,
+    Contact,
+    ContactList,
+    Domain,
+    Message,
+    MessageType,
+    SendResult,
+    Suppression,
+    Template,
+    TestRecipient,
+    Upload,
+    UsageSummary,
+    WebhookDelivery,
+    WebhookSubscription,
+)
+from .webhooks_verify import WebhookVerificationError
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Sendara",
+    "AsyncSendara",
+    "SendaraError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "PermissionError_",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "WebhookVerificationError",
+    "models",
+    "webhooks",
+    "Channel",
+    "MessageType",
+    "SendResult",
+    "Message",
+    "Broadcast",
+    "Suppression",
+    "Domain",
+    "ApiKey",
+    "UsageSummary",
+    "BillingState",
+    "Template",
+    "Contact",
+    "ContactList",
+    "WebhookSubscription",
+    "WebhookDelivery",
+    "Upload",
+    "TestRecipient",
+    "BimiStatus",
+    "BimiRecord",
+    "BimiDmarc",
+    "__version__",
+]

sendara/_async_http.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._config import ClientConfig
+from ._transport import JsonBody, PreparedRequest, RequestBuilder, connection_error
+
+
+class AsyncHTTP:
+    """Asynchronous transport over httpx.AsyncClient with retry/backoff."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._builder = RequestBuilder(config)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=self._builder.config.timeout
+        )
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._builder.config
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[JsonBody] = None,
+        files: Optional[Dict[str, Any]] = None,
+        idempotent: Optional[bool] = None,
+    ) -> Any:
+        prepared = self._builder.prepare(
+            method, path, json_body=json_body, files=files, idempotent=idempotent
+        )
+        return await self._send(prepared)
+
+    async def _send(self, prepared: PreparedRequest) -> Any:
+        attempt = 0
+        while True:
+            try:
+                response = await self._client.request(
+                    prepared.method,
+                    prepared.url,
+                    headers=prepared.headers,
+                    json=prepared.json_body if prepared.files is None else None,
+                    files=prepared.files,
+                    timeout=self._builder.config.timeout,
+                )
+            except httpx.HTTPError as exc:
+                if prepared.idempotent and self._builder.should_retry(attempt, None):
+                    await asyncio.sleep(self._builder.backoff_delay(attempt, None))
+                    attempt += 1
+                    continue
+                raise connection_error(exc) from None
+
+            headers = dict(response.headers)
+            if prepared.idempotent and self._builder.should_retry(
+                attempt, response.status_code
+            ):
+                retry_after = self._builder.retry_after_from_headers(headers)
+                await asyncio.sleep(self._builder.backoff_delay(attempt, retry_after))
+                attempt += 1
+                continue
+
+            return self._builder.interpret(
+                response.status_code, response.content, headers
+            )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHTTP":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()

sendara/_config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.sendara.dev"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_USER_AGENT = "sendara-python/0.2.0"
+
+RETRYABLE_STATUS = frozenset({408, 409, 429, 500, 502, 503, 504})
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+
+    def normalized(self) -> "ClientConfig":
+        return ClientConfig(
+            api_key=self.api_key,
+            base_url=self.base_url.rstrip("/"),
+            timeout=self.timeout,
+            max_retries=max(0, self.max_retries),
+        )

sendara/_params.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote, urlencode
+
+
+def query(params: Dict[str, Any]) -> str:
+    clean = {k: v for k, v in params.items() if v is not None and v != ""}
+    return f"?{urlencode(clean)}" if clean else ""
+
+
+def path_segment(value: str) -> str:
+    return quote(str(value), safe="")
+
+
+def email_send_body(
+    *,
+    to: str,
+    subject: str,
+    html: Optional[str] = None,
+    text: Optional[str] = None,
+    from_: Optional[str] = None,
+    message_type: Optional[str] = None,
+    template_id: Optional[str] = None,
+    template_vars: Optional[Dict[str, Any]] = None,
+    idempotency_key: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    test_send: bool = False,
+) -> Dict[str, Any]:
+    meta: Dict[str, Any] = dict(metadata or {})
+    if from_:
+        meta["from_email"] = from_
+    body: Dict[str, Any] = {
+        "channel": "email",
+        "destination": {"email": to},
+        "payload": {"subject": subject, "body_html": html, "body_text": text},
+    }
+    if message_type is not None:
+        body["message_type"] = message_type
+    if template_id is not None:
+        body["template_id"] = template_id
+    if template_vars is not None:
+        body["template_vars"] = template_vars
+    if idempotency_key is not None:
+        body["idempotency_key"] = idempotency_key
+    if meta:
+        body["metadata"] = meta
+    if test_send:
+        body["test_send"] = True
+    return body
+
+
+def sms_send_body(
+    *,
+    to: str,
+    body: str,
+    sender_id: Optional[str] = None,
+    message_type: Optional[str] = None,
+    idempotency_key: Optional[str] = None,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "channel": "sms",
+        "destination": {"phone_number": to},
+        "payload": {"body": body},
+    }
+    if message_type is not None:
+        payload["message_type"] = message_type
+    if idempotency_key is not None:
+        payload["idempotency_key"] = idempotency_key
+    if sender_id:
+        payload["metadata"] = {"sender_id": sender_id}
+    return payload

sendara/_sync_http.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._config import ClientConfig
+from ._transport import JsonBody, PreparedRequest, RequestBuilder, connection_error
+
+
+class SyncHTTP:
+    """Synchronous transport over httpx.Client with retry/backoff."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._builder = RequestBuilder(config)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=self._builder.config.timeout)
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._builder.config
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[JsonBody] = None,
+        files: Optional[Dict[str, Any]] = None,
+        idempotent: Optional[bool] = None,
+    ) -> Any:
+        prepared = self._builder.prepare(
+            method, path, json_body=json_body, files=files, idempotent=idempotent
+        )
+        return self._send(prepared)
+
+    def _send(self, prepared: PreparedRequest) -> Any:
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(
+                    prepared.method,
+                    prepared.url,
+                    headers=prepared.headers,
+                    json=prepared.json_body if prepared.files is None else None,
+                    files=prepared.files,
+                    timeout=self._builder.config.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if prepared.idempotent and self._builder.should_retry(attempt, None):
+                    time.sleep(self._builder.backoff_delay(attempt, None))
+                    attempt += 1
+                    continue
+                raise connection_error(exc) from None
+            except httpx.HTTPError as exc:
+                if prepared.idempotent and self._builder.should_retry(attempt, None):
+                    time.sleep(self._builder.backoff_delay(attempt, None))
+                    attempt += 1
+                    continue
+                raise connection_error(exc) from None
+
+            headers = dict(response.headers)
+            if prepared.idempotent and self._builder.should_retry(
+                attempt, response.status_code
+            ):
+                retry_after = self._builder.retry_after_from_headers(headers)
+                time.sleep(self._builder.backoff_delay(attempt, retry_after))
+                attempt += 1
+                continue
+
+            return self._builder.interpret(
+                response.status_code, response.content, headers
+            )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "SyncHTTP":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

sendara/_transport.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import json
+import random
+import uuid
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+from ._config import RETRYABLE_STATUS, DEFAULT_USER_AGENT, ClientConfig
+from .errors import (
+    APIConnectionError,
+    SendaraError,
+    error_from_response,
+)
+
+JsonBody = Any
+SAFE_METHODS = frozenset({"GET", "HEAD", "PUT", "DELETE"})
+
+
+@dataclass(frozen=True)
+class PreparedRequest:
+    method: str
+    url: str
+    headers: Dict[str, str]
+    json_body: Optional[JsonBody]
+    files: Optional[Dict[str, Any]]
+    idempotent: bool
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+def with_idempotency(body: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    payload = dict(body or {})
+    if not payload.get("idempotency_key"):
+        payload["idempotency_key"] = new_idempotency_key()
+    return payload
+
+
+class RequestBuilder:
+    """Builds prepared requests and interprets responses. Transport-agnostic so
+    the sync and async clients share identical request shapes and error mapping.
+    """
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config.normalized()
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._config
+
+    def prepare(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[JsonBody] = None,
+        files: Optional[Dict[str, Any]] = None,
+        idempotent: Optional[bool] = None,
+    ) -> PreparedRequest:
+        headers = {
+            "Authorization": f"Bearer {self._config.api_key}",
+            "Accept": "application/json",
+            "User-Agent": DEFAULT_USER_AGENT,
+        }
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+
+        is_idempotent = (
+            method.upper() in SAFE_METHODS if idempotent is None else idempotent
+        )
+        return PreparedRequest(
+            method=method.upper(),
+            url=f"{self._config.base_url}{path}",
+            headers=headers,
+            json_body=json_body,
+            files=files,
+            idempotent=is_idempotent,
+        )
+
+    def backoff_delay(self, attempt: int, retry_after: Optional[float]) -> float:
+        if retry_after is not None and retry_after >= 0:
+            return retry_after
+        base = min(0.5 * (2**attempt), 8.0)
+        return base + random.uniform(0, base * 0.25)
+
+    def should_retry(self, attempt: int, status: Optional[int]) -> bool:
+        if attempt >= self._config.max_retries:
+            return False
+        if status is None:
+            return True
+        return status in RETRYABLE_STATUS
+
+    def interpret(
+        self,
+        status: int,
+        body_bytes: bytes,
+        headers: Dict[str, str],
+    ) -> Any:
+        request_id = _header(headers, "x-request-id")
+        if 200 <= status < 300:
+            if status == 204 or not body_bytes:
+                return None
+            return json.loads(body_bytes)
+
+        code, message = _parse_error_envelope(body_bytes, status)
+        raise error_from_response(
+            status,
+            code,
+            message,
+            retry_after=_retry_after_seconds(headers),
+            request_id=request_id,
+        )
+
+    def retry_after_from_headers(self, headers: Dict[str, str]) -> Optional[float]:
+        return _retry_after_seconds(headers)
+
+
+def _header(headers: Dict[str, str], name: str) -> Optional[str]:
+    lowered = name.lower()
+    for key, value in headers.items():
+        if key.lower() == lowered:
+            return value
+    return None
+
+
+def _retry_after_seconds(headers: Dict[str, str]) -> Optional[float]:
+    raw = _header(headers, "retry-after")
+    if not raw:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def _parse_error_envelope(body_bytes: bytes, status: int) -> Tuple[str, str]:
+    if not body_bytes:
+        return ("http_error", f"HTTP {status}")
+    try:
+        payload = json.loads(body_bytes)
+    except ValueError:
+        return (
+            "http_error",
+            body_bytes.decode("utf-8", "replace")[:500] or f"HTTP {status}",
+        )
+    if isinstance(payload, dict):
+        err = payload.get("error")
+        if isinstance(err, dict):
+            return (
+                str(err.get("code", "error")),
+                str(err.get("message", f"HTTP {status}")),
+            )
+        if "message" in payload:
+            return (str(payload.get("code", "error")), str(payload["message"]))
+    return ("http_error", f"HTTP {status}")
+
+
+def connection_error(exc: Exception) -> SendaraError:
+    return APIConnectionError(f"Request failed: {exc}")

sendara/async_client.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+import httpx
+
+from ._async_http import AsyncHTTP
+from ._config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    ClientConfig,
+)
+from .async_resources import (
+    AsyncApiKeys,
+    AsyncBilling,
+    AsyncBroadcasts,
+    AsyncContacts,
+    AsyncDomains,
+    AsyncEmails,
+    AsyncLists,
+    AsyncMessages,
+    AsyncSms,
+    AsyncSuppressions,
+    AsyncTemplates,
+    AsyncTestRecipients,
+    AsyncUploads,
+    AsyncUsage,
+    AsyncWebhooks,
+)
+from .errors import SendaraError
+
+
+class AsyncSendara:
+    """Asynchronous client for the Sendara messaging API (httpx.AsyncClient).
+
+    Example:
+        import asyncio
+        from sendara import AsyncSendara
+
+        async def main():
+            async with AsyncSendara("sk_live_...") as client:
+                await client.emails.send(to="user@example.com", subject="Hi",
+                                         html="<p>Hi</p>")
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise SendaraError(0, "missing_api_key", "An API key is required")
+        config = ClientConfig(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = AsyncHTTP(config, http_client=http_client)
+
+        self.emails = AsyncEmails(self._http)
+        self.sms = AsyncSms(self._http)
+        self.broadcasts = AsyncBroadcasts(self._http)
+        self.messages = AsyncMessages(self._http)
+        self.suppressions = AsyncSuppressions(self._http)
+        self.domains = AsyncDomains(self._http)
+        self.api_keys = AsyncApiKeys(self._http)
+        self.usage = AsyncUsage(self._http)
+        self.billing = AsyncBilling(self._http)
+        self.templates = AsyncTemplates(self._http)
+        self.contacts = AsyncContacts(self._http)
+        self.lists = AsyncLists(self._http)
+        self.webhooks = AsyncWebhooks(self._http)
+        self.uploads = AsyncUploads(self._http)
+        self.test_recipients = AsyncTestRecipients(self._http)
+
+    async def send(self, request: dict) -> Any:
+        return await self.emails.send_raw(request)
+
+    async def send_batch(self, requests: List[dict]) -> Any:
+        return await self.emails.send_batch(requests)
+
+    async def request(self, method: str, path: str, body: Optional[Any] = None) -> Any:
+        return await self._http.request(method, path, json_body=body)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncSendara":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()