homesec 0.1.0__py3-none-any.whl

homesec/plugins/notifiers/sendgrid_email.py

@@ -0,0 +1,228 @@
+"""SendGrid email notifier plugin."""
+
+from __future__ import annotations
+
+import asyncio
+import html
+import logging
+import os
+from collections import defaultdict
+
+import aiohttp
+
+from homesec.models.alert import Alert
+from homesec.models.config import SendGridEmailConfig
+from homesec.models.vlm import SequenceAnalysis
+from homesec.interfaces import Notifier
+
+logger = logging.getLogger(__name__)
+
+
+class SendGridEmailNotifier(Notifier):
+    """SendGrid email notifier for HomeSec alerts."""
+
+    def __init__(self, config: SendGridEmailConfig) -> None:
+        self._api_key_env = config.api_key_env
+        self._from_email = config.from_email
+        self._from_name = config.from_name
+        self._to_emails = list(config.to_emails)
+        self._cc_emails = list(config.cc_emails)
+        self._bcc_emails = list(config.bcc_emails)
+        self._subject_template = config.subject_template
+        self._text_template = config.text_template
+        self._html_template = config.html_template
+        self._timeout_s = float(config.request_timeout_s)
+        self._api_base = config.api_base.rstrip("/")
+
+        self._api_key = os.getenv(self._api_key_env)
+        if not self._api_key:
+            logger.warning("SendGrid API key not found in env: %s", self._api_key_env)
+
+        self._session: aiohttp.ClientSession | None = None
+        self._shutdown_called = False
+
+    async def send(self, alert: Alert) -> None:
+        """Send alert notification via SendGrid."""
+        if self._shutdown_called:
+            raise RuntimeError("Notifier has been shut down")
+        if not self._api_key:
+            raise RuntimeError("SendGrid API key missing from environment")
+
+        subject = self._render_subject(alert)
+        text_body = self._render_text(alert) if self._text_template else ""
+        html_body = self._render_html(alert) if self._html_template else ""
+        if not text_body and not html_body:
+            raise RuntimeError("SendGrid email requires text or html content")
+
+        payload = self._build_payload(subject, text_body, html_body)
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        url = f"{self._api_base}/mail/send"
+        session = await self._get_session()
+
+        async with session.post(url, json=payload, headers=headers) as response:
+            if response.status >= 400:
+                details = await response.text()
+                raise RuntimeError(
+                    f"SendGrid email send failed ({response.status}): {details}"
+                )
+
+        logger.info(
+            "Sent SendGrid email alert: to=%s clip_id=%s",
+            ",".join(self._to_emails),
+            alert.clip_id,
+        )
+
+    async def ping(self) -> bool:
+        """Health check - verify SendGrid credentials and connectivity."""
+        if self._shutdown_called or not self._api_key:
+            return False
+
+        url = f"{self._api_base}/user/profile"
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        session = await self._get_session()
+        try:
+            async with session.get(url, headers=headers) as response:
+                if response.status >= 400:
+                    return False
+                await response.read()
+        except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+            logger.warning("SendGrid ping failed: %s", e)
+            return False
+        return True
+
+    async def shutdown(self, timeout: float | None = None) -> None:
+        """Cleanup resources - close HTTP session."""
+        _ = timeout
+        if self._shutdown_called:
+            return
+        self._shutdown_called = True
+
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            timeout = aiohttp.ClientTimeout(total=self._timeout_s)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+        return self._session
+
+    def _build_payload(self, subject: str, text_body: str, html_body: str) -> dict[str, object]:
+        personalization: dict[str, object] = {
+            "to": [{"email": email} for email in self._to_emails],
+            "subject": subject,
+        }
+        if self._cc_emails:
+            personalization["cc"] = [{"email": email} for email in self._cc_emails]
+        if self._bcc_emails:
+            personalization["bcc"] = [{"email": email} for email in self._bcc_emails]
+
+        sender: dict[str, str] = {"email": self._from_email}
+        if self._from_name:
+            sender["name"] = self._from_name
+
+        content: list[dict[str, str]] = []
+        if text_body:
+            content.append({"type": "text/plain", "value": text_body})
+        if html_body:
+            content.append({"type": "text/html", "value": html_body})
+
+        return {
+            "personalizations": [personalization],
+            "from": sender,
+            "content": content,
+        }
+
+    def _build_context(self, alert: Alert) -> defaultdict[str, str]:
+        view_url = alert.view_url or alert.storage_uri or "n/a"
+        analysis_html = self._render_analysis_html(alert.analysis)
+        return defaultdict(
+            str,
+            {
+                "camera_name": alert.camera_name,
+                "clip_id": alert.clip_id,
+                "risk_level": alert.risk_level or "unknown",
+                "activity_type": alert.activity_type or "unknown",
+                "notify_reason": alert.notify_reason,
+                "summary": alert.summary or "",
+                "view_url": view_url,
+                "storage_uri": alert.storage_uri or "",
+                "ts": alert.ts.isoformat(),
+                "upload_failed": str(alert.upload_failed),
+                "analysis_html": analysis_html,
+            },
+        )
+
+    def _render_subject(self, alert: Alert) -> str:
+        return self._subject_template.format_map(self._build_context(alert)).strip()
+
+    def _render_text(self, alert: Alert) -> str:
+        return self._text_template.format_map(self._build_context(alert)).strip()
+
+    def _render_html(self, alert: Alert) -> str:
+        return self._html_template.format_map(self._build_context(alert)).strip()
+
+    def _render_analysis_html(self, analysis: SequenceAnalysis | None) -> str:
+        if analysis is None:
+            return ""
+        return self._render_value_html(analysis.model_dump())
+
+    def _render_value_html(self, value: object) -> str:
+        match value:
+            case None:
+                return "<em>n/a</em>"
+            case dict() as mapping:
+                return self._render_dict_html(mapping)
+            case list() as items:
+                return self._render_list_html(items)
+            case _:
+                return html.escape(str(value))
+
+    def _render_dict_html(self, mapping: dict[str, object]) -> str:
+        items = []
+        for key, value in mapping.items():
+            rendered_value = self._render_value_html(value)
+            items.append(
+                f"<li><strong>{html.escape(str(key))}:</strong> {rendered_value}</li>"
+            )
+        return "<ul>" + "".join(items) + "</ul>"
+
+    def _render_list_html(self, items: list[object]) -> str:
+        if not items:
+            return "<ul><li>none</li></ul>"
+
+        rendered_items = []
+        for idx, item in enumerate(items, start=1):
+            rendered_value = self._render_value_html(item)
+            label = f"Item {idx}"
+            if isinstance(item, dict):
+                rendered_items.append(f"<li>{html.escape(label)}{rendered_value}</li>")
+            else:
+                rendered_items.append(f"<li>{rendered_value}</li>")
+        return "<ul>" + "".join(rendered_items) + "</ul>"
+
+
+# Plugin registration
+from typing import cast
+from pydantic import BaseModel
+from homesec.plugins.notifiers import NotifierPlugin, notifier_plugin
+from homesec.interfaces import Notifier
+
+
+@notifier_plugin(name="sendgrid_email")
+def sendgrid_email_plugin() -> NotifierPlugin:
+    """SendGrid email notifier plugin factory.
+
+    Returns:
+        NotifierPlugin for SendGrid email notifications
+    """
+    from homesec.models.config import SendGridEmailConfig
+
+    def factory(cfg: BaseModel) -> Notifier:
+        # Config is already validated by app.py, just cast
+        return SendGridEmailNotifier(cast(SendGridEmailConfig, cfg))
+
+    return NotifierPlugin(
+        name="sendgrid_email",
+        config_model=SendGridEmailConfig,
+        factory=factory,
+    )

