maildeno 2.0.0__py3-none-any.whl

maildeno/__init__.py

@@ -0,0 +1,47 @@
+"""Official Python SDK for the Maildeno render API.
+
+Quick start::
+
+    from maildeno import MaildenoClient
+
+    client = MaildenoClient(api_key="sk_live_...")
+    html = client.render_html("550e8400-e29b-41d4-a716-446655440000")
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._async_client import AsyncMaildenoClient
+from ._client import MaildenoClient
+from ._error import MaildenoError
+from ._types import (
+    CacheConfig,
+    ContextValue,
+    DynamicData,
+    MergeTagGroup,
+    RenderResult,
+    RenderTarget,
+    SdkErrorCode,
+    TemplateJson,
+    ValidationIssue,
+)
+
+try:
+    __version__ = version("maildeno")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = [
+    "AsyncMaildenoClient",
+    "CacheConfig",
+    "ContextValue",
+    "DynamicData",
+    "MaildenoClient",
+    "MaildenoError",
+    "MergeTagGroup",
+    "RenderResult",
+    "RenderTarget",
+    "SdkErrorCode",
+    "TemplateJson",
+    "ValidationIssue",
+    "__version__",
+]

maildeno/_async_client.py

@@ -0,0 +1,243 @@
+"""Asynchronous Maildeno client."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import warnings
+from types import TracebackType
+from typing import List, Optional, Type
+
+import httpx
+
+from ._cache import build_cache
+from ._minify import minify_output
+from ._error import MaildenoError
+from ._internal import (
+    DEFAULT_TIMEOUT,
+    TEMPLATE_PATH,
+    build_headers,
+    map_transport_error,
+    normalise_base_url,
+    normalise_dynamic_data,
+    parse_template_response,
+    raise_for_response,
+)
+from ._renderer import render_template
+from ._types import CacheConfig, DynamicData, RenderResult, RenderTarget, TemplateJson
+
+
+class AsyncMaildenoClient:
+    """Asynchronous Maildeno client. Mirrors :class:`MaildenoClient`.
+
+    Template JSON is fetched asynchronously, cached locally, and rendered
+    via the embedded Wasm engine in a thread-pool executor so the event
+    loop is never blocked.
+
+    Example::
+
+        import asyncio
+        from maildeno import AsyncMaildenoClient
+
+        async def main():
+            async with AsyncMaildenoClient(api_key="sk_live_...") as client:
+                html = await client.render_html("550e8400-...")
+                print(html)
+
+        asyncio.run(main())
+
+    For FastAPI / Starlette / aiohttp, instantiate one client per process
+    at startup and reuse it across all requests.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        cache: Optional[CacheConfig] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise MaildenoError("INVALID_API_KEY", "api_key is required.")
+
+        self._api_key  = api_key
+        self._base_url = normalise_base_url(base_url)
+        self._timeout  = timeout
+        self._cache    = build_cache(cache)  # type: ignore[arg-type]
+
+        if http_client is not None:
+            self._http = http_client
+            self._owns_http = False
+        else:
+            self._http = httpx.AsyncClient(timeout=timeout)
+            self._owns_http = True
+
+    # ── Render ────────────────────────────────────────────────────────────────
+
+    async def render(
+        self,
+        *,
+        template_id: str,
+        target: RenderTarget = "html",
+        dynamic_data: Optional[DynamicData] = None,
+    ) -> RenderResult:
+        """Render a template to HTML, React Email TSX, or MJML.
+
+        The Wasm engine is synchronous; it runs in a thread-pool executor so
+        the event loop is never blocked.
+
+        :param template_id:  UUID of the template (required).
+        :param target:       ``"html"`` | ``"react-email"`` | ``"mjml"``.
+        :param dynamic_data: Merge tags + visibility context (fully optional).
+        :raises MaildenoError: On any API or render failure.
+        """
+        template, from_stale = await self._get_template(template_id, target)
+
+        norm_data: Optional[DynamicData] = None
+        if dynamic_data is not None:
+            raw = normalise_dynamic_data(dynamic_data)
+            if raw:
+                norm_data = raw  # type: ignore[assignment]
+
+        # Run the synchronous Wasm render in a thread to avoid blocking the
+        # event loop. functools.partial binds the arguments cleanly.
+        loop = asyncio.get_event_loop()
+        raw_output: str = await loop.run_in_executor(
+            None,
+            functools.partial(render_template, template, target, norm_data),
+        )
+        output = minify_output(target, raw_output)
+
+        return RenderResult(
+            template_id=template_id,
+            target=target,
+            output=output,
+            from_stale_cache=from_stale,
+        )
+
+    async def render_html(
+        self,
+        template_id: str,
+        dynamic_data: Optional[DynamicData] = None,
+    ) -> str:
+        """Convenience: render to HTML, returning the output string directly."""
+        return (
+            await self.render(
+                template_id=template_id, target="html", dynamic_data=dynamic_data
+            )
+        ).output
+
+    async def render_react(
+        self,
+        template_id: str,
+        dynamic_data: Optional[DynamicData] = None,
+    ) -> str:
+        """Convenience: render to React Email TSX."""
+        return (
+            await self.render(
+                template_id=template_id, target="react-email", dynamic_data=dynamic_data
+            )
+        ).output
+
+    async def render_mjml(
+        self,
+        template_id: str,
+        dynamic_data: Optional[DynamicData] = None,
+    ) -> str:
+        """Convenience: render to MJML."""
+        return (
+            await self.render(
+                template_id=template_id, target="mjml", dynamic_data=dynamic_data
+            )
+        ).output
+
+    # ── Cache management ──────────────────────────────────────────────────────
+
+    def list_cached(self) -> List[str]:
+        """Return the IDs of all templates currently in the cache."""
+        return self._cache.list()
+
+    def delete_cached(self, template_id: str) -> None:
+        """Remove a single template from the cache."""
+        self._cache.invalidate(template_id)
+
+    def clear_cache(self) -> None:
+        """Remove all templates from the cache."""
+        self._cache.clear()
+
+    def invalidate(self, template_id: str) -> None:
+        """Deprecated — use :meth:`delete_cached` instead."""
+        warnings.warn(
+            "invalidate() is deprecated; use delete_cached() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.delete_cached(template_id)
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client.
+
+        Only closes the client if this :class:`AsyncMaildenoClient` created it.
+        """
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncMaildenoClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    # ── Template fetching ─────────────────────────────────────────────────────
+
+    async def _get_template(
+        self,
+        template_id: str,
+        target: RenderTarget,
+    ) -> tuple[TemplateJson, bool]:
+        """Return (template, from_stale_cache)."""
+        fresh = self._cache.get_fresh(template_id)
+        if fresh is not None:
+            return fresh, False
+
+        try:
+            template = await self._fetch_template(template_id, target)
+            self._cache.set(template_id, template)
+            return template, False
+        except MaildenoError:
+            stale = self._cache.get_fallback(template_id)
+            if stale is not None:
+                return stale, True
+            raise
+
+    async def _fetch_template(
+        self,
+        template_id: str,
+        target: RenderTarget,
+    ) -> TemplateJson:
+        url = f"{self._base_url}{TEMPLATE_PATH}/{template_id}?target={target}"
+        try:
+            response = await self._http.get(
+                url,
+                headers=build_headers(self._api_key),
+                timeout=self._timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise map_transport_error(exc) from exc
+        except Exception as exc:  # pragma: no cover
+            raise map_transport_error(exc) from exc
+
+        raise_for_response(response)
+        return parse_template_response(response.json())
+
+
+__all__ = ["AsyncMaildenoClient"]

maildeno/_cache.py

@@ -0,0 +1,291 @@
+"""Template cache — memory and disk strategies.
+
+Storage layout (disk mode):
+
+    {cache_dir}/
+      a7f4b181-a366-4944-a371-e7b941a3c5ab.json
+      9ec0c043-e8a1-4a68-bbb3-92fbef1ea222.json
+
+Each file contains::
+
+    {
+      "template_id": "...",
+      "fetched_at": 1717776000000,
+      "ttl": 300000,
+      "template": { ...TemplateJson... }
+    }
+
+The file name is the UUID as-is. UUIDs contain only [0-9a-f-] which is safe
+on every modern filesystem. Any other character is replaced with ``_`` as a
+defensive guard — this never fires for real Maildeno template IDs.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from ._types import TemplateJson
+
+
+# ── Shared helpers ────────────────────────────────────────────────────────────
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _is_stale(fetched_at: int, ttl: int) -> bool:
+    return _now_ms() - fetched_at > ttl
+
+
+# ── Strategy interface ────────────────────────────────────────────────────────
+
+class _CacheStore(ABC):
+    """All cache implementations must satisfy this interface."""
+
+    @abstractmethod
+    def get_fresh(self, template_id: str) -> Optional[TemplateJson]:
+        """Return the template only if it is within TTL, else None."""
+
+    @abstractmethod
+    def get_fallback(self, template_id: str) -> Optional[TemplateJson]:
+        """Return the template regardless of staleness, or None if absent."""
+
+    @abstractmethod
+    def set(self, template_id: str, template: TemplateJson) -> None:
+        """Store or overwrite a template entry."""
+
+    @abstractmethod
+    def invalidate(self, template_id: str) -> None:
+        """Remove a single entry. No-op if absent."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all entries."""
+
+    @abstractmethod
+    def list(self) -> List[str]:
+        """Return the IDs of all currently cached templates."""
+
+
+# ── Memory store ──────────────────────────────────────────────────────────────
+
+class _MemoryStore(_CacheStore):
+    """In-process dict cache with TTL + stale-on-error fallback.
+
+    Lost on process restart. Zero I/O. Every read is O(1).
+    Oldest entry evicted when ``max_entries`` is reached.
+    """
+
+    def __init__(self, ttl: int, max_entries: int) -> None:
+        self._ttl = ttl
+        self._max = max_entries
+        # {template_id: {"template": ..., "fetched_at": int, "ttl": int}}
+        self._store: Dict[str, Dict[str, Any]] = {}
+
+    def get_fresh(self, template_id: str) -> Optional[TemplateJson]:
+        entry = self._store.get(template_id)
+        if entry is None:
+            return None
+        if _is_stale(entry["fetched_at"], entry["ttl"]):
+            return None
+        return entry["template"]  # type: ignore[return-value]
+
+    def get_fallback(self, template_id: str) -> Optional[TemplateJson]:
+        entry = self._store.get(template_id)
+        return entry["template"] if entry else None  # type: ignore[return-value]
+
+    def set(self, template_id: str, template: TemplateJson) -> None:
+        if len(self._store) >= self._max and template_id not in self._store:
+            # Evict oldest entry
+            oldest = min(self._store, key=lambda k: self._store[k]["fetched_at"])
+            del self._store[oldest]
+        self._store[template_id] = {
+            "template": template,
+            "fetched_at": _now_ms(),
+            "ttl": self._ttl,
+        }
+
+    def invalidate(self, template_id: str) -> None:
+        self._store.pop(template_id, None)
+
+    def clear(self) -> None:
+        self._store.clear()
+
+    def list(self) -> List[str]:
+        return list(self._store.keys())
+
+
+# ── Disk store ────────────────────────────────────────────────────────────────
+
+class _DiskStore(_CacheStore):
+    """Persistent JSON-file cache.
+
+    Each template is stored as a single minified JSON file named after its
+    UUID. Survives process restarts. All reads/writes are synchronous — both
+    the sync and async clients call this from a thread (the async client uses
+    ``run_in_executor`` for the whole render pipeline).
+    """
+
+    def __init__(self, cache_dir: str, ttl: int, max_entries: int) -> None:
+        self._dir = cache_dir
+        self._ttl = ttl
+        self._max = max_entries
+
+    # ── Reads ──────────────────────────────────────────────────────────────
+
+    def get_fresh(self, template_id: str) -> Optional[TemplateJson]:
+        entry = self._read(template_id)
+        if entry is None:
+            return None
+        if _is_stale(entry["fetched_at"], entry["ttl"]):
+            return None
+        return entry["template"]  # type: ignore[return-value]
+
+    def get_fallback(self, template_id: str) -> Optional[TemplateJson]:
+        entry = self._read(template_id)
+        return entry["template"] if entry else None  # type: ignore[return-value]
+
+    # ── Writes ─────────────────────────────────────────────────────────────
+
+    def set(self, template_id: str, template: TemplateJson) -> None:
+        os.makedirs(self._dir, exist_ok=True)
+        self._enforce_limit()
+
+        entry = {
+            "template_id": template_id,
+            "fetched_at": _now_ms(),
+            "ttl": self._ttl,
+            "template": template,
+        }
+        final = self._path(template_id)
+        tmp = final + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            # Minified — no indent. 58 KB → 22 KB.
+            json.dump(entry, fh, separators=(",", ":"))
+        os.replace(tmp, final)  # atomic on POSIX; best-effort on Windows
+
+    def invalidate(self, template_id: str) -> None:
+        try:
+            os.unlink(self._path(template_id))
+        except FileNotFoundError:
+            pass
+
+    def clear(self) -> None:
+        try:
+            files = os.listdir(self._dir)
+        except FileNotFoundError:
+            return
+        for f in files:
+            if f.endswith(".json") and not f.endswith(".tmp"):
+                try:
+                    os.unlink(os.path.join(self._dir, f))
+                except OSError:
+                    pass
+
+    def list(self) -> List[str]:
+        try:
+            files = os.listdir(self._dir)
+        except FileNotFoundError:
+            return []
+        return [
+            f[:-5]  # strip ".json"
+            for f in files
+            if f.endswith(".json") and not f.endswith(".tmp")
+        ]
+
+    # ── Internals ──────────────────────────────────────────────────────────
+
+    def _path(self, template_id: str) -> str:
+        safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in template_id)
+        return os.path.join(self._dir, f"{safe}.json")
+
+    def _read(self, template_id: str) -> Optional[Dict[str, Any]]:
+        try:
+            with open(self._path(template_id), encoding="utf-8") as fh:
+                return json.load(fh)  # type: ignore[no-any-return]
+        except (FileNotFoundError, json.JSONDecodeError, KeyError):
+            return None
+
+    def _enforce_limit(self) -> None:
+        try:
+            files = [
+                f for f in os.listdir(self._dir)
+                if f.endswith(".json") and not f.endswith(".tmp")
+            ]
+        except FileNotFoundError:
+            return
+
+        if len(files) < self._max:
+            return
+
+        # Read fetchedAt from each file to find the oldest
+        entries = []
+        for f in files:
+            try:
+                with open(os.path.join(self._dir, f), encoding="utf-8") as fh:
+                    data = json.load(fh)
+                entries.append((f, data.get("fetched_at", 0)))
+            except (OSError, json.JSONDecodeError):
+                entries.append((f, 0))
+
+        entries.sort(key=lambda x: x[1])
+        to_evict = entries[: len(entries) - self._max + 1]
+        for fname, _ in to_evict:
+            try:
+                os.unlink(os.path.join(self._dir, fname))
+            except OSError:
+                pass
+
+
+# ── Public facade ─────────────────────────────────────────────────────────────
+
+_DEFAULT_TTL = 300_000          # 5 minutes
+_DEFAULT_MAX_ENTRIES = 50
+_DEFAULT_CACHE_PATH = ".maildeno-cache"
+
+
+class TemplateCache:
+    """Thin facade over the active ``_CacheStore``.
+
+    Both clients delegate every cache operation here so they never reference
+    ``_MemoryStore`` or ``_DiskStore`` directly.
+    """
+
+    def __init__(self, store: _CacheStore) -> None:
+        self._store = store
+
+    def get_fresh(self, template_id: str) -> Optional[TemplateJson]:
+        return self._store.get_fresh(template_id)
+
+    def get_fallback(self, template_id: str) -> Optional[TemplateJson]:
+        return self._store.get_fallback(template_id)
+
+    def set(self, template_id: str, template: TemplateJson) -> None:
+        self._store.set(template_id, template)
+
+    def invalidate(self, template_id: str) -> None:
+        self._store.invalidate(template_id)
+
+    def clear(self) -> None:
+        self._store.clear()
+
+    def list(self) -> List[str]:
+        return self._store.list()
+
+
+def build_cache(config: Optional[Dict[str, Any]]) -> TemplateCache:
+    """Build a :class:`TemplateCache` from a raw config dict or ``None``."""
+    cfg = config or {}
+    ttl = int(cfg.get("ttl", _DEFAULT_TTL))
+    max_entries = int(cfg.get("max_entries", _DEFAULT_MAX_ENTRIES))
+
+    if cfg.get("type") == "disk":
+        raw_path = cfg.get("path", _DEFAULT_CACHE_PATH)
+        resolved = os.path.abspath(raw_path)
+        return TemplateCache(_DiskStore(resolved, ttl, max_entries))
+
+    return TemplateCache(_MemoryStore(ttl, max_entries))