Add Notification Backend Protocol (#24)

Reviewed-on: #24

src/va_agent/notifications.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import logging
 import time
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from google.cloud.firestore_v1.async_client import AsyncClient
@@ -12,8 +12,28 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class NotificationService:
-    """Service for fetching and managing user notifications from Firestore."""
+@runtime_checkable
+class NotificationBackend(Protocol):
+    """Backend-agnostic interface for notification storage."""
+
+    async def get_recent_notifications(self, phone_number: str) -> list[dict[str, Any]]:
+        """Return recent notifications for *phone_number*."""
+        ...
+
+    async def mark_as_notified(
+        self, phone_number: str, notification_ids: list[str]
+    ) -> bool:
+        """Mark the given notification IDs as notified. Return success."""
+        ...
+
+
+class FirestoreNotificationBackend:
+    """Firestore-backed notification backend (read-only).
+
+    Reads notifications from a Firestore document keyed by phone number.
+    Filters by a configurable time window instead of tracking read/unread
+    state — the agent is awareness-only; delivery happens in the app.
+    """
 
     def __init__(
         self,
@@ -21,25 +41,18 @@ class NotificationService:
         db: AsyncClient,
         collection_path: str,
         max_to_notify: int = 5,
+        window_hours: float = 48,
     ) -> None:
-        """Initialize NotificationService.
-
-        Args:
-            db: Firestore async client
-            collection_path: Path to notifications collection
-            max_to_notify: Maximum number of notifications to return
-
-        """
+        """Initialize with Firestore client and collection path."""
         self._db = db
         self._collection_path = collection_path
         self._max_to_notify = max_to_notify
+        self._window_hours = window_hours
 
-    async def get_pending_notifications(
-        self, phone_number: str
-    ) -> list[dict[str, Any]]:
-        """Get pending notifications for a user.
+    async def get_recent_notifications(self, phone_number: str) -> list[dict[str, Any]]:
+        """Get recent notifications for a user.
 
-        Retrieves notifications that have not been notified by the agent yet,
+        Retrieves notifications created within the configured time window,
         ordered by timestamp (most recent first), limited to max_to_notify.
 
         Args:
@@ -57,7 +70,6 @@ class NotificationService:
 
         """
         try:
-            # Query Firestore document by phone number
             doc_ref = self._db.collection(self._collection_path).document(phone_number)
             doc = await doc_ref.get()
 
@@ -74,26 +86,31 @@ class NotificationService:
                 logger.info("No notifications in array for phone: %s", phone_number)
                 return []
 
-            # Filter notifications that have NOT been notified by the agent
-            pending = [
-                n for n in all_notifications if not n.get("notified_by_agent", False)
-            ]
+            cutoff = time.time() - (self._window_hours * 3600)
 
-            if not pending:
+            def _ts(n: dict[str, Any]) -> Any:
+                return n.get(
+                    "timestamp_creacion",
+                    n.get("timestampCreacion", 0),
+                )
+
+            recent = [n for n in all_notifications if _ts(n) >= cutoff]
+
+            if not recent:
                 logger.info(
-                    "All notifications already notified for phone: %s", phone_number
+                    "No notifications within the last %.0fh for phone: %s",
+                    self._window_hours,
+                    phone_number,
                 )
                 return []
 
-            # Sort by timestamp_creacion (most recent first)
-            pending.sort(key=lambda n: n.get("timestamp_creacion", 0), reverse=True)
+            recent.sort(key=_ts, reverse=True)
 
-            # Return top N most recent
-            result = pending[: self._max_to_notify]
+            result = recent[: self._max_to_notify]
 
             logger.info(
-                "Found %d pending notifications for phone: %s (returning top %d)",
-                len(pending),
+                "Found %d recent notifications for phone: %s (returning top %d)",
+                len(recent),
                 phone_number,
                 len(result),
             )
@@ -107,114 +124,109 @@ class NotificationService:
             return result
 
     async def mark_as_notified(
-        self, phone_number: str, notification_ids: list[str]
+        self,
+        phone_number: str,  # noqa: ARG002
+        notification_ids: list[str],  # noqa: ARG002
     ) -> bool:
-        """Mark notifications as notified by the agent.
+        """No-op — the agent is not the delivery mechanism."""
+        return True
 
-        Updates the notifications in Firestore by adding:
-        - notified_by_agent: true
-        - notified_at: current timestamp
 
-        Args:
-            phone_number: User's phone number (document ID)
-            notification_ids: List of id_notificacion values to mark
+class RedisNotificationBackend:
+    """Redis-backed notification backend (read-only)."""
 
-        Returns:
-            True if update was successful, False otherwise
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 6379,
+        max_to_notify: int = 5,
+        window_hours: float = 48,
+    ) -> None:
+        """Initialize with Redis connection parameters."""
+        import redis.asyncio as aioredis  # noqa: PLC0415
 
