herfy-email 0.1.0__tar.gz

herfy_email-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: herfy-email
+Version: 0.1.0
+Summary: Provider-abstracted email SDK for Herfy applications — send via Control Center credentials
+Author: Herfy Development Team
+License-Expression: MIT
+Keywords: email,mailgun,sendgrid,herfy,control-center
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: mailgun
+Requires-Dist: mailgun>=1.0.0; extra == "mailgun"
+Provides-Extra: sendgrid
+Requires-Dist: sendgrid>=6.0.0; extra == "sendgrid"
+Provides-Extra: all
+Requires-Dist: mailgun>=1.0.0; extra == "all"
+Requires-Dist: sendgrid>=6.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+
+# herfy-email
+
+Provider-abstracted email SDK for Herfy applications. Send transactional email using only your Control Center `client_id` and `client_secret` — no email provider credentials in app config.
+
+## Installation
+
+```bash
+pip install herfy-email[mailgun]
+```
+
+## Usage
+
+```python
+from herfy_email import HerfyEmailClient, AsyncHerfyEmailClient
+
+# Sync
+client = HerfyEmailClient.from_credentials(
+    client_id="app_pettycash",
+    client_secret="your_secret",
+    control_center_url="https://cc.herfy.com",
+)
+client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")
+
+# Async (FastAPI)
+client = AsyncHerfyEmailClient.from_credentials(
+    client_id="app_pettycash",
+    client_secret="your_secret",
+    control_center_url="https://cc.herfy.com",
+)
+await client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")
+
+# From environment variables (CC_CLIENT_ID / AUTH_CLIENT_ID, CC_CLIENT_SECRET / AUTH_CLIENT_SECRET, CC_URL / CONTROL_CENTER_URL)
+client = HerfyEmailClient.from_env()
+```
+
+## How it works
+
+1. SDK authenticates with Control Center via `POST /api/app-auth/token` (cached, TTL 300s)
+2. SDK fetches provider config from `GET /api/config/email` (cached for process lifetime)
+3. SDK calls the configured provider (Mailgun, SendGrid, …) directly
+
+Switching email providers requires only a Control Center env-var change — zero app changes.
+
+## Provider support
+
+| Provider | Extra |
+|----------|-------|
+| Mailgun  | `pip install herfy-email[mailgun]` |
+| SendGrid | `pip install herfy-email[sendgrid]` |
+
+## Control Center configuration
+
+```env
+EMAIL_PROVIDER=mailgun
+MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxx
+MAILGUN_DOMAIN=mg.herfy.com
+MAILGUN_FROM_ADDRESS=noreply@herfy.com
+```

herfy_email-0.1.0/README.md

@@ -0,0 +1,58 @@
+# herfy-email
+
+Provider-abstracted email SDK for Herfy applications. Send transactional email using only your Control Center `client_id` and `client_secret` — no email provider credentials in app config.
+
+## Installation
+
+```bash
+pip install herfy-email[mailgun]
+```
+
+## Usage
+
+```python
+from herfy_email import HerfyEmailClient, AsyncHerfyEmailClient
+
+# Sync
+client = HerfyEmailClient.from_credentials(
+    client_id="app_pettycash",
+    client_secret="your_secret",
+    control_center_url="https://cc.herfy.com",
+)
+client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")
+
+# Async (FastAPI)
+client = AsyncHerfyEmailClient.from_credentials(
+    client_id="app_pettycash",
+    client_secret="your_secret",
+    control_center_url="https://cc.herfy.com",
+)
+await client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")
+
+# From environment variables (CC_CLIENT_ID / AUTH_CLIENT_ID, CC_CLIENT_SECRET / AUTH_CLIENT_SECRET, CC_URL / CONTROL_CENTER_URL)
+client = HerfyEmailClient.from_env()
+```
+
+## How it works
+
+1. SDK authenticates with Control Center via `POST /api/app-auth/token` (cached, TTL 300s)
+2. SDK fetches provider config from `GET /api/config/email` (cached for process lifetime)
+3. SDK calls the configured provider (Mailgun, SendGrid, …) directly
+
+Switching email providers requires only a Control Center env-var change — zero app changes.
+
+## Provider support
+
+| Provider | Extra |
+|----------|-------|
+| Mailgun  | `pip install herfy-email[mailgun]` |
+| SendGrid | `pip install herfy-email[sendgrid]` |
+
+## Control Center configuration
+
+```env
+EMAIL_PROVIDER=mailgun
+MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxx
+MAILGUN_DOMAIN=mg.herfy.com
+MAILGUN_FROM_ADDRESS=noreply@herfy.com
+```

