msaas-notifications 0.1.0__tar.gz

msaas_notifications-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_notifications-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: msaas-notifications
+Version: 0.1.0
+Summary: In-app notification system with PostgreSQL storage and FastAPI router
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

msaas_notifications-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "msaas-notifications"
+version = "0.1.0"
+description = "In-app notification system with PostgreSQL storage and FastAPI router"
+requires-python = ">=3.12"
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0",
+    "asyncpg>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/notifications"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_notifications-0.1.0/src/notifications/__init__.py

@@ -0,0 +1,28 @@
+"""Willian Notifications -- In-app notification system with PostgreSQL storage."""
+
+from notifications.config import NotificationConfig, init_notifications
+from notifications.models import (
+    CreateNotification,
+    Notification,
+    NotificationPreferences,
+)
+from notifications.router import NotificationRouter
+from notifications.service import (
+    get_notifications,
+    mark_all_read,
+    mark_read,
+    send_notification,
+)
+
+__all__ = [
+    "CreateNotification",
+    "Notification",
+    "NotificationConfig",
+    "NotificationPreferences",
+    "NotificationRouter",
+    "get_notifications",
+    "init_notifications",
+    "mark_all_read",
+    "mark_read",
+    "send_notification",
+]

msaas_notifications-0.1.0/src/notifications/config.py

@@ -0,0 +1,54 @@
+"""Notification module configuration and initialization."""
+
+from __future__ import annotations
+
+import asyncpg
+from pydantic import BaseModel
+
+_config: NotificationConfig | None = None
+_pool: asyncpg.Pool | None = None
+
+
+class NotificationConfig(BaseModel):
+    """Configuration for the notification module."""
+
+    database_url: str
+    max_per_page: int = 50
+    retention_days: int = 90
+
+
+async def init_notifications(config: NotificationConfig) -> None:
+    """Initialize the notification module with the given configuration.
+
+    Creates an asyncpg connection pool and stores the config globally.
+    Must be called before any store or service operations.
+    """
+    global _config, _pool
+    _config = config
+    _pool = await asyncpg.create_pool(dsn=config.database_url, min_size=2, max_size=10)
+
+
+def get_config() -> NotificationConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_notifications() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError(
+            "Notification module not initialized. Call init_notifications() first."
+        )
+    return _config
+
+
+def get_pool() -> asyncpg.Pool:
+    """Return the current connection pool.
+
+    Raises:
+        RuntimeError: If init_notifications() has not been called.
+    """
+    if _pool is None:
+        raise RuntimeError(
+            "Notification module not initialized. Call init_notifications() first."
+        )
+    return _pool

msaas_notifications-0.1.0/src/notifications/models.py

@@ -0,0 +1,66 @@
+"""Pydantic models for the notification module."""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class NotificationType(str, enum.Enum):
+    """Type of notification, determines display styling."""
+
+    INFO = "info"
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class DigestFrequency(str, enum.Enum):
+    """How often the user receives digest emails."""
+
+    NONE = "none"
+    DAILY = "daily"
+    WEEKLY = "weekly"
+
+
+class Notification(BaseModel):
+    """A single notification record."""
+
+    id: UUID
+    user_id: str
+    type: NotificationType
+    title: str
+    message: str
+    action_url: str | None = None
+    read: bool = False
+    created_at: datetime
+
+
+class NotificationPreferences(BaseModel):
+    """User notification preferences."""
+
+    user_id: str
+    email_enabled: bool = True
+    in_app_enabled: bool = True
+    digest_frequency: DigestFrequency = DigestFrequency.NONE
+
+
+class CreateNotification(BaseModel):
+    """Payload for creating a new notification."""
+
+    user_id: str
+    type: NotificationType = NotificationType.INFO
+    title: str = Field(min_length=1, max_length=255)
+    message: str = Field(min_length=1, max_length=2000)
+    action_url: str | None = None
+
+
+class UpdatePreferences(BaseModel):
+    """Payload for updating notification preferences."""
+
+    email_enabled: bool | None = None
+    in_app_enabled: bool | None = None
+    digest_frequency: DigestFrequency | None = None

msaas_notifications-0.1.0/src/notifications/router.py