+        self._client = aioredis.Redis(
+            host=host,
+            port=port,
+            decode_responses=True,
+            socket_connect_timeout=5,
+        )
+        self._max_to_notify = max_to_notify
+        self._window_hours = window_hours
+
+    async def get_recent_notifications(self, phone_number: str) -> list[dict[str, Any]]:
+        """Get recent notifications for a user from Redis.
+
+        Reads from the ``notification:{phone}`` key, parses the JSON
+        payload, and returns notifications created within the configured
+        time window, sorted by creation timestamp (most recent first),
+        limited to *max_to_notify*.
         """
-        if not notification_ids:
-            return True
+        import json  # noqa: PLC0415
 
         try:
-            doc_ref = self._db.collection(self._collection_path).document(phone_number)
-            doc = await doc_ref.get()
+            raw = await self._client.get(f"notification:{phone_number}")
 
-            if not doc.exists:
-                logger.warning(
-                    "Cannot mark notifications as notified: document not found for %s",
+            if not raw:
+                logger.info(
+                    "No notification data in Redis for phone: %s",
                     phone_number,
                 )
-                return False
+                return []
 
-            data = doc.to_dict() or {}
-            notificaciones = data.get("notificaciones", [])
+            data = json.loads(raw)
+            all_notifications: list[dict[str, Any]] = data.get("notificaciones", [])
 
-            if not notificaciones:
-                logger.warning(
-                    "Cannot mark notifications: empty array for %s", phone_number
+            if not all_notifications:
+                logger.info(
+                    "No notifications in array for phone: %s",
+                    phone_number,
                 )
-                return False
+                return []
 
-            # Update matching notifications
-            now = time.time()
-            updated_count = 0
+            cutoff = time.time() - (self._window_hours * 3600)
 
-            for notif in notificaciones:
-                if notif.get("id_notificacion") in notification_ids:
-                    notif["notified_by_agent"] = True
-                    notif["notified_at"] = now
-                    updated_count += 1
-
-            if updated_count == 0:
-                logger.warning(
-                    "No notifications matched IDs for phone: %s", phone_number
+            def _ts(n: dict[str, Any]) -> Any:
+                return n.get(
+                    "timestamp_creacion",
+                    n.get("timestampCreacion", 0),
                 )
-                return False
 
-            # Save back to Firestore
-            await doc_ref.update(
-                {
-                    "notificaciones": notificaciones,
-                    "ultima_actualizacion": now,
-                }
-            )
+            recent = [n for n in all_notifications if _ts(n) >= cutoff]
+
+            if not recent:
+                logger.info(
+                    "No notifications within the last %.0fh for phone: %s",
+                    self._window_hours,
+                    phone_number,
+                )
+                return []
+
+            recent.sort(key=_ts, reverse=True)
+
+            result = recent[: self._max_to_notify]
 
             logger.info(
-                "Marked %d notification(s) as notified for phone: %s",
-                updated_count,
+                "Found %d recent notifications for phone: %s (returning top %d)",
+                len(recent),
                 phone_number,
+                len(result),
             )
 
         except Exception:
             logger.exception(
-                "Failed to mark notifications as notified for phone: %s",
+                "Failed to fetch notifications from Redis for phone: %s",
                 phone_number,
             )
-            return False
+            return []
         else:
-            return True
+            return result
 
-    def format_notification_summary(self, notifications: list[dict[str, Any]]) -> str:
-        """Format notifications into a human-readable summary.
-
-        Args:
-            notifications: List of notification dictionaries
-
-        Returns:
-            Formatted string summarizing the notifications
-
-        """
-        if not notifications:
-            return ""
-
-        count = len(notifications)
-        summary_lines = [f"El usuario tiene {count} notificación(es) pendiente(s):"]
-
-        for i, notif in enumerate(notifications, 1):
-            texto = notif.get("texto", "Sin texto")
-            params = notif.get("parametros", {})
-
-            # Extract key parameters if available
-            amount = params.get("notification_po_amount")
-            tx_id = params.get("notification_po_transaction_id")
-
-            line = f"{i}. {texto}"
-            if amount:
-                line += f" (monto: ${amount})"
-            if tx_id:
-                line += f" [ID: {tx_id}]"
-
-            summary_lines.append(line)
-
-        return "\n".join(summary_lines)
+    async def mark_as_notified(
+        self,
+        phone_number: str,  # noqa: ARG002
+        notification_ids: list[str],  # noqa: ARG002
+    ) -> bool:
+        """No-op — the agent is not the delivery mechanism."""
+        return True