herfy_email-0.1.0/herfy_email/__init__.py

@@ -0,0 +1,17 @@
+from .client import AsyncHerfyEmailClient, HerfyEmailClient
+from .exceptions import AuthError, ConfigError, EmailError, SendError
+from .models import EmailConfig, ProviderConfig, SendResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HerfyEmailClient",
+    "AsyncHerfyEmailClient",
+    "EmailConfig",
+    "ProviderConfig",
+    "SendResult",
+    "EmailError",
+    "AuthError",
+    "ConfigError",
+    "SendError",
+]

herfy_email-0.1.0/herfy_email/client.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Optional
+
+import httpx
+
+from .exceptions import AuthError, ConfigError
+from .models import EmailConfig, ProviderConfig, SendResult
+from .providers import get_provider
+from .providers.base import BaseEmailProvider
+
+logger = logging.getLogger(__name__)
+
+
+class HerfyEmailClient:
+    """Synchronous email client using Control Center credentials."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        control_center_url: str,
+        *,
+        token_cache_ttl: int = 240,
+        request_timeout: float = 15.0,
+    ) -> None:
+        self._cfg = EmailConfig(
+            control_center_url=control_center_url.rstrip("/"),
+            client_id=client_id,
+            client_secret=client_secret,
+            token_cache_ttl=token_cache_ttl,
+            request_timeout=request_timeout,
+        )
+        self._token: Optional[str] = None
+        self._token_at: float = 0.0
+        self._provider: Optional[BaseEmailProvider] = None
+
+    @classmethod
+    def from_env(cls) -> "HerfyEmailClient":
+        cfg = EmailConfig.from_env()
+        return cls(
+            client_id=cfg.client_id,
+            client_secret=cfg.client_secret,
+            control_center_url=cfg.control_center_url,
+            token_cache_ttl=cfg.token_cache_ttl,
+            request_timeout=cfg.request_timeout,
+        )
+
+    @classmethod
+    def from_credentials(
+        cls,
+        *,
+        client_id: str,
+        client_secret: str,
+        control_center_url: str,
+    ) -> "HerfyEmailClient":
+        return cls(
+            client_id=client_id,
+            client_secret=client_secret,
+            control_center_url=control_center_url,
+        )
+
+    def _get_token(self) -> str:
+        if self._token and (time.monotonic() - self._token_at) < self._cfg.token_cache_ttl:
+            return self._token
+        url = f"{self._cfg.control_center_url}/oauth/token"
+        try:
+            resp = httpx.post(
+                url,
+                json={
+                    "grant_type": "client_credentials",
+                    "client_id": self._cfg.client_id,
+                    "client_secret": self._cfg.client_secret,
+                },
+                timeout=self._cfg.request_timeout,
+            )
+        except httpx.RequestError as exc:
+            raise AuthError(f"Cannot reach Control Center at {url}: {exc}") from exc
+        if resp.status_code == 401:
+            raise AuthError("Invalid client_id or client_secret")
+        if resp.status_code != 200:
+            raise AuthError(f"Token request failed (HTTP {resp.status_code}): {resp.text[:200]}")
+        token = resp.json().get("access_token")
+        if not token:
+            raise AuthError("Control Center did not return an access_token")
+        self._token = str(token)
+        self._token_at = time.monotonic()
+        return self._token
+
+    def _get_provider(self) -> BaseEmailProvider:
+        if self._provider is not None:
+            return self._provider
+        url = f"{self._cfg.control_center_url}{self._cfg.email_config_path}"
+        try:
+            resp = httpx.get(
+                url,
+                headers={"Authorization": f"Bearer {self._get_token()}"},
+                timeout=self._cfg.request_timeout,
+            )
+        except httpx.RequestError as exc:
+            raise ConfigError(f"Cannot reach CC email config at {url}: {exc}") from exc
+        if resp.status_code == 401:
+            self._token = None
+            raise AuthError("Email config request rejected — token invalid")
+        if resp.status_code != 200:
+            raise ConfigError(
+                f"Email config request failed (HTTP {resp.status_code}): {resp.text[:200]}"
+            )
+        provider_cfg = ProviderConfig.from_api_response(resp.json())
+        self._provider = get_provider(provider_cfg)
+        return self._provider
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html: str,
+        text: str,
+        from_address: Optional[str] = None,
+    ) -> SendResult:
+        """Send an email. Raises SendError on failure."""
+        return self._get_provider().send(to, subject, html, text, from_address)
+
+
+class AsyncHerfyEmailClient:
+    """Async email client using Control Center credentials (for FastAPI apps)."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        control_center_url: str,
+        *,
+        token_cache_ttl: int = 240,
+        request_timeout: float = 15.0,
+    ) -> None:
+        self._cfg = EmailConfig(
+            control_center_url=control_center_url.rstrip("/"),
+            client_id=client_id,
+            client_secret=client_secret,
+            token_cache_ttl=token_cache_ttl,
+            request_timeout=request_timeout,
+        )
+        self._token: Optional[str] = None
+        self._token_at: float = 0.0
+        self._provider: Optional[BaseEmailProvider] = None
+        self._http: Optional[httpx.AsyncClient] = None
+
+    @classmethod
+    def from_env(cls) -> "AsyncHerfyEmailClient":
+        cfg = EmailConfig.from_env()
+        return cls(
+            client_id=cfg.client_id,
+            client_secret=cfg.client_secret,
+            control_center_url=cfg.control_center_url,
+            token_cache_ttl=cfg.token_cache_ttl,
+            request_timeout=cfg.request_timeout,
+        )
+
+    @classmethod
+    def from_credentials(
+        cls,
+        *,
+        client_id: str,
+        client_secret: str,
+        control_center_url: str,
+    ) -> "AsyncHerfyEmailClient":
+        return cls(
+            client_id=client_id,
+            client_secret=client_secret,
+            control_center_url=control_center_url,
+        )
+
+    async def _http_client(self) -> httpx.AsyncClient:
+        if self._http is None or self._http.is_closed:
+            self._http = httpx.AsyncClient()
+        return self._http
+
+    async def close(self) -> None:
+        if self._http and not self._http.is_closed:
+            await self._http.aclose()
+
+    async def _get_token(self) -> str:
+        if self._token and (time.monotonic() - self._token_at) < self._cfg.token_cache_ttl:
+            return self._token
+        client = await self._http_client()
+        url = f"{self._cfg.control_center_url}/oauth/token"
+        try:
+            resp = await client.post(
+                url,
+                json={
+                    "grant_type": "client_credentials",
+                    "client_id": self._cfg.client_id,
+                    "client_secret": self._cfg.client_secret,
+                },
+                timeout=self._cfg.request_timeout,
+            )
+        except httpx.RequestError as exc:
+            raise AuthError(f"Cannot reach Control Center at {url}: {exc}") from exc
+        if resp.status_code == 401:
+            raise AuthError("Invalid client_id or client_secret")
+        if resp.status_code != 200:
+            raise AuthError(f"Token request failed (HTTP {resp.status_code}): {resp.text[:200]}")
+        token = resp.json().get("access_token")
+        if not token:
+            raise AuthError("Control Center did not return an access_token")
+        self._token = str(token)
+        self._token_at = time.monotonic()
+        return self._token
+
+    async def _get_provider(self) -> BaseEmailProvider:
+        if self._provider is not None:
+            return self._provider
+        client = await self._http_client()
+        url = f"{self._cfg.control_center_url}{self._cfg.email_config_path}"
+        try:
+            resp = await client.get(
+                url,
+                headers={"Authorization": f"Bearer {await self._get_token()}"},
+                timeout=self._cfg.request_timeout,
+            )
+        except httpx.RequestError as exc:
+            raise ConfigError(f"Cannot reach CC email config: {exc}") from exc
+        if resp.status_code == 401:
+            self._token = None
+            raise AuthError("Email config request rejected — token invalid")
+        if resp.status_code != 200:
+            raise ConfigError(
+                f"Email config request failed (HTTP {resp.status_code}): {resp.text[:200]}"
+            )
+        provider_cfg = ProviderConfig.from_api_response(resp.json())
+        self._provider = get_provider(provider_cfg)
+        return self._provider
+
+    async def send(
+        self,
+        to: str,
+        subject: str,
+        html: str,
+        text: str,
+        from_address: Optional[str] = None,
+    ) -> SendResult:
+        """Send an email asynchronously. Raises SendError on failure."""
+        provider = await self._get_provider()
+        return await provider.async_send(to, subject, html, text, from_address)