@@ -0,0 +1,150 @@
+"""FastAPI router for notification endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+from notifications.models import (
+    Notification,
+    NotificationPreferences,
+    UpdatePreferences,
+)
+from notifications.service import (
+    get_notifications,
+    mark_all_read,
+    mark_read,
+)
+from notifications.store import (
+    get_preferences,
+    get_unread_count,
+    set_preferences,
+)
+from errors import AuthorizationError, BusinessLogicError, ConflictError, NotFoundError, ValidationError
+from api_core.responses import ApiResponse, PaginatedResponse
+
+
+class NotificationListResponse(BaseModel):
+    """Response model for paginated notification list."""
+
+    items: list[Notification]
+    total: int
+    unread_count: int
+    page: int
+    per_page: int
+
+
+class UnreadCountResponse(BaseModel):
+    """Response model for unread count."""
+
+    count: int
+
+
+class MarkReadResponse(BaseModel):
+    """Response model for mark-read operations."""
+
+    success: bool
+
+
+class MarkAllReadResponse(BaseModel):
+    """Response model for mark-all-read operations."""
+
+    updated: int
+
+
+def NotificationRouter(
+    *,
+    get_user_id: Any,
+    prefix: str = "/notifications",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """Create a FastAPI router for notification endpoints.
+
+    Args:
+        get_user_id: A FastAPI dependency that returns the current user's ID.
+            Must be an async or sync callable compatible with ``Depends()``.
+        prefix: URL prefix for all routes. Defaults to ``/notifications``.
+        tags: OpenAPI tags for the router.
+
+    Returns:
+        A configured APIRouter.
+
+    Example::
+
+        from fastapi import Depends, Request
+
+        async def get_current_user_id(request: Request) -> str:
+            return request.state.user_id
+
+        router = NotificationRouter(get_user_id=get_current_user_id)
+        app.include_router(router)
+    """
+    from fastapi import Depends
+
+    router = APIRouter(prefix=prefix, tags=tags or ["notifications"])
+
+    @router.get("", response_model=NotificationListResponse)
+    async def list_notifications(
+        user_id: str = Depends(get_user_id),
+        page: int = Query(1, ge=1, description="Page number"),
+        unread_only: bool = Query(False, description="Only return unread notifications"),
+    ) -> NotificationListResponse:
+        """List notifications for the current user with pagination."""
+        result = await get_notifications(user_id, page=page, unread_only=unread_only)
+        return NotificationListResponse(**result)
+
+    @router.get("/count", response_model=UnreadCountResponse)
+    async def unread_count(
+        user_id: str = Depends(get_user_id),
+    ) -> UnreadCountResponse:
+        """Get the number of unread notifications for the current user."""
+        count = await get_unread_count(user_id)
+        return UnreadCountResponse(count=count)
+
+    @router.patch("/{notification_id}/read", response_model=MarkReadResponse)
+    async def mark_notification_read(
+        notification_id: UUID,
+        user_id: str = Depends(get_user_id),
+    ) -> MarkReadResponse:
+        """Mark a single notification as read."""
+        success = await mark_read(notification_id)
+        if not success:
+            raise NotFoundError("Notification not found")
+        return MarkReadResponse(success=True)
+
+    @router.post("/read-all", response_model=MarkAllReadResponse)
+    async def mark_all_notifications_read(
+        user_id: str = Depends(get_user_id),
+    ) -> MarkAllReadResponse:
+        """Mark all unread notifications as read for the current user."""
+        updated = await mark_all_read(user_id)
+        return MarkAllReadResponse(updated=updated)
+
+    @router.get("/preferences", response_model=NotificationPreferences)
+    async def get_notification_preferences(
+        user_id: str = Depends(get_user_id),
+    ) -> NotificationPreferences:
+        """Get notification preferences for the current user."""
+        return await get_preferences(user_id)
+
+    @router.put("/preferences", response_model=NotificationPreferences)
+    async def update_notification_preferences(
+        body: UpdatePreferences,
+        user_id: str = Depends(get_user_id),
+    ) -> NotificationPreferences:
+        """Update notification preferences for the current user."""
+        current = await get_preferences(user_id)
+
+        updated = NotificationPreferences(
+            user_id=user_id,
+            email_enabled=body.email_enabled if body.email_enabled is not None else current.email_enabled,
+            in_app_enabled=body.in_app_enabled if body.in_app_enabled is not None else current.in_app_enabled,
+            digest_frequency=body.digest_frequency if body.digest_frequency is not None else current.digest_frequency,
+        )
+
+        return await set_preferences(user_id, updated)
+
+    return router

msaas_notifications-0.1.0/src/notifications/service.py

@@ -0,0 +1,146 @@
+"""High-level notification service for business logic orchestration."""
+
+from __future__ import annotations
+
+import uuid
+
+from notifications.config import get_config
+from notifications.models import (
+    CreateNotification,
+    Notification,
+    NotificationType,
+)
+from notifications.store import (
+    get_by_user,
+    get_total_count,
+    get_unread_count,
+    insert,
+    insert_bulk,
+)
+from notifications.store import mark_all_read as store_mark_all_read
+from notifications.store import mark_read as store_mark_read
+from errors import NotFoundError, ValidationError
+
+
+async def send_notification(
+    user_id: str,
+    type: NotificationType | str,
+    title: str,
+    message: str,
+    action_url: str | None = None,
+) -> Notification:
+    """Create and store a single notification for a user.
+
+    Args:
+        user_id: The target user's ID.
+        type: Notification type (info, success, warning, error).
+        title: Short notification title.
+        message: Notification body.
+        action_url: Optional URL the notification links to.
+
+    Returns:
+        The created Notification.
+    """
+    notification_type = NotificationType(type) if isinstance(type, str) else type
+
+    return await insert(
+        CreateNotification(
+            user_id=user_id,
+            type=notification_type,
+            title=title,
+            message=message,
+            action_url=action_url,
+        )
+    )
+
+
+async def send_bulk(
+    user_ids: list[str],
+    type: NotificationType | str,
+    title: str,
+    message: str,
+    action_url: str | None = None,
+) -> list[Notification]:
+    """Create the same notification for multiple users in a single transaction.
+
+    Args:
+        user_ids: List of target user IDs.
+        type: Notification type.
+        title: Short notification title.
+        message: Notification body.
+        action_url: Optional URL the notification links to.
+
+    Returns:
+        List of created Notifications.
+    """
+    notification_type = NotificationType(type) if isinstance(type, str) else type
+
+    payloads = [
+        CreateNotification(
+            user_id=uid,
+            type=notification_type,
+            title=title,
+            message=message,
+            action_url=action_url,
+        )
+        for uid in user_ids
+    ]
+
+    return await insert_bulk(payloads)
+
+
+async def get_notifications(
+    user_id: str,
+    page: int = 1,
+    unread_only: bool = False,
+) -> dict:
+    """Fetch a paginated list of notifications for a user.
+
+    Args:
+        user_id: The user to fetch notifications for.
+        page: Page number (1-indexed).
+        unread_only: If True, only return unread notifications.
+
+    Returns:
+        Dictionary with keys: items, total, unread_count, page, per_page.
+    """
+    config = get_config()
+    per_page = config.max_per_page
+    offset = (max(1, page) - 1) * per_page
+
+    items = await get_by_user(user_id, limit=per_page, offset=offset, unread_only=unread_only)
+    total = await get_total_count(user_id, unread_only=unread_only)
+    unread_count = await get_unread_count(user_id)
+
+    return {
+        "items": items,
+        "total": total,
+        "unread_count": unread_count,
+        "page": page,
+        "per_page": per_page,
+    }
+
+
+async def mark_read(notification_id: str | uuid.UUID) -> bool:
+    """Mark a single notification as read.
+
+    Args:
+        notification_id: The notification ID (string or UUID).
+
+    Returns:
+        True if the notification was found and updated, False otherwise.
+    """
+    nid = uuid.UUID(notification_id) if isinstance(notification_id, str) else notification_id
+    return await store_mark_read(nid)
+
+
+async def mark_all_read(user_id: str) -> int:
+    """Mark all unread notifications for a user as read.
+
+    Args:
+        user_id: The user whose notifications should be marked read.
+
+    Returns:
+        The number of notifications that were updated.
+    """
+    return await store_mark_all_read(user_id)

msaas_notifications-0.1.0/src/notifications/store.py

@@ -0,0 +1,290 @@
+"""PostgreSQL storage operations for notifications (asyncpg, no ORM)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from notifications.config import get_pool
+from notifications.models import (
+    CreateNotification,
+    DigestFrequency,
+    Notification,
+    NotificationPreferences,
+    NotificationType,
+)
+
+
+async def create_tables() -> None:
+    """Create the notifications and notification_preferences tables if they do not exist."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS notifications (
+                id UUID PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                type TEXT NOT NULL DEFAULT 'info',
+                title TEXT NOT NULL,
+                message TEXT NOT NULL,
+                action_url TEXT,
+                read BOOLEAN NOT NULL DEFAULT FALSE,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+        """)
+        await conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_notifications_user_id
+            ON notifications (user_id, created_at DESC)
+        """)
+        await conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_notifications_user_unread
+            ON notifications (user_id) WHERE read = FALSE
+        """)
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS notification_preferences (
+                user_id TEXT PRIMARY KEY,
+                email_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+                in_app_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+                digest_frequency TEXT NOT NULL DEFAULT 'none'
+            )
+        """)
+
+
+def _row_to_notification(row: dict) -> Notification:
+    """Convert an asyncpg Record to a Notification model."""
+    return Notification(
+        id=row["id"],
+        user_id=row["user_id"],
+        type=NotificationType(row["type"]),
+        title=row["title"],
+        message=row["message"],
+        action_url=row["action_url"],
+        read=row["read"],
+        created_at=row["created_at"],
+    )
+
+
+async def insert(notification: CreateNotification) -> Notification:
+    """Insert a single notification and return it."""
+    pool = get_pool()
+    notification_id = uuid.uuid4()
+    now = datetime.now(timezone.utc)
+
+    async with pool.acquire() as conn:
+        await conn.execute(
+            """
+            INSERT INTO notifications (id, user_id, type, title, message, action_url, read, created_at)
+            VALUES ($1, $2, $3, $4, $5, $6, FALSE, $7)
+            """,
+            notification_id,
+            notification.user_id,
+            notification.type.value,
+            notification.title,
+            notification.message,
+            notification.action_url,
+            now,
+        )
+
+    return Notification(
+        id=notification_id,
+        user_id=notification.user_id,
+        type=notification.type,
+        title=notification.title,
+        message=notification.message,
+        action_url=notification.action_url,
+        read=False,
+        created_at=now,
+    )
+
+
+async def insert_bulk(notifications: list[CreateNotification]) -> list[Notification]:
+    """Insert multiple notifications in a single transaction."""
+    pool = get_pool()
+    now = datetime.now(timezone.utc)
+    results: list[Notification] = []
+
+    async with pool.acquire() as conn:
+        async with conn.transaction():
+            stmt = await conn.prepare(
+                """
+                INSERT INTO notifications (id, user_id, type, title, message, action_url, read, created_at)
+                VALUES ($1, $2, $3, $4, $5, $6, FALSE, $7)
+                """
+            )
+            for n in notifications:
+                nid = uuid.uuid4()
+                await stmt.fetch(
+                    nid,
+                    n.user_id,
+                    n.type.value,
+                    n.title,
+                    n.message,
+                    n.action_url,
+                    now,
+                )
+                results.append(
+                    Notification(
+                        id=nid,
+                        user_id=n.user_id,
+                        type=n.type,
+                        title=n.title,
+                        message=n.message,
+                        action_url=n.action_url,
+                        read=False,
+                        created_at=now,
+                    )
+                )
+
+    return results
+
+
+async def get_by_user(
+    user_id: str,
+    limit: int = 50,
+    offset: int = 0,
+    unread_only: bool = False,
+) -> list[Notification]:
+    """Fetch notifications for a user, newest first."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        if unread_only:
+            rows = await conn.fetch(
+                """
+                SELECT id, user_id, type, title, message, action_url, read, created_at
+                FROM notifications
+                WHERE user_id = $1 AND read = FALSE
+                ORDER BY created_at DESC
+                LIMIT $2 OFFSET $3
+                """,
+                user_id,
+                limit,
+                offset,
+            )
+        else:
+            rows = await conn.fetch(
+                """
+                SELECT id, user_id, type, title, message, action_url, read, created_at
+                FROM notifications
+                WHERE user_id = $1
+                ORDER BY created_at DESC
+                LIMIT $2 OFFSET $3
+                """,
+                user_id,
+                limit,
+                offset,
+            )
+
+    return [_row_to_notification(dict(row)) for row in rows]
+
+
+async def get_total_count(user_id: str, unread_only: bool = False) -> int:
+    """Get total notification count for a user."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        if unread_only:
+            row = await conn.fetchval(
+                "SELECT COUNT(*) FROM notifications WHERE user_id = $1 AND read = FALSE",
+                user_id,
+            )
+        else:
+            row = await conn.fetchval(
+                "SELECT COUNT(*) FROM notifications WHERE user_id = $1",
+                user_id,
+            )
+    return row or 0
+
+
+async def mark_read(notification_id: uuid.UUID) -> bool:
+    """Mark a single notification as read. Returns True if the notification existed."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            "UPDATE notifications SET read = TRUE WHERE id = $1",
+            notification_id,
+        )
+    return result == "UPDATE 1"
+
+
+async def mark_all_read(user_id: str) -> int:
+    """Mark all unread notifications for a user as read. Returns count of updated rows."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            "UPDATE notifications SET read = TRUE WHERE user_id = $1 AND read = FALSE",
+            user_id,
+        )
+    # result looks like "UPDATE N"
+    return int(result.split()[-1])
+
+
+async def get_unread_count(user_id: str) -> int:
+    """Get the number of unread notifications for a user."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        count = await conn.fetchval(
+            "SELECT COUNT(*) FROM notifications WHERE user_id = $1 AND read = FALSE",
+            user_id,
+        )
+    return count or 0
+
+
+async def delete_old(days: int) -> int:
+    """Delete notifications older than the specified number of days. Returns count deleted."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            """
+            DELETE FROM notifications
+            WHERE created_at < NOW() - MAKE_INTERVAL(days => $1)
+            """,
+            days,
+        )
+    return int(result.split()[-1])
+
+
+async def get_preferences(user_id: str) -> NotificationPreferences:
+    """Get notification preferences for a user. Returns defaults if no row exists."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            SELECT user_id, email_enabled, in_app_enabled, digest_frequency
+            FROM notification_preferences
+            WHERE user_id = $1
+            """,
+            user_id,
+        )
+
+    if row is None:
+        return NotificationPreferences(user_id=user_id)
+
+    return NotificationPreferences(
+        user_id=row["user_id"],
+        email_enabled=row["email_enabled"],
+        in_app_enabled=row["in_app_enabled"],
+        digest_frequency=DigestFrequency(row["digest_frequency"]),
+    )
+
+
+async def set_preferences(
+    user_id: str, prefs: NotificationPreferences
+) -> NotificationPreferences:
+    """Upsert notification preferences for a user."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        await conn.execute(
+            """
+            INSERT INTO notification_preferences (user_id, email_enabled, in_app_enabled, digest_frequency)
+            VALUES ($1, $2, $3, $4)
+            ON CONFLICT (user_id)
+            DO UPDATE SET
+                email_enabled = EXCLUDED.email_enabled,
+                in_app_enabled = EXCLUDED.in_app_enabled,
+                digest_frequency = EXCLUDED.digest_frequency
+            """,
+            user_id,
+            prefs.email_enabled,
+            prefs.in_app_enabled,
+            prefs.digest_frequency.value,
+        )
+
+    return prefs

