senderkit 0.1.0__py3-none-any.whl

senderkit/client.py

@@ -0,0 +1,305 @@
+"""The public client: ``SenderKit`` (sync) and ``AsyncSenderKit`` (async).
+
+Both expose the same surface as the TypeScript and PHP SDKs — ``send``,
+``send_raw``, ``send_batch``, ``context``, plus the ``messages`` and
+``templates`` resource namespaces — and both work as (async) context managers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+import httpx
+
+from . import errors
+from ._http import AsyncTransport, Transport
+from ._serialize import build_send
+from .models import (
+    BatchResult,
+    ChannelLike,
+    Content,
+    Context,
+    RawSend,
+    ScheduledAt,
+    SendResult,
+    TemplateSend,
+)
+from .resources import AsyncMessages, AsyncTemplates, Messages, Templates
+
+DEFAULT_BASE_URL = "https://api.senderkit.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+SendItem = Union[TemplateSend, RawSend]
+
+
+def _mode_for_key(api_key: str) -> str:
+    return "test" if api_key.startswith("sk_test_") else "live"
+
+
+def _batch_key(base: Optional[str], item: SendItem, index: int) -> str:
+    """Per-item idempotency key: ``{base}-{index}`` if a base was given, else the
+    item's own key, else a fresh UUID."""
+    if base:
+        return f"{base}-{index}"
+    return item.idempotency_key or str(uuid.uuid4())
+
+
+class SenderKit:
+    """Synchronous SenderKit client.
+
+    ``timeout`` is in seconds (httpx convention; the TS/PHP SDKs use milliseconds).
+    Pass your own ``httpx.Client`` to control proxies, TLS, or connection pooling.
+    """
+
+    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.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.mode = _mode_for_key(api_key)
+        self._transport = Transport(api_key, base_url, timeout, max_retries, http_client)
+        self.messages = Messages(self._transport)
+        self.templates = Templates(self._transport)
+
+    def send(
+        self,
+        template: str,
+        to: str,
+        *,
+        vars: Optional[Dict[str, Any]] = None,
+        version: Optional[int] = None,
+        channel: Optional[ChannelLike] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        scheduled_at: Optional[ScheduledAt] = None,
+        cc: Optional[List[str]] = None,
+        bcc: Optional[List[str]] = None,
+        reply_to: Optional[str] = None,
+        attachments: Optional[list] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> SendResult:
+        """Send a stored template to one recipient."""
+        return self._send(
+            TemplateSend(
+                template=template,
+                to=to,
+                vars=vars,
+                version=version,
+                channel=channel,
+                metadata=metadata,
+                scheduled_at=scheduled_at,
+                cc=cc,
+                bcc=bcc,
+                reply_to=reply_to,
+                attachments=attachments,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def send_raw(
+        self,
+        to: str,
+        content: Content,
+        *,
+        channel: Optional[ChannelLike] = None,
+        from_: Optional[str] = None,
+        interpolate: Optional[bool] = None,
+        vars: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        scheduled_at: Optional[ScheduledAt] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> SendResult:
+        """Send inline content (no template). ``channel`` is inferred from ``content``."""
+        return self._send(
+            RawSend(
+                to=to,
+                content=content,
+                channel=channel,
+                from_=from_,
+                interpolate=interpolate,
+                vars=vars,
+                metadata=metadata,
+                scheduled_at=scheduled_at,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def _send(self, request: SendItem, idempotency_key: Optional[str] = None) -> SendResult:
+        body, own_key = build_send(request)
+        key = idempotency_key or own_key or str(uuid.uuid4())
+        data = self._transport.request_json("POST", "/v1/send", body=body, idempotency_key=key)
+        return SendResult.from_dict(data)
+
+    def send_batch(
+        self,
+        requests: Sequence[SendItem],
+        *,
+        concurrency: int = 5,
+        idempotency_key: Optional[str] = None,
+    ) -> List[BatchResult]:
+        """Send many messages concurrently. Each result is positionally aligned
+        with ``requests``; a per-item failure becomes a ``BatchResult(ok=False)``
+        rather than aborting the batch."""
+        results: List[Optional[BatchResult]] = [None] * len(requests)
+
+        def run(index: int, request: SendItem) -> BatchResult:
+            try:
+                key = _batch_key(idempotency_key, request, index)
+                result = self._send(request, idempotency_key=key)
+                return BatchResult(ok=True, index=index, result=result)
+            except errors.SenderKitError as exc:
+                return BatchResult(ok=False, index=index, error=exc)
+
+        if not requests:
+            return []
+
+        with ThreadPoolExecutor(max_workers=max(1, concurrency)) as pool:
+            for outcome in pool.map(lambda pair: run(*pair), list(enumerate(requests))):
+                results[outcome.index] = outcome
+
+        return [r for r in results if r is not None]
+
+    def context(self) -> Context:
+        """Return the workspace and mode this API key operates in."""
+        return Context.from_dict(self._transport.request_json("GET", "/v1/context"))
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> SenderKit:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncSenderKit:
+    """Asynchronous SenderKit client. Mirrors :class:`SenderKit` with ``await``."""
+
+    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 ValueError("api_key is required")
+        self.mode = _mode_for_key(api_key)
+        self._transport = AsyncTransport(api_key, base_url, timeout, max_retries, http_client)
+        self.messages = AsyncMessages(self._transport)
+        self.templates = AsyncTemplates(self._transport)
+
+    async def send(
+        self,
+        template: str,
+        to: str,
+        *,
+        vars: Optional[Dict[str, Any]] = None,
+        version: Optional[int] = None,
+        channel: Optional[ChannelLike] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        scheduled_at: Optional[ScheduledAt] = None,
+        cc: Optional[List[str]] = None,
+        bcc: Optional[List[str]] = None,
+        reply_to: Optional[str] = None,
+        attachments: Optional[list] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> SendResult:
+        return await self._send(
+            TemplateSend(
+                template=template,
+                to=to,
+                vars=vars,
+                version=version,
+                channel=channel,
+                metadata=metadata,
+                scheduled_at=scheduled_at,
+                cc=cc,
+                bcc=bcc,
+                reply_to=reply_to,
+                attachments=attachments,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def send_raw(
+        self,
+        to: str,
+        content: Content,
+        *,
+        channel: Optional[ChannelLike] = None,
+        from_: Optional[str] = None,
+        interpolate: Optional[bool] = None,
+        vars: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        scheduled_at: Optional[ScheduledAt] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> SendResult:
+        return await self._send(
+            RawSend(
+                to=to,
+                content=content,
+                channel=channel,
+                from_=from_,
+                interpolate=interpolate,
+                vars=vars,
+                metadata=metadata,
+                scheduled_at=scheduled_at,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def _send(self, request: SendItem, idempotency_key: Optional[str] = None) -> SendResult:
+        body, own_key = build_send(request)
+        key = idempotency_key or own_key or str(uuid.uuid4())
+        data = await self._transport.request_json(
+            "POST", "/v1/send", body=body, idempotency_key=key
+        )
+        return SendResult.from_dict(data)
+
+    async def send_batch(
+        self,
+        requests: Sequence[SendItem],
+        *,
+        concurrency: int = 5,
+        idempotency_key: Optional[str] = None,
+    ) -> List[BatchResult]:
+        if not requests:
+            return []
+        semaphore = asyncio.Semaphore(max(1, concurrency))
+
+        async def run(index: int, request: SendItem) -> BatchResult:
+            async with semaphore:
+                try:
+                    key = _batch_key(idempotency_key, request, index)
+                    result = await self._send(request, idempotency_key=key)
+                    return BatchResult(ok=True, index=index, result=result)
+                except errors.SenderKitError as exc:
+                    return BatchResult(ok=False, index=index, error=exc)
+
+        outcomes = await asyncio.gather(*(run(i, r) for i, r in enumerate(requests)))
+        return sorted(outcomes, key=lambda r: r.index)
+
+    async def context(self) -> Context:
+        return Context.from_dict(await self._transport.request_json("GET", "/v1/context"))
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncSenderKit:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

senderkit/errors.py

@@ -0,0 +1,89 @@
+"""Exception hierarchy for the SenderKit SDK.
+
+Mirrors the TypeScript and PHP SDKs: a single ``SenderKitError`` base, an
+``APIError`` for non-2xx responses (with status-specific subclasses), plus
+transport-level ``TimeoutError`` / ``NetworkError`` and a webhook
+``SignatureVerificationError``. Catch the base ``SenderKitError`` to handle
+everything the SDK can raise, or a specific subclass for granular handling.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SenderKitError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APIError(SenderKitError):
+    """The API returned a non-2xx response.
+
+    ``status`` is the HTTP status code, ``code`` the machine-readable error code
+    from the response body (e.g. ``invalid_request``), ``issues`` any structured
+    validation detail, and ``request_id`` the ``x-request-id`` header for support.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: Optional[str] = None,
+        issues: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.issues = issues
+        self.request_id = request_id
+
+
+class AuthenticationError(APIError):
+    """401/403 — the API key is missing, invalid, or revoked."""
+
+
+class ValidationError(APIError):
+    """400/422 — the request was malformed or failed validation."""
+
+
+class PaymentRequiredError(APIError):
+    """402 — a plan limit was reached (e.g. ``message_limit_reached``)."""
+
+
+class ConflictError(APIError):
+    """409 — the resource is in a state that disallows the action.
+
+    Raised by ``messages.cancel`` when a message has already been dispatched
+    (``not_cancelable``); the message's freshly observed status is in ``code``/message.
+    """
+
+
+class RateLimitError(APIError):
+    """429 — too many requests. ``retry_after`` is the server's hint, in seconds."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 429,
+        code: Optional[str] = None,
+        issues: Any = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code, issues=issues, request_id=request_id)
+        self.retry_after = retry_after
+
+
+class TimeoutError(SenderKitError):
+    """The request exceeded the configured timeout (shadows builtins.TimeoutError)."""
+
+
+class NetworkError(SenderKitError):
+    """A transport-level failure occurred before a response was received."""
+
+
+class SignatureVerificationError(SenderKitError):
+    """A webhook payload failed signature verification."""

senderkit/integrations/__init__.py

@@ -0,0 +1,10 @@
+"""Framework integrations.
+
+Each submodule imports its framework lazily, so installing the core SDK never
+pulls in Django/FastAPI/Flask/Celery. Import the one you need:
+
+    from senderkit.integrations.django import EmailBackend, get_client, senderkit_webhook
+    from senderkit.integrations.fastapi import get_senderkit, webhook_verifier
+    from senderkit.integrations.flask import SenderKitFlask
+    from senderkit.integrations.celery import make_send_task
+"""

senderkit/integrations/celery.py

@@ -0,0 +1,56 @@
+"""Celery integration: a retryable background send task.
+
+    from celery import Celery
+    from senderkit import SenderKit
+    from senderkit.integrations.celery import make_send_task
+
+    celery_app = Celery("app", broker="redis://localhost:6379/0")
+    send_email = make_send_task(celery_app, lambda: SenderKit(api_key="sk_..."))
+
+    send_email.delay("welcome", "user@example.com", vars={"name": "Ada"})
+
+The task calls ``client.send(template, to, **kwargs)`` and returns the result as a
+dict (JSON-serializable for result backends). Transient failures — rate limits,
+network errors, timeouts — are retried by Celery with exponential backoff, on top
+of the SDK's own in-request retries for 5xx responses.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Tuple, Type
+
+from ..client import SenderKit
+from ..errors import NetworkError, RateLimitError, SenderKitError, TimeoutError
+
+# Transient errors worth retrying at the task level. (5xx is already retried inside
+# the SDK, so a surfaced APIError is treated as terminal here.)
+TRANSIENT_ERRORS: Tuple[Type[SenderKitError], ...] = (
+    RateLimitError,
+    NetworkError,
+    TimeoutError,
+)
+
+
+def make_send_task(
+    celery_app: Any,
+    client_factory: Callable[[], SenderKit],
+    *,
+    name: str = "senderkit.send",
+    max_retries: int = 3,
+) -> Any:
+    """Register and return a ``send(template, to, **kwargs)`` Celery task."""
+
+    @celery_app.task(
+        bind=True,
+        name=name,
+        max_retries=max_retries,
+        autoretry_for=TRANSIENT_ERRORS,
+        retry_backoff=True,
+        retry_jitter=True,
+    )
+    def send_task(self: Any, template: str, to: str, **kwargs: Any) -> Dict[str, Any]:
+        client = client_factory()
+        result = client.send(template, to, **kwargs)
+        return {"id": result.id, "status": result.status, "livemode": result.livemode}
+
+    return send_task

senderkit/integrations/django/__init__.py

@@ -0,0 +1,25 @@
+"""Django integration for SenderKit.
+
+Configure via a ``SENDERKIT`` dict in settings::
+
+    SENDERKIT = {
+        "API_KEY": env("SENDERKIT_API_KEY"),
+        "BASE_URL": "https://api.senderkit.com",   # optional
+        "TIMEOUT": 30.0,                             # optional, seconds
+        "MAX_RETRIES": 2,                            # optional
+        "WEBHOOK_SECRET": env("SENDERKIT_WEBHOOK_SECRET"),  # for webhooks
+    }
+
+Use it three ways:
+
+- ``EMAIL_BACKEND = "senderkit.integrations.django.EmailBackend"`` to route
+  ``django.core.mail`` through SenderKit.
+- ``get_client()`` for a configured :class:`~senderkit.SenderKit` instance.
+- ``@senderkit_webhook`` to verify and dispatch inbound webhooks.
+"""
+
+from .backends import EmailBackend
+from .client import get_client, reset_client
+from .views import senderkit_webhook
+
+__all__ = ["EmailBackend", "get_client", "reset_client", "senderkit_webhook"]

senderkit/integrations/django/backends.py

@@ -0,0 +1,108 @@
+"""A Django ``EMAIL_BACKEND`` that routes mail through SenderKit's raw-send API.
+
+Because Django renders messages locally, sends through this backend bypass
+SenderKit templates (you lose versioning, preview, and per-template analytics).
+Use it to migrate an existing ``django.core.mail`` app without code changes; for
+new code, prefer ``get_client().send(...)`` with a template.
+
+Messages with multiple ``to`` recipients are fanned out as one API call each,
+since the API addresses a single recipient per send (mirrors the PHP Laravel
+``SenderKitTransport``).
+"""
+
+from __future__ import annotations
+
+import base64
+from email.mime.base import MIMEBase
+from typing import Any, List, Optional
+
+from django.core.mail.backends.base import BaseEmailBackend
+
+from ...errors import SenderKitError
+from ...models import Attachment, EmailContent
+from .client import get_client
+
+
+def _to_text(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return str(value)
+
+
+def _html_body(message: Any) -> str:
+    """The API requires HTML. Prefer an explicit text/html alternative, then an
+    html ``content_subtype`` body, falling back to an escaped plain-text body."""
+    for content, mimetype in getattr(message, "alternatives", None) or []:
+        if mimetype == "text/html":
+            return _to_text(content) or ""
+    if getattr(message, "content_subtype", "plain") == "html":
+        return _to_text(message.body) or ""
+    from django.utils.html import escape
+
+    return escape(_to_text(message.body) or "").replace("\n", "<br>")
+
+
+def _text_body(message: Any) -> Optional[str]:
+    if getattr(message, "content_subtype", "plain") == "html":
+        return None
+    return _to_text(message.body)
+
+
+def _addresses(values: Any) -> Optional[List[str]]:
+    items = [v for v in (values or []) if v]
+    return items or None
+
+
+def _attachments(message: Any) -> Optional[List[Attachment]]:
+    out: List[Attachment] = []
+    for attachment in getattr(message, "attachments", None) or []:
+        if isinstance(attachment, MIMEBase):
+            filename = attachment.get_filename() or "attachment"
+            content_type = attachment.get_content_type()
+            decoded = attachment.get_payload(decode=True)
+            payload = decoded if isinstance(decoded, (bytes, bytearray)) else b""
+            content = base64.b64encode(payload).decode()
+        else:
+            filename, raw, content_type = attachment
+            data = raw.encode() if isinstance(raw, str) else raw
+            content = base64.b64encode(data).decode()
+        out.append(
+            Attachment(
+                filename=filename or "attachment",
+                content_type=content_type or "application/octet-stream",
+                content=content,
+            )
+        )
+    return out or None
+
+
+class EmailBackend(BaseEmailBackend):
+    """Sends Django email messages via SenderKit raw email sends."""
+
+    def send_messages(self, email_messages: Any) -> int:
+        if not email_messages:
+            return 0
+        client = get_client()
+        sent = 0
+        for message in email_messages:
+            content = EmailContent(
+                subject=str(message.subject or ""),
+                html=_html_body(message),
+                text=_text_body(message),
+                cc=_addresses(getattr(message, "cc", None)),
+                bcc=_addresses(getattr(message, "bcc", None)),
+                reply_to=(getattr(message, "reply_to", None) or [None])[0],
+                attachments=_attachments(message),
+            )
+            from_email = message.from_email or None
+            recipients = getattr(message, "to", None) or []
+            try:
+                for recipient in recipients:
+                    client.send_raw(recipient, content, from_=from_email)
+                    sent += 1
+            except SenderKitError:
+                if not self.fail_silently:
+                    raise
+        return sent

senderkit/integrations/django/client.py

@@ -0,0 +1,43 @@
+"""Build and cache a :class:`~senderkit.SenderKit` from Django settings."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ...client import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, SenderKit
+
+_client: Optional[SenderKit] = None
+
+
+def get_config() -> Dict[str, Any]:
+    """Return the ``SENDERKIT`` settings dict (empty if unset)."""
+    from django.conf import settings
+
+    return dict(getattr(settings, "SENDERKIT", {}) or {})
+
+
+def get_client() -> SenderKit:
+    """Return a process-wide :class:`~senderkit.SenderKit` built from settings."""
+    global _client
+    if _client is None:
+        config = get_config()
+        api_key = config.get("API_KEY")
+        if not api_key:
+            from django.core.exceptions import ImproperlyConfigured
+
+            raise ImproperlyConfigured("SENDERKIT['API_KEY'] is not set.")
+        _client = SenderKit(
+            api_key=api_key,
+            base_url=config.get("BASE_URL", DEFAULT_BASE_URL),
+            timeout=config.get("TIMEOUT", DEFAULT_TIMEOUT),
+            max_retries=config.get("MAX_RETRIES", DEFAULT_MAX_RETRIES),
+        )
+    return _client
+
+
+def reset_client() -> None:
+    """Drop the cached client (useful in tests and after settings changes)."""
+    global _client
+    if _client is not None:
+        _client.close()
+    _client = None

senderkit/integrations/django/views.py

@@ -0,0 +1,55 @@
+"""A decorator that verifies a SenderKit webhook before calling your view.
+
+    from senderkit.integrations.django import senderkit_webhook
+
+    @senderkit_webhook
+    def handle(request, event):
+        if event.type == "message.delivered":
+            ...
+        return HttpResponse(status=204)
+
+The secret comes from ``SENDERKIT['WEBHOOK_SECRET']`` unless passed explicitly.
+A missing/invalid/stale signature yields an HTTP 400 before your view runs.
+"""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from ...errors import SignatureVerificationError
+from ...webhooks import DEFAULT_TOLERANCE_SECONDS, WebhookVerifier
+from .client import get_config
+
+
+def senderkit_webhook(
+    view: Optional[Callable[..., Any]] = None,
+    *,
+    secret: Optional[str] = None,
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+) -> Callable[..., Any]:
+    """Wrap a view ``(request, event, *args, **kwargs)``; usable bare or with args."""
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        from django.http import HttpResponseBadRequest
+        from django.views.decorators.csrf import csrf_exempt
+
+        @csrf_exempt
+        @wraps(fn)
+        def wrapper(request: Any, *args: Any, **kwargs: Any) -> Any:
+            signing_secret = secret or get_config().get("WEBHOOK_SECRET")
+            try:
+                event = WebhookVerifier(signing_secret).verify(
+                    request.body,
+                    request.headers.get("X-SenderKit-Signature", ""),
+                    tolerance=tolerance,
+                    event_type=request.headers.get("X-SenderKit-Event"),
+                    delivery_id=request.headers.get("X-SenderKit-Delivery"),
+                )
+            except SignatureVerificationError as exc:
+                return HttpResponseBadRequest(str(exc))
+            return fn(request, event, *args, **kwargs)
+
+        return wrapper
+
+    return decorator(view) if view is not None else decorator