senderkit 0.1.0__py3-none-any.whl

senderkit/__init__.py

@@ -0,0 +1,95 @@
+"""SenderKit Python SDK.
+
+    from senderkit import SenderKit
+
+    with SenderKit(api_key="sk_test_...") as sk:
+        sk.send("welcome", "user@example.com", vars={"name": "Ada"})
+
+See :class:`SenderKit` / :class:`AsyncSenderKit` for the client, ``senderkit.errors``
+for the exception hierarchy, and :class:`WebhookVerifier` for inbound webhooks.
+"""
+
+from __future__ import annotations
+
+from . import errors
+from ._version import VERSION
+from .client import AsyncSenderKit, SenderKit
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    NetworkError,
+    PaymentRequiredError,
+    RateLimitError,
+    SenderKitError,
+    SignatureVerificationError,
+    TimeoutError,
+    ValidationError,
+)
+from .models import (
+    Attachment,
+    BatchResult,
+    Channel,
+    Context,
+    EmailContent,
+    Message,
+    MessageList,
+    PushContent,
+    RawSend,
+    RenderResult,
+    SendResult,
+    SmsContent,
+    TemplateDetail,
+    TemplateSend,
+    TemplateSummary,
+    TemplateVariable,
+    TemplateVersion,
+    WebPushContent,
+    Workspace,
+)
+from .webhooks import WebhookEvent, WebhookVerifier
+
+__version__ = VERSION
+
+__all__ = [
+    "VERSION",
+    "__version__",
+    "SenderKit",
+    "AsyncSenderKit",
+    "errors",
+    # Errors
+    "SenderKitError",
+    "APIError",
+    "AuthenticationError",
+    "ValidationError",
+    "PaymentRequiredError",
+    "ConflictError",
+    "RateLimitError",
+    "TimeoutError",
+    "NetworkError",
+    "SignatureVerificationError",
+    # Requests
+    "TemplateSend",
+    "RawSend",
+    "EmailContent",
+    "SmsContent",
+    "PushContent",
+    "WebPushContent",
+    "Attachment",
+    "Channel",
+    # Responses
+    "SendResult",
+    "BatchResult",
+    "Message",
+    "MessageList",
+    "TemplateSummary",
+    "TemplateDetail",
+    "TemplateVersion",
+    "TemplateVariable",
+    "RenderResult",
+    "Context",
+    "Workspace",
+    # Webhooks
+    "WebhookVerifier",
+    "WebhookEvent",
+]

senderkit/_http.py