msaas_notifications-0.1.0/tests/conftest.py

@@ -0,0 +1,60 @@
+"""Shared fixtures for notification module tests."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+import notifications.config as cfg
+from notifications.config import NotificationConfig
+
+
+@pytest.fixture(autouse=True)
+def _reset_config():
+    """Reset the global config and pool before each test."""
+    cfg._config = None
+    cfg._pool = None
+    yield
+    cfg._config = None
+    cfg._pool = None
+
+
+@pytest.fixture()
+def notification_config() -> NotificationConfig:
+    """Return a standard test configuration."""
+    return NotificationConfig(
+        database_url="postgresql://test:test@localhost:5432/test_notifications",
+        max_per_page=20,
+        retention_days=30,
+    )
+
+
+@pytest.fixture()
+def mock_pool() -> MagicMock:
+    """Return a mock asyncpg pool with an acquire context manager."""
+    pool = MagicMock()
+    conn = AsyncMock()
+
+    # Make pool.acquire() return an async context manager yielding conn
+    acquire_cm = AsyncMock()
+    acquire_cm.__aenter__ = AsyncMock(return_value=conn)
+    acquire_cm.__aexit__ = AsyncMock(return_value=False)
+    pool.acquire.return_value = acquire_cm
+
+    return pool
+
+
+@pytest.fixture()
+def mock_conn(mock_pool: MagicMock) -> AsyncMock:
+    """Return the mock connection from the mock pool."""
+    return mock_pool.acquire.return_value.__aenter__.return_value
+
+
+@pytest.fixture()
+def initialized_config(notification_config: NotificationConfig, mock_pool: MagicMock) -> NotificationConfig:
+    """Return a config that has been initialized with a mock pool."""
+    cfg._config = notification_config
+    cfg._pool = mock_pool
+    return notification_config

msaas_notifications-0.1.0/tests/test_service.py

@@ -0,0 +1,236 @@
+"""Tests for the notification service layer."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+from uuid import uuid4
+
+import pytest
+
+import notifications.config as cfg
+from notifications.config import NotificationConfig
+from notifications.models import (
+    CreateNotification,
+    Notification,
+    NotificationType,
+)
+from notifications.service import (
+    get_notifications,
+    mark_all_read,
+    mark_read,
+    send_bulk,
+    send_notification,
+)
+
+
+@pytest.fixture()
+def sample_notification() -> Notification:
+    """Return a sample notification for test assertions."""
+    return Notification(
+        id=uuid4(),
+        user_id="user-123",
+        type=NotificationType.INFO,
+        title="Test",
+        message="Hello world",
+        action_url=None,
+        read=False,
+        created_at=datetime.now(timezone.utc),
+    )
+
+
+class TestSendNotification:
+    """Tests for service.send_notification()."""
+
+    @patch("notifications.service.insert", new_callable=AsyncMock)
+    async def test_sends_single_notification(
+        self,
+        mock_insert: AsyncMock,
+        initialized_config: NotificationConfig,
+        sample_notification: Notification,
+    ):
+        mock_insert.return_value = sample_notification
+
+        result = await send_notification(
+            user_id="user-123",
+            type="info",
+            title="Test",
+            message="Hello world",
+        )
+
+        assert result.user_id == "user-123"
+        assert result.title == "Test"
+        mock_insert.assert_called_once()
+
+        payload = mock_insert.call_args[0][0]
+        assert isinstance(payload, CreateNotification)
+        assert payload.user_id == "user-123"
+        assert payload.type == NotificationType.INFO
+
+    @patch("notifications.service.insert", new_callable=AsyncMock)
+    async def test_accepts_enum_type(
+        self,
+        mock_insert: AsyncMock,
+        initialized_config: NotificationConfig,
+        sample_notification: Notification,
+    ):
+        mock_insert.return_value = sample_notification
+
+        await send_notification(
+            user_id="user-123",
+            type=NotificationType.ERROR,
+            title="Error",
+            message="Something broke",
+        )
+
+        payload = mock_insert.call_args[0][0]
+        assert payload.type == NotificationType.ERROR
+
+    @patch("notifications.service.insert", new_callable=AsyncMock)
+    async def test_passes_action_url(
+        self,
+        mock_insert: AsyncMock,
+        initialized_config: NotificationConfig,
+        sample_notification: Notification,
+    ):
+        mock_insert.return_value = sample_notification
+
+        await send_notification(
+            user_id="user-123",
+            type="success",
+            title="Done",
+            message="All good",
+            action_url="https://example.com/action",
+        )
+
+        payload = mock_insert.call_args[0][0]
+        assert payload.action_url == "https://example.com/action"
+
+
+class TestSendBulk:
+    """Tests for service.send_bulk()."""
+
+    @patch("notifications.service.insert_bulk", new_callable=AsyncMock)
+    async def test_sends_to_multiple_users(
+        self,
+        mock_insert_bulk: AsyncMock,
+        initialized_config: NotificationConfig,
+    ):
+        now = datetime.now(timezone.utc)
+        mock_insert_bulk.return_value = [
+            Notification(
+                id=uuid4(),
+                user_id=uid,
+                type=NotificationType.WARNING,
+                title="Maintenance",
+                message="Downtime at midnight",
+                read=False,
+                created_at=now,
+            )
+            for uid in ["user-1", "user-2", "user-3"]
+        ]
+
+        results = await send_bulk(
+            user_ids=["user-1", "user-2", "user-3"],
+            type="warning",
+            title="Maintenance",
+            message="Downtime at midnight",
+        )
+
+        assert len(results) == 3
+        mock_insert_bulk.assert_called_once()
+        payloads = mock_insert_bulk.call_args[0][0]
+        assert len(payloads) == 3
+        assert {p.user_id for p in payloads} == {"user-1", "user-2", "user-3"}
+
+
+class TestGetNotifications:
+    """Tests for service.get_notifications()."""
+
+    @patch("notifications.service.get_unread_count", new_callable=AsyncMock)
+    @patch("notifications.service.get_total_count", new_callable=AsyncMock)
+    @patch("notifications.service.get_by_user", new_callable=AsyncMock)
+    async def test_returns_paginated_result(
+        self,
+        mock_get_by_user: AsyncMock,
+        mock_get_total: AsyncMock,
+        mock_get_unread: AsyncMock,
+        initialized_config: NotificationConfig,
+        sample_notification: Notification,
+    ):
+        mock_get_by_user.return_value = [sample_notification]
+        mock_get_total.return_value = 1
+        mock_get_unread.return_value = 1
+
+        result = await get_notifications("user-123", page=1)
+
+        assert result["items"] == [sample_notification]
+        assert result["total"] == 1
+        assert result["unread_count"] == 1
+        assert result["page"] == 1
+        assert result["per_page"] == 20  # from test config
+
+    @patch("notifications.service.get_unread_count", new_callable=AsyncMock)
+    @patch("notifications.service.get_total_count", new_callable=AsyncMock)
+    @patch("notifications.service.get_by_user", new_callable=AsyncMock)
+    async def test_page_offset_calculation(
+        self,
+        mock_get_by_user: AsyncMock,
+        mock_get_total: AsyncMock,
+        mock_get_unread: AsyncMock,
+        initialized_config: NotificationConfig,
+    ):
+        mock_get_by_user.return_value = []
+        mock_get_total.return_value = 50
+        mock_get_unread.return_value = 10
+
+        await get_notifications("user-123", page=3)
+
+        # Page 3 with per_page=20 means offset=40
+        call_args = mock_get_by_user.call_args
+        assert call_args.kwargs.get("offset", call_args[1].get("offset")) == 40
+
+
+class TestMarkRead:
+    """Tests for service.mark_read() and service.mark_all_read()."""
+
+    @patch("notifications.service.store_mark_read", new_callable=AsyncMock)
+    async def test_mark_read_with_string_id(
+        self,
+        mock_store_mark_read: AsyncMock,
+        initialized_config: NotificationConfig,
+    ):
+        mock_store_mark_read.return_value = True
+        nid = uuid4()
+
+        result = await mark_read(str(nid))
+
+        assert result is True
+        mock_store_mark_read.assert_called_once_with(nid)
+
+    @patch("notifications.service.store_mark_read", new_callable=AsyncMock)
+    async def test_mark_read_with_uuid(
+        self,
+        mock_store_mark_read: AsyncMock,
+        initialized_config: NotificationConfig,
+    ):
+        mock_store_mark_read.return_value = True
+        nid = uuid4()
+
+        result = await mark_read(nid)
+
+        assert result is True
+        mock_store_mark_read.assert_called_once_with(nid)
+
+    @patch("notifications.service.store_mark_all_read", new_callable=AsyncMock)
+    async def test_mark_all_read(
+        self,
+        mock_store_mark_all: AsyncMock,
+        initialized_config: NotificationConfig,
+    ):
+        mock_store_mark_all.return_value = 7
+
+        count = await mark_all_read("user-123")
+
+        assert count == 7
+        mock_store_mark_all.assert_called_once_with("user-123")