herfy_email-0.1.0/herfy_email/exceptions.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+
+class EmailError(Exception):
+    """Base exception for herfy-email."""
+    def __init__(self, message: str, status_code: int = 0) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(EmailError):
+    """CC token fetch failed or was rejected."""
+
+
+class ConfigError(EmailError):
+    """CC email config endpoint returned an error or unknown provider."""
+
+
+class SendError(EmailError):
+    """Email provider rejected the send request."""

herfy_email-0.1.0/herfy_email/models.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class EmailConfig:
+    """Configuration for HerfyEmailClient."""
+    control_center_url: str
+    client_id: str
+    client_secret: str
+    email_config_path: str = "/api/config/email"
+    token_cache_ttl: int = 240
+    request_timeout: float = 15.0
+
+    @classmethod
+    def from_env(cls) -> "EmailConfig":
+        url = os.environ.get("CONTROL_CENTER_URL", "")
+        cid = os.environ.get("AUTH_CLIENT_ID", "")
+        secret = os.environ.get("AUTH_CLIENT_SECRET", "")
+        if not url:
+            raise ValueError("CONTROL_CENTER_URL is required")
+        if not cid:
+            raise ValueError("AUTH_CLIENT_ID is required")
+        if not secret:
+            raise ValueError("AUTH_CLIENT_SECRET is required")
+        return cls(
+            control_center_url=url.rstrip("/"),
+            client_id=cid,
+            client_secret=secret,
+            token_cache_ttl=int(os.environ.get("EMAIL_TOKEN_CACHE_TTL", "240")),
+            request_timeout=float(os.environ.get("EMAIL_REQUEST_TIMEOUT", "15")),
+        )
+
+
+@dataclass
+class ProviderConfig:
+    """Parsed response from GET /api/config/email."""
+    provider: str
+    api_key: str
+    domain: str
+    from_address: str
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api_response(cls, data: dict) -> "ProviderConfig":
+        config = data.get("config", {})
+        return cls(
+            provider=data["provider"],
+            api_key=config["api_key"],
+            domain=config.get("domain", ""),
+            from_address=config.get("from_address", "noreply@herfy.com"),
+            extra={k: v for k, v in config.items()
+                   if k not in {"api_key", "domain", "from_address"}},
+        )
+
+
+@dataclass
+class SendResult:
+    success: bool
+    message_id: str = ""
+    provider: str = ""
+    raw: Any = None