@@ -0,0 +1,280 @@
+"""Internal HTTP transport: header construction, retries with backoff,
+idempotency, timeout/network mapping, and error-to-exception translation.
+
+Two thin transports — ``Transport`` (sync, ``httpx.Client``) and
+``AsyncTransport`` (``httpx.AsyncClient``) — share all policy via the module
+helpers below. Not part of the public API; the client and resources use it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import errors
+from ._version import VERSION
+
+RETRY_BASE_MS = 250
+RETRY_CAP_MS = 5_000
+
+
+def _is_retryable(status: int) -> bool:
+    """429 and 5xx (except 501 Not Implemented) are worth retrying."""
+    return status == 429 or (500 <= status < 600 and status != 501)
+
+
+def _build_headers(
+    api_key: str,
+    idempotency_key: Optional[str],
+    extra: Optional[Dict[str, str]],
+) -> Dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+        "User-Agent": f"senderkit-python/{VERSION}",
+    }
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _parse_retry_after(response: httpx.Response) -> Optional[float]:
+    value = response.headers.get("retry-after")
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _backoff_seconds(attempt: int, retry_after: Optional[float]) -> float:
+    """Full-jitter exponential backoff, capped at ``RETRY_CAP_MS``.
+
+    When the server sent ``Retry-After`` we wait at least that long (also capped),
+    so we never hammer ahead of an explicit instruction.
+    """
+    cap = RETRY_CAP_MS / 1000
+    ceiling = min(RETRY_CAP_MS, RETRY_BASE_MS * (2**attempt)) / 1000
+    jitter = random.uniform(0, ceiling)
+    if retry_after is not None:
+        return min(max(retry_after, jitter), cap)
+    return jitter
+
+
+def _clean_query(query: Optional[Dict[str, Any]]) -> Optional[Dict[str, str]]:
+    if not query:
+        return None
+    return {k: str(v) for k, v in query.items() if v is not None}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    status = response.status_code
+    if 200 <= status < 300:
+        return
+
+    code: Optional[str] = None
+    message: Optional[str] = None
+    issues: Any = None
+    try:
+        body = response.json()
+        err = body.get("error") if isinstance(body, dict) else None
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message")
+            issues = err.get("issues")
+    except (ValueError, json.JSONDecodeError):
+        pass
+
+    message = message or f"HTTP {status}"
+    request_id = response.headers.get("x-request-id")
+
+    if status in (401, 403):
+        raise errors.AuthenticationError(
+            message, status=status, code=code, issues=issues, request_id=request_id
+        )
+    if status in (400, 422):
+        raise errors.ValidationError(
+            message, status=status, code=code, issues=issues, request_id=request_id
+        )
+    if status == 402:
+        raise errors.PaymentRequiredError(
+            message, status=status, code=code, issues=issues, request_id=request_id
+        )
+    if status == 409:
+        raise errors.ConflictError(
+            message, status=status, code=code, issues=issues, request_id=request_id
+        )
+    if status == 429:
+        raise errors.RateLimitError(
+            message,
+            status=status,
+            code=code,
+            issues=issues,
+            request_id=request_id,
+            retry_after=_parse_retry_after(response),
+        )
+    raise errors.APIError(message, status=status, code=code, issues=issues, request_id=request_id)
+
+
+class _BaseTransport:
+    def __init__(self, api_key: str, base_url: str, max_retries: int) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+
+    def _url(self, path: str) -> str:
+        return self._base_url + (path if path.startswith("/") else f"/{path}")
+
+    def _prepare(
+        self,
+        body: Optional[Dict[str, Any]],
+        idempotency_key: Optional[str],
+        headers: Optional[Dict[str, str]],
+        accept: Optional[str],
+    ) -> tuple[Dict[str, str], Optional[bytes]]:
+        h = _build_headers(self._api_key, idempotency_key, headers)
+        if accept:
+            h["Accept"] = accept
+        content: Optional[bytes] = None
+        if body is not None:
+            content = json.dumps(body).encode()
+            h["Content-Type"] = "application/json"
+        return h, content
+
+
+class Transport(_BaseTransport):
+    """Synchronous transport over ``httpx.Client``."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, max_retries)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        accept: Optional[str] = None,
+    ) -> httpx.Response:
+        url = self._url(path)
+        h, content = self._prepare(body, idempotency_key, headers, accept)
+        params = _clean_query(query)
+        attempts = 1 + self._max_retries
+
+        for attempt in range(attempts):
+            try:
+                response = self._client.request(
+                    method, url, params=params, content=content, headers=h
+                )
+            except httpx.TimeoutException as exc:
+                raise errors.TimeoutError(f"Request timed out: {exc}") from exc
+            except httpx.RequestError as exc:
+                if attempt < attempts - 1:
+                    time.sleep(_backoff_seconds(attempt, None))
+                    continue
+                raise errors.NetworkError(f"Network error: {exc}") from exc
+
+            if _is_retryable(response.status_code) and attempt < attempts - 1:
+                time.sleep(_backoff_seconds(attempt, _parse_retry_after(response)))
+                continue
+
+            _raise_for_status(response)
+            return response
+
+        raise errors.NetworkError("Request failed after retries")  # pragma: no cover
+
+    def request_json(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        response = self.request(method, path, **kwargs)
+        if not response.content:
+            return {}
+        data = response.json()
+        return data if isinstance(data, dict) else {"data": data}
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncTransport(_BaseTransport):
+    """Asynchronous transport over ``httpx.AsyncClient``."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, max_retries)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        accept: Optional[str] = None,
+    ) -> httpx.Response:
+        url = self._url(path)
+        h, content = self._prepare(body, idempotency_key, headers, accept)
+        params = _clean_query(query)
+        attempts = 1 + self._max_retries
+
+        for attempt in range(attempts):
+            try:
+                response = await self._client.request(
+                    method, url, params=params, content=content, headers=h
+                )
+            except httpx.TimeoutException as exc:
+                raise errors.TimeoutError(f"Request timed out: {exc}") from exc
+            except httpx.RequestError as exc:
+                if attempt < attempts - 1:
+                    await asyncio.sleep(_backoff_seconds(attempt, None))
+                    continue
+                raise errors.NetworkError(f"Network error: {exc}") from exc
+
+            if _is_retryable(response.status_code) and attempt < attempts - 1:
+                await asyncio.sleep(_backoff_seconds(attempt, _parse_retry_after(response)))
+                continue
+
+            _raise_for_status(response)
+            return response
+
+        raise errors.NetworkError("Request failed after retries")  # pragma: no cover
+
+    async def request_json(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        response = await self.request(method, path, **kwargs)
+        if not response.content:
+            return {}
+        data = response.json()
+        return data if isinstance(data, dict) else {"data": data}
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()

senderkit/_serialize.py

@@ -0,0 +1,184 @@
+"""Turn request DTOs into the JSON shapes the API expects.
+
+Centralizes the snake_case → camelCase mapping, ``None`` pruning, datetime →
+ISO-8601 conversion, and enum unwrapping so the client and resources never
+hand-build wire dicts. Kept explicit (rather than reflection-based) so the
+mapping is auditable against ``openapi.yaml``.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Optional, Tuple
+
+from .models import (
+    Attachment,
+    Channel,
+    ChannelLike,
+    Content,
+    EmailContent,
+    PushContent,
+    RawSend,
+    SmsContent,
+    TemplateSend,
+    WebPushContent,
+)
+
+
+def _iso(value: Any) -> Any:
+    """ISO-8601 string for a datetime; pass strings (and None) through."""
+    if isinstance(value, datetime):
+        return value.isoformat()
+    return value
+
+
+def _channel_value(channel: Optional[ChannelLike]) -> Optional[str]:
+    if channel is None:
+        return None
+    return channel.value if isinstance(channel, Channel) else str(channel)
+
+
+def _prune(d: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop keys whose value is ``None`` (omit-if-absent semantics)."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _attachment_to_wire(a: Attachment) -> Dict[str, Any]:
+    return _prune(
+        {
+            "filename": a.filename,
+            "contentType": a.content_type,
+            "content": a.content,
+            "inline": a.inline,
+            "contentId": a.content_id,
+        }
+    )
+
+
+def channel_for_content(content: Content) -> str:
+    """Infer the channel string from a content instance."""
+    if isinstance(content, EmailContent):
+        return "email"
+    if isinstance(content, SmsContent):
+        return "sms"
+    if isinstance(content, PushContent):
+        return "push"
+    if isinstance(content, WebPushContent):
+        return "web-push"
+    raise TypeError(f"Unsupported content type: {type(content)!r}")
+
+
+def content_to_wire(content: Content) -> Dict[str, Any]:
+    if isinstance(content, EmailContent):
+        return _prune(
+            {
+                "subject": content.subject,
+                "preheader": content.preheader,
+                "html": content.html,
+                "text": content.text,
+                "cc": content.cc,
+                "bcc": content.bcc,
+                "replyTo": content.reply_to,
+                "attachments": (
+                    [_attachment_to_wire(a) for a in content.attachments]
+                    if content.attachments
+                    else None
+                ),
+            }
+        )
+    if isinstance(content, SmsContent):
+        return {"body": content.body}
+    if isinstance(content, PushContent):
+        return _prune(
+            {
+                "title": content.title,
+                "body": content.body,
+                "data": content.data,
+                "badge": content.badge,
+                "sound": content.sound,
+            }
+        )
+    if isinstance(content, WebPushContent):
+        return _prune(
+            {
+                "title": content.title,
+                "body": content.body,
+                "icon": content.icon,
+                "clickUrl": content.click_url,
+                "data": content.data,
+                "badge": content.badge,
+            }
+        )
+    raise TypeError(f"Unsupported content type: {type(content)!r}")
+
+
+def template_send_to_body(req: TemplateSend) -> Dict[str, Any]:
+    return _prune(
+        {
+            "template": req.template,
+            "to": req.to,
+            "vars": req.vars,
+            "version": req.version,
+            "channel": _channel_value(req.channel),
+            "metadata": req.metadata,
+            "scheduledAt": _iso(req.scheduled_at),
+            "cc": req.cc,
+            "bcc": req.bcc,
+            "replyTo": req.reply_to,
+            "attachments": (
+                [_attachment_to_wire(a) for a in req.attachments] if req.attachments else None
+            ),
+        }
+    )
+
+
+def raw_send_to_body(req: RawSend) -> Dict[str, Any]:
+    channel = _channel_value(req.channel) or channel_for_content(req.content)
+    return _prune(
+        {
+            "channel": channel,
+            "to": req.to,
+            "from": req.from_,
+            "interpolate": req.interpolate,
+            "content": content_to_wire(req.content),
+            "vars": req.vars,
+            "metadata": req.metadata,
+            "scheduledAt": _iso(req.scheduled_at),
+        }
+    )
+
+
+def build_send(req: Any) -> Tuple[Dict[str, Any], Optional[str]]:
+    """Serialize a send request, returning ``(body, idempotency_key)``."""
+    if isinstance(req, TemplateSend):
+        return template_send_to_body(req), req.idempotency_key
+    if isinstance(req, RawSend):
+        return raw_send_to_body(req), req.idempotency_key
+    raise TypeError(f"Expected TemplateSend or RawSend, got {type(req)!r}")
+
+
+def list_messages_query(
+    *,
+    limit: Optional[int],
+    cursor: Optional[str],
+    status: Optional[str],
+    channel: Optional[ChannelLike],
+    template: Optional[str],
+    metadata: Optional[Dict[str, Any]],
+    tail: Optional[str],
+) -> Dict[str, Any]:
+    """Build the query dict for ``GET /v1/messages``, including ``metadata[key]``."""
+    query: Dict[str, Any] = _prune(
+        {
+            "limit": limit,
+            "cursor": cursor,
+            "status": status.value if isinstance(status, Channel) else status,
+            "channel": _channel_value(channel),
+            "template": template,
+            "tail": tail,
+        }
+    )
+    if metadata:
+        for key, value in metadata.items():
+            query[f"metadata[{key}]"] = value
+    return query

senderkit/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SDK version, surfaced in the User-Agent header."""
+
+VERSION = "0.1.0"  # x-release-please-version