homesec/plugins/storage/__init__.py

@@ -0,0 +1,116 @@
+"""Storage backend plugins and registry."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Callable, TypeVar
+
+from pydantic import BaseModel
+
+from homesec.interfaces import StorageBackend
+from homesec.models.config import StorageConfig
+
+logger = logging.getLogger(__name__)
+
+# Type alias for clarity
+StorageFactory = Callable[[BaseModel], StorageBackend]
+
+
+@dataclass(frozen=True)
+class StoragePlugin:
+    """Metadata for a storage backend plugin."""
+
+    name: str
+    config_model: type[BaseModel]
+    factory: StorageFactory
+
+
+STORAGE_REGISTRY: dict[str, StoragePlugin] = {}
+
+
+def register_storage(plugin: StoragePlugin) -> None:
+    """Register a storage plugin with collision detection.
+
+    Args:
+        plugin: Storage plugin to register
+
+    Raises:
+        ValueError: If a plugin with the same name is already registered
+    """
+    if plugin.name in STORAGE_REGISTRY:
+        raise ValueError(
+            f"Storage plugin '{plugin.name}' is already registered. "
+            f"Plugin names must be unique across all storage plugins."
+        )
+    STORAGE_REGISTRY[plugin.name] = plugin
+
+
+T = TypeVar("T", bound=Callable[[], StoragePlugin])
+
+
+def storage_plugin(name: str) -> Callable[[T], T]:
+    """Decorator to register a storage backend plugin.
+
+    Usage:
+        @storage_plugin(name="my_storage")
+        def my_storage_plugin() -> StoragePlugin:
+            return StoragePlugin(...)
+
+    Args:
+        name: Plugin name (for validation only - must match plugin.name)
+
+    Returns:
+        Decorator function that registers the plugin
+    """
+
+    def decorator(factory_fn: T) -> T:
+        plugin = factory_fn()
+        register_storage(plugin)
+        return factory_fn
+
+    return decorator
+
+
+def create_storage(config: StorageConfig) -> StorageBackend:
+    """Create storage backend from config using plugin registry.
+
+    Args:
+        config: Storage configuration with backend name and backend-specific settings
+
+    Returns:
+        Instantiated storage backend
+
+    Raises:
+        RuntimeError: If backend is unknown or backend-specific config is missing
+    """
+    backend_name = config.backend.lower()
+
+    if backend_name not in STORAGE_REGISTRY:
+        available = ", ".join(sorted(STORAGE_REGISTRY.keys()))
+        raise RuntimeError(
+            f"Unknown storage backend: '{backend_name}'. Available: {available}"
+        )
+
+    plugin = STORAGE_REGISTRY[backend_name]
+
+    # Extract backend-specific config using attribute access
+    # e.g., config.dropbox, config.local
+    specific_config = getattr(config, backend_name, None)
+    if specific_config is None:
+        raise RuntimeError(
+            f"Missing '{backend_name}' config in storage section. "
+            f"Add 'storage.{backend_name}' to your config."
+        )
+
+    return plugin.factory(specific_config)
+
+
+__all__ = [
+    "StoragePlugin",
+    "StorageFactory",
+    "STORAGE_REGISTRY",
+    "register_storage",
+    "storage_plugin",
+    "create_storage",
+]

homesec/plugins/storage/dropbox.py

@@ -0,0 +1,272 @@
+"""Dropbox storage backend plugin."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path, PurePosixPath
+from typing import BinaryIO
+import dropbox  # type: ignore
+
+from homesec.models.config import DropboxStorageConfig
+from homesec.models.storage import StorageUploadResult
+from homesec.interfaces import StorageBackend
+
+logger = logging.getLogger(__name__)
+
+CHUNK_SIZE = 4 * 1024 * 1024
+
+
+class DropboxStorage(StorageBackend):
+    """Dropbox storage backend.
+    
+    Uses dropbox SDK for file operations.
+    Implements idempotent uploads with overwrite mode.
+    
+    Supports two auth modes:
+    1. Simple token: Set DROPBOX_TOKEN env var
+    2. Refresh token flow: Set DROPBOX_APP_KEY, DROPBOX_APP_SECRET, DROPBOX_REFRESH_TOKEN
+    """
+
+    def __init__(self, config: DropboxStorageConfig) -> None:
+        """Initialize Dropbox storage with config validation.
+        
+        Required config:
+            root: Root path in Dropbox (e.g., /homecam)
+            
+        Optional config:
+            token_env: Env var name for simple token auth (default: DROPBOX_TOKEN)
+            app_key_env: Env var name for app key (default: DROPBOX_APP_KEY)
+            app_secret_env: Env var name for app secret (default: DROPBOX_APP_SECRET)
+            refresh_token_env: Env var name for refresh token (default: DROPBOX_REFRESH_TOKEN)
+            web_url_prefix: URL prefix for view links (default: https://www.dropbox.com/home)
+        """
+        self.root = str(config.root).rstrip("/")
+        self.web_url_prefix = str(config.web_url_prefix)
+        
+        # Initialize Dropbox client using env vars
+        self.client = self._create_client(config)
+        self._shutdown_called = False
+        
+        logger.info("DropboxStorage initialized: root=%s", self.root)
+
+    def _create_client(self, config: DropboxStorageConfig) -> dropbox.Dropbox:
+        """Create Dropbox client from env vars.
+        
+        Tries simple token first, then falls back to refresh token flow.
+        """
+        # Try simple token auth first
+        token_var = str(config.token_env)
+        token = os.getenv(token_var)
+        if token:
+            logger.info("Using Dropbox simple token auth")
+            return dropbox.Dropbox(token)
+        
+        # Try refresh token flow
+        app_key_var = str(config.app_key_env)
+        app_secret_var = str(config.app_secret_env)
+        refresh_token_var = str(config.refresh_token_env)
+        
+        app_key = os.getenv(app_key_var)
+        app_secret = os.getenv(app_secret_var)
+        refresh_token = os.getenv(refresh_token_var)
+        
+        if app_key and app_secret and refresh_token:
+            logger.info("Using Dropbox refresh token auth")
+            return dropbox.Dropbox(
+                app_key=app_key,
+                app_secret=app_secret,
+                oauth2_refresh_token=refresh_token,
+            )
+        
+        raise ValueError(
+            f"Missing Dropbox credentials. Set {token_var} or "
+            f"({app_key_var}, {app_secret_var}, {refresh_token_var})."
+        )
+
+    async def put_file(self, local_path: Path, dest_path: str) -> StorageUploadResult:
+        """Upload file to Dropbox."""
+        self._ensure_open()
+
+        dest_path = self._full_dest_path(dest_path)
+
+        # Run blocking upload in executor
+        await asyncio.to_thread(self._upload_file, local_path, dest_path)
+
+        storage_uri = f"dropbox:{dest_path}"
+        view_url = await self.get_view_url(storage_uri)
+        return StorageUploadResult(storage_uri=storage_uri, view_url=view_url)
+
+    async def get_view_url(self, storage_uri: str) -> str | None:
+        """Compute a web-accessible URL for a Dropbox storage URI."""
+        self._ensure_open()
+        if not storage_uri.startswith("dropbox:"):
+            return None
+        path = storage_uri[8:]
+        prefix = self.web_url_prefix.rstrip("/")
+        return f"{prefix}{path}"
+
+    def _upload_file(self, local_path: Path, dest_path: str) -> None:
+        """Upload file (blocking operation)."""
+        file_size = local_path.stat().st_size
+        with open(local_path, "rb") as f:
+            if file_size <= CHUNK_SIZE:
+                self.client.files_upload(
+                    f.read(),
+                    dest_path,
+                    mode=dropbox.files.WriteMode.overwrite,
+                )
+            else:
+                self._upload_file_chunked(f, dest_path, file_size)
+        logger.debug("Uploaded to Dropbox: %s", dest_path)
+
+    def _upload_file_chunked(self, file_handle: BinaryIO, dest_path: str, file_size: int) -> None:
+        """Upload file in chunks using a Dropbox upload session."""
+        chunk = file_handle.read(CHUNK_SIZE)
+        if not chunk:
+            raise ValueError("Cannot upload empty file")
+
+        session = self.client.files_upload_session_start(chunk)
+        cursor = dropbox.files.UploadSessionCursor(
+            session_id=session.session_id,
+            offset=file_handle.tell(),
+        )
+        commit = dropbox.files.CommitInfo(
+            path=dest_path,
+            mode=dropbox.files.WriteMode.overwrite,
+        )
+
+        while file_handle.tell() < file_size:
+            chunk = file_handle.read(CHUNK_SIZE)
+            if not chunk:
+                raise RuntimeError("Unexpected end of file during chunked upload")
+            if file_handle.tell() >= file_size:
+                self.client.files_upload_session_finish(chunk, cursor, commit)
+                return
+            self.client.files_upload_session_append_v2(chunk, cursor)
+            cursor.offset = file_handle.tell()
+
+    async def get(self, storage_uri: str, local_path: Path) -> None:
+        """Download file from Dropbox."""
+        self._ensure_open()
+        
+        # Parse storage_uri
+        if not storage_uri.startswith("dropbox:"):
+            raise ValueError(f"Invalid storage_uri: {storage_uri}")
+        
+        remote_path = storage_uri[8:]  # Strip "dropbox:"
+        
+        # Run blocking download in executor
+        await asyncio.to_thread(self._download_file, remote_path, local_path)
+
+    def _download_file(self, remote_path: str, local_path: Path) -> None:
+        """Download file (blocking operation)."""
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        self.client.files_download_to_file(str(local_path), remote_path)
+        logger.debug("Downloaded from Dropbox: %s", remote_path)
+
+    async def exists(self, storage_uri: str) -> bool:
+        """Check if file exists in Dropbox."""
+        self._ensure_open()
+
+        # Parse storage_uri
+        if not storage_uri.startswith("dropbox:"):
+            return False
+
+        remote_path = storage_uri[8:]
+
+        # Run blocking check in executor
+        return await asyncio.to_thread(self._check_exists, remote_path)
+
+    async def delete(self, storage_uri: str) -> None:
+        """Delete file from Dropbox.
+
+        Idempotent: missing files are treated as success.
+        """
+        self._ensure_open()
+
+        if not storage_uri.startswith("dropbox:"):
+            raise ValueError(f"Invalid storage_uri: {storage_uri}")
+
+        remote_path = storage_uri[8:]
+
+        try:
+            await asyncio.to_thread(self.client.files_delete_v2, remote_path)
+        except dropbox.exceptions.ApiError as exc:
+            # Treat missing file as success
+            err = getattr(exc, "error", None)
+            try:
+                if err is not None and getattr(err, "is_path_lookup", lambda: False)():
+                    lookup = err.get_path_lookup()
+                    if getattr(lookup, "is_not_found", lambda: False)():
+                        return
+            except Exception:
+                pass
+            raise
+
+    def _check_exists(self, remote_path: str) -> bool:
+        """Check if file exists (blocking operation)."""
+        try:
+            self.client.files_get_metadata(remote_path)
+            return True
+        except dropbox.exceptions.ApiError:
+            return False
+
+    async def ping(self) -> bool:
+        """Health check - verify Dropbox connection."""
+        try:
+            await asyncio.to_thread(self.client.users_get_current_account)
+            return True
+        except Exception as e:
+            logger.warning("Dropbox ping failed: %s", e, exc_info=True)
+            return False
+
+    async def shutdown(self, timeout: float | None = None) -> None:
+        """Cleanup resources."""
+        _ = timeout
+        if self._shutdown_called:
+            return
+        
+        self._shutdown_called = True
+        logger.info("DropboxStorage closed")
+
+    def _ensure_open(self) -> None:
+        if self._shutdown_called:
+            raise RuntimeError("Storage has been shut down")
+
+    def _full_dest_path(self, dest_path: str) -> str:
+        cleaned = str(dest_path).lstrip("/")
+        if not cleaned or "\\" in cleaned:
+            raise ValueError(f"Invalid dest_path: {dest_path}")
+        path = PurePosixPath(cleaned)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"Invalid dest_path: {dest_path}")
+        return f"{self.root}/{path}"
+
+
+# Plugin registration
+from typing import cast
+from pydantic import BaseModel
+from homesec.plugins.storage import StoragePlugin, storage_plugin
+from homesec.interfaces import StorageBackend
+
+
+@storage_plugin(name="dropbox")
+def dropbox_storage_plugin() -> StoragePlugin:
+    """Dropbox storage plugin factory.
+
+    Returns:
+        StoragePlugin for Dropbox cloud storage
+    """
+    from homesec.models.config import DropboxStorageConfig
+
+    def factory(cfg: BaseModel) -> StorageBackend:
+        # Config is already validated by pydantic when loaded
+        return DropboxStorage(cast(DropboxStorageConfig, cfg))
+
+    return StoragePlugin(
+        name="dropbox",
+        config_model=DropboxStorageConfig,
+        factory=factory,
+    )