herfy_email-0.1.0/herfy_email/providers/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from ..exceptions import ConfigError
+from ..models import ProviderConfig
+from .base import BaseEmailProvider
+
+
+def get_provider(config: ProviderConfig) -> BaseEmailProvider:
+    """Instantiate the correct provider from CC config."""
+    if config.provider == "mailgun":
+        from .mailgun import MailgunProvider
+        return MailgunProvider.from_config(config)
+    if config.provider == "sendgrid":
+        from .sendgrid import SendGridProvider
+        return SendGridProvider.from_config(config)
+    raise ConfigError(f"Unknown email provider: '{config.provider}'. "
+                      f"Supported: mailgun, sendgrid")

herfy_email-0.1.0/herfy_email/providers/base.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from ..models import ProviderConfig, SendResult
+
+
+class BaseEmailProvider(ABC):
+    """Abstract base — one implementation per email provider."""
+
+    @abstractmethod
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html: str,
+        text: str,
+        from_address: Optional[str] = None,
+    ) -> SendResult:
+        """Send a single email. Raises SendError on failure."""
+
+    async def async_send(
+        self,
+        to: str,
+        subject: str,
+        html: str,
+        text: str,
+        from_address: Optional[str] = None,
+    ) -> SendResult:
+        """Async variant. Default implementation runs sync send in executor."""
+        import asyncio
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, lambda: self.send(to, subject, html, text, from_address)
+        )
+
+    @classmethod
+    @abstractmethod
+    def from_config(cls, config: ProviderConfig) -> "BaseEmailProvider":
+        """Construct from a ProviderConfig."""