msaas_notifications-0.1.0/tests/test_store.py

@@ -0,0 +1,233 @@
+"""Tests for the notification store layer."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+import notifications.config as cfg
+from notifications.config import NotificationConfig
+from notifications.models import CreateNotification, NotificationType
+from notifications.store import (
+    delete_old,
+    get_by_user,
+    get_preferences,
+    get_unread_count,
+    insert,
+    mark_all_read,
+    mark_read,
+    set_preferences,
+)
+
+
+class TestInsert:
+    """Tests for store.insert()."""
+
+    async def test_insert_creates_notification(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.execute = AsyncMock()
+
+        payload = CreateNotification(
+            user_id="user-123",
+            type=NotificationType.INFO,
+            title="Test notification",
+            message="This is a test",
+            action_url="https://example.com",
+        )
+
+        result = await insert(payload)
+
+        assert result.user_id == "user-123"
+        assert result.type == NotificationType.INFO
+        assert result.title == "Test notification"
+        assert result.message == "This is a test"
+        assert result.action_url == "https://example.com"
+        assert result.read is False
+        assert result.id is not None
+        mock_conn.execute.assert_called_once()
+
+    async def test_insert_without_action_url(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.execute = AsyncMock()
+
+        payload = CreateNotification(
+            user_id="user-456",
+            type=NotificationType.ERROR,
+            title="Error occurred",
+            message="Something went wrong",
+        )
+
+        result = await insert(payload)
+
+        assert result.action_url is None
+        assert result.type == NotificationType.ERROR
+
+
+class TestGetByUser:
+    """Tests for store.get_by_user()."""
+
+    async def test_get_by_user_returns_notifications(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        now = datetime.now(timezone.utc)
+        nid = uuid4()
+        mock_conn.fetch = AsyncMock(
+            return_value=[
+                {
+                    "id": nid,
+                    "user_id": "user-123",
+                    "type": "info",
+                    "title": "Test",
+                    "message": "Hello",
+                    "action_url": None,
+                    "read": False,
+                    "created_at": now,
+                }
+            ]
+        )
+
+        results = await get_by_user("user-123", limit=10, offset=0)
+
+        assert len(results) == 1
+        assert results[0].id == nid
+        assert results[0].user_id == "user-123"
+        mock_conn.fetch.assert_called_once()
+
+    async def test_get_by_user_unread_only(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.fetch = AsyncMock(return_value=[])
+
+        results = await get_by_user("user-123", limit=10, offset=0, unread_only=True)
+
+        assert results == []
+        # Verify the query included the unread filter
+        call_args = mock_conn.fetch.call_args
+        query = call_args[0][0]
+        assert "read = FALSE" in query
+
+
+class TestMarkRead:
+    """Tests for store.mark_read() and store.mark_all_read()."""
+
+    async def test_mark_read_returns_true_on_success(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.execute = AsyncMock(return_value="UPDATE 1")
+        nid = uuid4()
+
+        result = await mark_read(nid)
+
+        assert result is True
+
+    async def test_mark_read_returns_false_on_miss(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.execute = AsyncMock(return_value="UPDATE 0")
+        nid = uuid4()
+
+        result = await mark_read(nid)
+
+        assert result is False
+
+    async def test_mark_all_read_returns_count(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.execute = AsyncMock(return_value="UPDATE 5")
+
+        count = await mark_all_read("user-123")
+
+        assert count == 5
+
+
+class TestUnreadCount:
+    """Tests for store.get_unread_count()."""
+
+    async def test_returns_count(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.fetchval = AsyncMock(return_value=7)
+
+        count = await get_unread_count("user-123")
+
+        assert count == 7
+
+    async def test_returns_zero_on_none(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.fetchval = AsyncMock(return_value=None)
+
+        count = await get_unread_count("user-123")
+
+        assert count == 0
+
+
+class TestDeleteOld:
+    """Tests for store.delete_old()."""
+
+    async def test_deletes_old_notifications(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.execute = AsyncMock(return_value="DELETE 42")
+
+        count = await delete_old(90)
+
+        assert count == 42
+
+
+class TestPreferences:
+    """Tests for store.get_preferences() and store.set_preferences()."""
+
+    async def test_get_preferences_returns_defaults_when_missing(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.fetchrow = AsyncMock(return_value=None)
+
+        prefs = await get_preferences("user-999")
+
+        assert prefs.user_id == "user-999"
+        assert prefs.email_enabled is True
+        assert prefs.in_app_enabled is True
+        assert prefs.digest_frequency.value == "none"
+
+    async def test_get_preferences_returns_stored_values(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        mock_conn.fetchrow = AsyncMock(
+            return_value={
+                "user_id": "user-123",
+                "email_enabled": False,
+                "in_app_enabled": True,
+                "digest_frequency": "daily",
+            }
+        )
+
+        prefs = await get_preferences("user-123")
+
+        assert prefs.email_enabled is False
+        assert prefs.digest_frequency.value == "daily"
+
+    async def test_set_preferences_upserts(
+        self, initialized_config: NotificationConfig, mock_conn: AsyncMock
+    ):
+        from notifications.models import DigestFrequency, NotificationPreferences
+
+        mock_conn.execute = AsyncMock()
+
+        prefs = NotificationPreferences(
+            user_id="user-123",
+            email_enabled=False,
+            in_app_enabled=True,
+            digest_frequency=DigestFrequency.WEEKLY,
+        )
+
+        result = await set_preferences("user-123", prefs)
+
+        assert result.email_enabled is False
+        assert result.digest_frequency == DigestFrequency.WEEKLY
+        mock_conn.execute.assert_called_once()