herfy_email-0.1.0/herfy_email/providers/mailgun.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from ..exceptions import ConfigError, SendError
+from ..models import ProviderConfig, SendResult
+from .base import BaseEmailProvider
+
+logger = logging.getLogger(__name__)
+
+
+class MailgunProvider(BaseEmailProvider):
+    """Email provider backed by the Mailgun API."""
+
+    def __init__(self, api_key: str, domain: str, from_address: str) -> None:
+        self._api_key = api_key
+        self._domain = domain
+        self._from_address = from_address
+
+    @classmethod
+    def from_config(cls, config: ProviderConfig) -> "MailgunProvider":
+        if not config.domain.strip():
+            raise ConfigError("Mailgun provider requires 'domain' in CC email config")
+        return cls(
+            api_key=config.api_key,
+            domain=config.domain,
+            from_address=config.from_address,
+        )
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html: str,
+        text: str,
+        from_address: Optional[str] = None,
+    ) -> SendResult:
+        try:
+            import mailgun  # type: ignore
+        except ImportError as exc:
+            raise ConfigError(
+                "mailgun package not installed. Run: pip install mailgun"
+            ) from exc
+
+        sender = from_address or self._from_address
+        try:
+            client = mailgun.Client(auth=("api", self._api_key))
+            result = client.messages.create(
+                self._domain,
+                data={
+                    "from": sender,
+                    "to": [to],
+                    "subject": subject,
+                    "html": html,
+                    "text": text,
+                },
+            )
+            msg_id = getattr(result, "id", "") or ""
+            logger.info("Mailgun sent to %s, id=%s", to, msg_id)
+            return SendResult(success=True, message_id=msg_id, provider="mailgun", raw=result)
+        except ConfigError:
+            raise
+        except Exception as exc:
+            raise SendError(f"Mailgun send failed: {exc}") from exc

herfy_email-0.1.0/herfy_email/providers/sendgrid.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from ..exceptions import ConfigError, SendError
+from ..models import ProviderConfig, SendResult
+from .base import BaseEmailProvider
+
+logger = logging.getLogger(__name__)
+
+
+class SendGridProvider(BaseEmailProvider):
+    """Email provider backed by the SendGrid API (stub — install sendgrid to activate)."""
+
+    def __init__(self, api_key: str, from_address: str) -> None:
+        self._api_key = api_key
+        self._from_address = from_address
+
+    @classmethod
+    def from_config(cls, config: ProviderConfig) -> "SendGridProvider":
+        return cls(api_key=config.api_key, from_address=config.from_address)
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html: str,
+        text: str,
+        from_address: Optional[str] = None,
+    ) -> SendResult:
+        try:
+            import sendgrid as sg  # type: ignore
+            from sendgrid.helpers.mail import Mail  # type: ignore
+        except ImportError as exc:
+            raise ConfigError(
+                "sendgrid package not installed. Run: pip install sendgrid"
+            ) from exc
+
+        sender = from_address or self._from_address
+        try:
+            client = sg.SendGridAPIClient(self._api_key)
+            message = Mail(
+                from_email=sender,
+                to_emails=to,
+                subject=subject,
+                html_content=html,
+                plain_text_content=text,
+            )
+            resp = client.send(message)
+            if resp.status_code >= 400:
+                raise SendError(f"SendGrid send failed: HTTP {resp.status_code}")
+            msg_id = str(resp.headers.get("X-Message-Id", ""))
+            logger.info("SendGrid sent to %s, id=%s", to, msg_id)
+            return SendResult(success=True, message_id=msg_id, provider="sendgrid", raw=resp)
+        except ConfigError:
+            raise
+        except SendError:
+            raise
+        except Exception as exc:
+            raise SendError(f"SendGrid send failed: {exc}") from exc

herfy_email-0.1.0/herfy_email.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: herfy-email
+Version: 0.1.0
+Summary: Provider-abstracted email SDK for Herfy applications — send via Control Center credentials
+Author: Herfy Development Team
+License-Expression: MIT
+Keywords: email,mailgun,sendgrid,herfy,control-center
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: mailgun
+Requires-Dist: mailgun>=1.0.0; extra == "mailgun"
+Provides-Extra: sendgrid
+Requires-Dist: sendgrid>=6.0.0; extra == "sendgrid"
+Provides-Extra: all
+Requires-Dist: mailgun>=1.0.0; extra == "all"
+Requires-Dist: sendgrid>=6.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+
+# herfy-email
+
+Provider-abstracted email SDK for Herfy applications. Send transactional email using only your Control Center `client_id` and `client_secret` — no email provider credentials in app config.
+
+## Installation
+
+```bash
+pip install herfy-email[mailgun]
+```
+
+## Usage
+
+```python
+from herfy_email import HerfyEmailClient, AsyncHerfyEmailClient
+
+# Sync
+client = HerfyEmailClient.from_credentials(
+    client_id="app_pettycash",
+    client_secret="your_secret",
+    control_center_url="https://cc.herfy.com",
+)
+client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")
+
+# Async (FastAPI)
+client = AsyncHerfyEmailClient.from_credentials(
+    client_id="app_pettycash",
+    client_secret="your_secret",
+    control_center_url="https://cc.herfy.com",
+)
+await client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")
+
+# From environment variables (CC_CLIENT_ID / AUTH_CLIENT_ID, CC_CLIENT_SECRET / AUTH_CLIENT_SECRET, CC_URL / CONTROL_CENTER_URL)
+client = HerfyEmailClient.from_env()
+```
+
+## How it works
+
+1. SDK authenticates with Control Center via `POST /api/app-auth/token` (cached, TTL 300s)
+2. SDK fetches provider config from `GET /api/config/email` (cached for process lifetime)
+3. SDK calls the configured provider (Mailgun, SendGrid, …) directly
+
+Switching email providers requires only a Control Center env-var change — zero app changes.
+
+## Provider support
+
+| Provider | Extra |
+|----------|-------|
+| Mailgun  | `pip install herfy-email[mailgun]` |
+| SendGrid | `pip install herfy-email[sendgrid]` |
+
+## Control Center configuration
+
+```env
+EMAIL_PROVIDER=mailgun
+MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxx
+MAILGUN_DOMAIN=mg.herfy.com
+MAILGUN_FROM_ADDRESS=noreply@herfy.com
+```

herfy_email-0.1.0/herfy_email.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+herfy_email/__init__.py
+herfy_email/client.py
+herfy_email/exceptions.py
+herfy_email/models.py
+herfy_email.egg-info/PKG-INFO
+herfy_email.egg-info/SOURCES.txt
+herfy_email.egg-info/dependency_links.txt
+herfy_email.egg-info/requires.txt
+herfy_email.egg-info/top_level.txt
+herfy_email/providers/__init__.py
+herfy_email/providers/base.py
+herfy_email/providers/mailgun.py
+herfy_email/providers/sendgrid.py
+tests/test_client.py
+tests/test_providers.py

herfy_email-0.1.0/herfy_email.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

herfy_email-0.1.0/herfy_email.egg-info/requires.txt

@@ -0,0 +1,17 @@
+httpx>=0.24.0
+
+[all]
+mailgun>=1.0.0
+sendgrid>=6.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+respx>=0.20.0
+black>=23.0.0
+
+[mailgun]
+mailgun>=1.0.0
+
+[sendgrid]
+sendgrid>=6.0.0

herfy_email-0.1.0/herfy_email.egg-info/top_level.txt

@@ -0,0 +1 @@
+herfy_email

herfy_email-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "herfy-email"
+version = "0.1.0"
+description = "Provider-abstracted email SDK for Herfy applications — send via Control Center credentials"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{name = "Herfy Development Team"}]
+keywords = ["email", "mailgun", "sendgrid", "herfy", "control-center"]
+
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+mailgun  = ["mailgun>=1.0.0"]
+sendgrid = ["sendgrid>=6.0.0"]
+all      = ["mailgun>=1.0.0", "sendgrid>=6.0.0"]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "respx>=0.20.0",
+    "black>=23.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["herfy_email*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

herfy_email-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

herfy_email-0.1.0/tests/test_client.py

@@ -0,0 +1,97 @@
+import pytest
+import respx
+import httpx
+from herfy_email.client import HerfyEmailClient
+from herfy_email.exceptions import AuthError, ConfigError
+
+
+CC_URL = "http://cc.test"
+TOKEN_URL = f"{CC_URL}/oauth/token"
+CONFIG_URL = f"{CC_URL}/api/config/email"
+
+TOKEN_RESP = {"access_token": "tok123", "token_type": "bearer", "expires_in": 300}
+CONFIG_RESP = {
+    "provider": "mailgun",
+    "version": 1,
+    "config": {
+        "api_key": "key-test",
+        "domain": "mg.herfy.com",
+        "from_address": "noreply@herfy.com",
+    },
+}
+
+
+@respx.mock
+def test_fetch_token_success():
+    respx.post(TOKEN_URL).mock(return_value=httpx.Response(200, json=TOKEN_RESP))
+    respx.get(CONFIG_URL).mock(return_value=httpx.Response(200, json=CONFIG_RESP))
+
+    client = HerfyEmailClient(
+        client_id="app_test",
+        client_secret="secret",
+        control_center_url=CC_URL,
+    )
+    token = client._get_token()
+    assert token == "tok123"
+
+
+@respx.mock
+def test_bad_credentials_raises_auth_error():
+    respx.post(TOKEN_URL).mock(return_value=httpx.Response(401, json={"detail": "bad"}))
+
+    client = HerfyEmailClient(
+        client_id="bad",
+        client_secret="wrong",
+        control_center_url=CC_URL,
+    )
+    with pytest.raises(AuthError):
+        client._get_token()
+
+
+@respx.mock
+def test_unknown_provider_raises_config_error():
+    respx.post(TOKEN_URL).mock(return_value=httpx.Response(200, json=TOKEN_RESP))
+    respx.get(CONFIG_URL).mock(return_value=httpx.Response(200, json={
+        "provider": "pigeon",
+        "version": 1,
+        "config": {"api_key": "x", "domain": "y", "from_address": "z"},
+    }))
+
+    client = HerfyEmailClient(
+        client_id="app_test",
+        client_secret="secret",
+        control_center_url=CC_URL,
+    )
+    with pytest.raises(ConfigError, match="Unknown email provider"):
+        client._get_provider()
+
+
+@respx.mock
+def test_token_cached_not_refetched():
+    """Second call to _get_token() should not make a second HTTP request."""
+    mock = respx.post(TOKEN_URL).mock(return_value=httpx.Response(200, json=TOKEN_RESP))
+
+    client = HerfyEmailClient(
+        client_id="app_test",
+        client_secret="secret",
+        control_center_url=CC_URL,
+    )
+    client._get_token()
+    client._get_token()
+    assert mock.call_count == 1
+
+
+@respx.mock
+def test_config_401_clears_token_cache():
+    """A 401 on the config endpoint should clear the cached token."""
+    respx.post(TOKEN_URL).mock(return_value=httpx.Response(200, json=TOKEN_RESP))
+    respx.get(CONFIG_URL).mock(return_value=httpx.Response(401))
+
+    client = HerfyEmailClient(
+        client_id="app_test",
+        client_secret="secret",
+        control_center_url=CC_URL,
+    )
+    with pytest.raises(AuthError):
+        client._get_provider()
+    assert client._token is None

herfy_email-0.1.0/tests/test_providers.py

@@ -0,0 +1,24 @@
+import pytest
+from herfy_email.exceptions import ConfigError
+from herfy_email.models import ProviderConfig
+from herfy_email.providers import get_provider
+
+
+def _cfg(provider: str) -> ProviderConfig:
+    return ProviderConfig(
+        provider=provider,
+        api_key="key-test",
+        domain="mg.herfy.com",
+        from_address="noreply@herfy.com",
+    )
+
+
+def test_unknown_provider_raises():
+    with pytest.raises(ConfigError, match="Unknown email provider"):
+        get_provider(_cfg("unknown_provider"))
+
+
+def test_mailgun_provider_returned():
+    from herfy_email.providers.mailgun import MailgunProvider
+    p = get_provider(_cfg("mailgun"))
+    assert isinstance(p, MailgunProvider)