fastapi-plugin-notification 0.1.0__py3-none-any.whl

fastapi_plugin_notification/__init__.py

@@ -0,0 +1,29 @@
+"""FastAPI Notification Plugin
+
+A notification plugin for FastAPI that integrates with FastAPI SDK and Postmark provider
+to send notifications via email and store them in a database.
+"""
+
+from fastapi_plugin_notification.app import create_notification_router
+from fastapi_plugin_notification.client import NotificationClient
+from fastapi_plugin_notification.controller import NotificationController
+from fastapi_plugin_notification.models import NotificationModel
+from fastapi_plugin_notification.schemas import (
+    NotificationCreate,
+    NotificationResponse,
+    NotificationResponsePaginated,
+    NotificationUpdate,
+)
+
+__all__ = [
+    "NotificationClient",
+    "NotificationController",
+    "NotificationModel",
+    "NotificationCreate",
+    "NotificationUpdate",
+    "NotificationResponse",
+    "NotificationResponsePaginated",
+    "create_notification_router",
+]
+
+__version__ = "0.1.0"

fastapi_plugin_notification/app.py

@@ -0,0 +1,162 @@
+"""FastAPI app setup for notification plugin."""
+
+from typing import Callable, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi_sdk.security.permissions import require_permission
+from odmantic import AIOEngine
+
+from fastapi_plugin_notification.controller import NotificationController
+from fastapi_plugin_notification.schemas import (
+    NotificationResponse,
+    NotificationResponsePaginated,
+)
+
+
+def create_notification_router(
+    *,
+    prefix: str = "/notifications",
+    tags: Optional[list[str]] = None,
+    get_db: Callable,
+) -> APIRouter:
+    """Create a FastAPI router for user-specific notification endpoints.
+
+    Args:
+        prefix: URL prefix for all routes (default: "/notifications")
+        tags: List of tags for API documentation (default: ["notifications"])
+        get_db: Database dependency function that returns AIOEngine
+
+    Returns:
+        Configured APIRouter instance with user-specific routes only
+    """
+    if tags is None:
+        tags = ["notifications"]
+
+    router = APIRouter(prefix=prefix, tags=tags)
+
+    @router.get("/me", response_model=NotificationResponsePaginated)
+    @require_permission("notification:read")
+    async def get_my_notifications(
+        request: Request,
+        page: int = Query(default=1, ge=1, description="Page number (1-based)"),
+        seen: Optional[bool] = Query(
+            default=None, description="Filter by seen status (true/false)"
+        ),
+        db: AIOEngine = Depends(get_db),
+    ):
+        """Get notifications for the current user."""
+        user_id = request.state.claims.get("sub")
+        if not user_id:
+            raise HTTPException(status_code=400, detail="user_id not found in claims")
+
+        controller = NotificationController(db)
+        query = [{"user_id": user_id}]
+        if seen is not None:
+            query.append({"seen": seen})
+
+        result = await controller.list(
+            page=page,
+            query=query,
+            claims=None,  # No ownership rule at controller level, enforced via query
+        )
+        return result
+
+    @router.get("/me/{notification_id}", response_model=NotificationResponse)
+    @require_permission("notification:read")
+    async def get_my_notification(
+        request: Request,
+        notification_id: str,
+        db: AIOEngine = Depends(get_db),
+    ):
+        """Get a specific notification by ID for the current user and automatically mark it as seen."""
+        user_id = request.state.claims.get("sub")
+        if not user_id:
+            raise HTTPException(status_code=400, detail="user_id not found in claims")
+
+        controller = NotificationController(db)
+
+        # Get the notification
+        notification = await controller.get(
+            uuid=notification_id,
+            claims=None,  # No ownership rule at controller level
+        )
+
+        if not notification:
+            raise HTTPException(status_code=404, detail="Notification not found")
+
+        # Enforce ownership at route level
+        if notification.user_id != user_id:
+            raise HTTPException(
+                status_code=403,
+                detail="Access denied: notification does not belong to you",
+            )
+
+        # Automatically mark as seen if not already seen
+        if not notification.seen:
+            notification = await controller.update(
+                uuid=notification_id,
+                data={"seen": True},
+                claims=None,  # No ownership rule at controller level
+            )
+
+        return NotificationResponse(**notification.model_dump())
+
+    @router.delete("/me/{notification_id}")
+    @require_permission("notification:delete")
+    async def delete_my_notification(
+        request: Request,
+        notification_id: str,
+        db: AIOEngine = Depends(get_db),
+    ):
+        """Delete a notification for the current user."""
+        user_id = request.state.claims.get("sub")
+        if not user_id:
+            raise HTTPException(status_code=400, detail="user_id not found in claims")
+
+        controller = NotificationController(db)
+
+        # Get the notification first to check ownership
+        notification = await controller.get(
+            uuid=notification_id,
+            claims=None,  # No ownership rule at controller level
+        )
+
+        if not notification:
+            raise HTTPException(status_code=404, detail="Notification not found")
+
+        # Enforce ownership at route level
+        if notification.user_id != user_id:
+            raise HTTPException(
+                status_code=403,
+                detail="Access denied: notification does not belong to you",
+            )
+
+        # Delete the notification
+        deleted = await controller.delete(
+            uuid=notification_id,
+            claims=None,  # No ownership rule at controller level
+        )
+
+        if not deleted:
+            raise HTTPException(status_code=404, detail="Notification not found")
+        return {"detail": "Notification deleted"}
+
+    @router.get("/count/unseen", response_model=dict)
+    @require_permission("notification:read")
+    async def get_unseen_count(
+        request: Request,
+        db: AIOEngine = Depends(get_db),
+    ):
+        """Get count of unseen notifications for the current user."""
+        user_id = request.state.claims.get("sub")
+        if not user_id:
+            raise HTTPException(status_code=400, detail="user_id not found in claims")
+
+        controller = NotificationController(db)
+        count = await controller.count(
+            query=[{"user_id": user_id}, {"seen": False}],
+            claims=None,  # No ownership rule at controller level, enforced via query
+        )
+        return {"count": count}
+
+    return router

fastapi_plugin_notification/client.py

@@ -0,0 +1,206 @@
+"""Notification client for sending notifications."""
+
+import logging
+from typing import Any, Dict, Optional
+
+from fastapi_provider_postmark import PostmarkProvider
+from odmantic import AIOEngine
+
+from fastapi_plugin_notification.controller import NotificationController
+from fastapi_plugin_notification.models import NotificationModel
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationClient:
+    """Client for creating and sending notifications."""
+
+    def __init__(
+        self,
+        postmark_provider: PostmarkProvider,
+        default_template_id: Optional[int] = None,
+    ):
+        """Initialize the notification client.
+
+        Args:
+            postmark_provider: PostmarkProvider instance for sending emails
+            default_template_id: Default Postmark template ID to use for emails
+        """
+        self.postmark_provider = postmark_provider
+        self.default_template_id = default_template_id
+
+    async def send_notification(
+        self,
+        db_engine: AIOEngine,
+        name: str,
+        user_id: str,
+        user_email: str,
+        claims: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+        link: Optional[str] = None,
+        link_name: Optional[str] = None,
+        template_id: Optional[int] = None,
+        template_variables: Optional[Dict[str, Any]] = None,
+        send_email: bool = True,
+    ) -> NotificationModel:
+        """Create a notification and optionally send an email.
+
+        Args:
+            db_engine: MongoDB engine instance from odmantic
+            name: Name/type of the notification
+            user_id: ID of the user who should receive the notification
+            user_email: Email address of the user
+            claims: User claims for ownership verification (required)
+            metadata: Additional metadata about the notification
+            link: Call to action link for the notification
+            link_name: Text to display on the call to action button/link in the email
+            template_id: Postmark template ID to use (uses default if not provided)
+            template_variables: Variables to pass to the email template
+            send_email: Whether to send an email (default: True)
+
+        Returns:
+            The created notification model instance
+        """
+        controller = NotificationController(db_engine)
+
+        # Prepare notification data
+        notification_data = {
+            "name": name,
+            "user_id": user_id,
+            "user_email": user_email,
+            "metadata": metadata or {},
+            "link": link,
+            "link_name": link_name,
+            "seen": False,
+        }
+
+        # Create notification in database
+        notification = await controller.create(notification_data, claims=claims)
+
+        # Send email if requested
+        if send_email:
+            try:
+                # Use provided template_id or default
+                email_template_id = template_id or self.default_template_id
+
+                if not email_template_id:
+                    logger.warning(
+                        "No template_id provided and no default_template_id set. "
+                        "Skipping email send for notification %s",
+                        notification.uuid,
+                    )
+                else:
+                    # Prepare template variables
+                    email_variables = {
+                        "notification_name": name,
+                        "user_email": user_email,
+                        "link": link or "",
+                        "link_name": link_name or "",
+                        **(template_variables or {}),
+                        **(metadata or {}),
+                    }
+
+                    # Send email via Postmark
+                    await self.postmark_provider.send_email(
+                        to=user_email,
+                        template_id=email_template_id,
+                        template_variables=email_variables,
+                    )
+
+                    logger.info(
+                        "Notification email sent successfully for notification %s to %s",
+                        notification.uuid,
+                        user_email,
+                    )
+            except Exception as e:
+                # Log the error (suppress any warnings from exception handling)
+                try:
+                    logger.error(
+                        "Failed to send notification email for notification %s: %s",
+                        notification.uuid,
+                        str(e),
+                    )
+                except Exception:
+                    # If logging fails, just pass - don't let logging errors break notification creation
+                    pass
+                # Don't fail the notification creation if email fails
+                # The notification is still stored in the database
+
+        return notification
+
+    async def get_user_notifications(
+        self,
+        db_engine: AIOEngine,
+        user_id: str,
+        page: int = 1,
+        seen: Optional[bool] = None,
+        claims: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Get notifications for a specific user.
+
+        Args:
+            db_engine: MongoDB engine instance from odmantic
+            user_id: ID of the user
+            page: Page number (1-based)
+            seen: Filter by seen status (None for all, True for seen, False for unseen)
+            claims: Optional user claims for ownership verification
+
+        Returns:
+            Paginated list of notifications
+        """
+        controller = NotificationController(db_engine)
+        query = [{"user_id": user_id}]
+        if seen is not None:
+            query.append({"seen": seen})
+
+        return await controller.list(
+            page=page,
+            query=query,
+            claims=claims,
+        )
+
+    async def get_unseen_count(
+        self,
+        db_engine: AIOEngine,
+        user_id: str,
+        claims: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """Get count of unseen notifications for a user.
+
+        Args:
+            db_engine: MongoDB engine instance from odmantic
+            user_id: ID of the user
+            claims: Optional user claims for ownership verification
+
+        Returns:
+            Count of unseen notifications
+        """
+        controller = NotificationController(db_engine)
+        return await controller.count(
+            query=[{"user_id": user_id}, {"seen": False}],
+            claims=claims,
+        )
+
+    async def mark_as_seen(
+        self,
+        db_engine: AIOEngine,
+        notification_uuid: str,
+        claims: Optional[Dict[str, Any]] = None,
+    ) -> Optional[NotificationModel]:
+        """Mark a notification as seen.
+
+        Args:
+            db_engine: MongoDB engine instance from odmantic
+            notification_uuid: UUID of the notification
+            claims: Optional user claims for ownership verification
+
+        Returns:
+            Updated notification model instance or None if not found
+        """
+        controller = NotificationController(db_engine)
+        result = await controller.update(
+            uuid=notification_uuid,
+            data={"seen": True},
+            claims=claims,
+        )
+        return result

fastapi_plugin_notification/controller.py

@@ -0,0 +1,19 @@
+"""Notification controller for CRUD operations."""
+
+from fastapi_sdk.controllers import ModelController
+
+from fastapi_plugin_notification.models import NotificationModel
+from fastapi_plugin_notification.schemas import (
+    NotificationCreate,
+    NotificationResponse,
+    NotificationUpdate,
+)
+
+
+class NotificationController(ModelController):
+    """Controller for notification operations."""
+
+    model = NotificationModel
+    schema_create = NotificationCreate
+    schema_update = NotificationUpdate
+    schema_response = NotificationResponse

fastapi_plugin_notification/models.py

@@ -0,0 +1,46 @@
+"""Notification model for database storage."""
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from fastapi_sdk.utils.model import ShortUUID, ShortUUIDType
+from odmantic import Field, Index, Model
+
+
+class NotificationModel(Model):
+    """Notification model for storing notifications in the database."""
+
+    created_at: datetime
+    updated_at: datetime
+    uuid: ShortUUIDType = Field(default_factory=lambda: ShortUUID.generate("not"))
+    name: str = Field(description="Name/type of the notification")
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata about the notification"
+    )
+    user_id: str = Field(
+        description="ID of the user who should receive the notification"
+    )
+    user_email: str = Field(
+        description="Email address of the user to send notification to"
+    )
+    link: Optional[str] = Field(
+        default=None, description="Call to action link for the notification"
+    )
+    link_name: Optional[str] = Field(
+        default=None,
+        description="Text to display on the call to action button/link in the email",
+    )
+    seen: bool = Field(
+        default=False, description="Whether the notification has been seen/acknowledged"
+    )
+    deleted: bool = False
+
+    model_config = {
+        "collection": "notification",
+        "indexes": lambda: [
+            Index(NotificationModel.uuid, unique=True),
+            Index(NotificationModel.user_id),
+            Index(NotificationModel.seen),
+            Index(NotificationModel.created_at),
+        ],
+    }

fastapi_plugin_notification/schemas.py

@@ -0,0 +1,91 @@
+"""Schemas for notification API requests and responses."""
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from fastapi_sdk.utils.model import ShortUUIDType
+from fastapi_sdk.utils.schema import BaseResponsePaginated, datetime_now_sec
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class NotificationBase(BaseModel):
+    """Base schema for common notification attributes."""
+
+    name: str = Field(
+        min_length=1, max_length=200, description="Name/type of the notification"
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata about the notification"
+    )
+    user_id: str = Field(
+        description="ID of the user who should receive the notification"
+    )
+    user_email: str = Field(
+        description="Email address of the user to send notification to"
+    )
+    link: Optional[str] = Field(
+        default=None, description="Call to action link for the notification"
+    )
+    link_name: Optional[str] = Field(
+        default=None,
+        description="Text to display on the call to action button/link in the email",
+    )
+
+
+class NotificationCreate(NotificationBase):
+    """Schema for creating a notification."""
+
+    created_at: datetime = Field(default_factory=datetime_now_sec)
+    updated_at: datetime = Field(default_factory=datetime_now_sec)
+    seen: bool = Field(
+        default=False, description="Whether the notification has been seen"
+    )
+
+
+class NotificationUpdate(BaseModel):
+    """Schema for updating a notification."""
+
+    name: Optional[str] = Field(
+        default=None,
+        min_length=1,
+        max_length=200,
+        description="Name/type of the notification",
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None, description="Additional metadata about the notification"
+    )
+    user_id: Optional[str] = Field(
+        default=None, description="ID of the user who should receive the notification"
+    )
+    user_email: Optional[str] = Field(
+        default=None, description="Email address of the user to send notification to"
+    )
+    link: Optional[str] = Field(
+        default=None, description="Call to action link for the notification"
+    )
+    link_name: Optional[str] = Field(
+        default=None,
+        description="Text to display on the call to action button/link in the email",
+    )
+    seen: Optional[bool] = Field(
+        default=None, description="Whether the notification has been seen/acknowledged"
+    )
+    updated_at: datetime = Field(default_factory=datetime_now_sec)
+
+
+class NotificationResponse(NotificationBase):
+    """Schema for API responses."""
+
+    uuid: ShortUUIDType
+    created_at: datetime
+    updated_at: datetime
+    seen: bool
+    deleted: bool
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class NotificationResponsePaginated(BaseResponsePaginated):
+    """Schema for paginated notification API responses."""
+
+    items: list[NotificationResponse]

fastapi_plugin_notification-0.1.0.dist-info/METADATA

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: fastapi-plugin-notification
+Version: 0.1.0
+Summary: Notification plugin for FastAPI projects using FastAPI SDK and Postmark provider.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi-sdk>=0.9.7
+Requires-Dist: fastapi-provider-postmark>=0.1.1
+Requires-Dist: fastapi>=0.115.11
+Requires-Dist: odmantic>=1.0.2
+Requires-Dist: pydantic>=2.10.6
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25.3; extra == "dev"
+Requires-Dist: motor>=3.6.0; extra == "dev"
+Dynamic: license-file
+
+# FastAPI Plugin Notification
+
+A notification plugin for FastAPI that integrates with FastAPI SDK and Postmark provider to send notifications via email and store them in a database.
+
+## Features
+
+- 📧 **Email Notifications**: Send notifications via Postmark email provider
+- 💾 **Database Storage**: Store notifications in MongoDB using ODMantic
+- 🔐 **User Ownership**: Automatic ownership filtering based on user claims
+- 📊 **Notification Management**: 
+  - Get all notifications for a user
+  - Mark notifications as seen/acknowledged
+  - Get unseen notification count
+- 🚀 **FastAPI Integration**: Full CRUD API endpoints with authentication
+- 📦 **PyPI Package**: Easy to install and use in any FastAPI project
+
+## Installation
+
+Using UV:
+
+```bash
+uv add fastapi-plugin-notification
+```
+
+Or using pip:
+
+```bash
+pip install fastapi-plugin-notification
+```
+
+## Quick Start
+
+### 1. Initialize the Notification Client
+
+```python
+from fastapi import FastAPI, Depends
+from odmantic import AIOEngine
+from fastapi_provider_postmark import PostmarkProvider
+from fastapi_plugin_notification import NotificationClient
+
+app = FastAPI()
+
+# Initialize Postmark provider
+postmark = PostmarkProvider(
+    api_key="your-postmark-api-key",
+    from_email="noreply@example.com",
+    from_name="My App",
+)
+
+# Initialize notification client (no DB engine needed)
+notification_client = NotificationClient(
+    postmark_provider=postmark,
+    default_template_id=123456,  # Your Postmark template ID
+)
+
+# Dependency for notification client
+def get_notification_client() -> NotificationClient:
+    return notification_client
+
+# Dependency for database engine
+def get_db() -> AIOEngine:
+    return AIOEngine(database="your_database")
+```
+
+### 2. Add Notification Routes to Your App
+
+```python
+from fastapi_plugin_notification.app import create_notification_router
+
+# Add notification routes
+notification_router = create_notification_router(
+    prefix="/notifications",
+    get_db=lambda: engine,
+)
+
+app.include_router(notification_router)
+```
+
+### 3. Send Notifications
+
+```python
+@app.post("/send-welcome")
+async def send_welcome_notification(
+    user_id: str,
+    user_email: str,
+    notification_client: NotificationClient = Depends(get_notification_client),
+    db: AIOEngine = Depends(get_db),
+):
+    """Send a welcome notification to a user."""
+    notification = await notification_client.send_notification(
+        db_engine=db,
+        name="welcome",
+        user_id=user_id,
+        user_email=user_email,
+        claims=request.state.claims,  # Required: user claims for ownership verification
+        metadata={
+            "welcome_message": "Welcome to our platform!",
+        },
+        link="https://example.com/dashboard",
+        link_name="Go to Dashboard",
+        template_variables={
+            "user_name": "John Doe",
+            "action_url": "https://example.com/dashboard",
+        },
+    )
+    return {"notification_id": notification.uuid, "message": "Notification sent"}
+```
+
+### 4. Get User Notifications
+
+The plugin automatically provides these user-specific endpoints:
+
+- `GET /notifications/me` - Get all notifications for the current user
+- `GET /notifications/me?seen=false` - Get only unseen notifications
+- `GET /notifications/me/{notification_id}` - Get a specific notification (automatically marks as seen)
+- `DELETE /notifications/me/{notification_id}` - Delete a notification
+- `GET /notifications/count/unseen` - Get count of unseen notifications
+
+## Usage Examples
+
+### Sending a Notification with Email
+
+```python
+# In a FastAPI route handler
+@app.post("/send-password-reset")
+async def send_password_reset(
+    user_id: str,
+    user_email: str,
+    notification_client: NotificationClient = Depends(get_notification_client),
+    db: AIOEngine = Depends(get_db),
+):
+    notification = await notification_client.send_notification(
+        db_engine=db,
+        name="password_reset",
+        user_id=user_id,
+        user_email=user_email,
+        claims=request.state.claims,  # Required: user claims for ownership verification
+        metadata={
+            "reset_token": "abc123",
+            "expires_in": 3600,
+        },
+        link="https://example.com/reset-password?token=abc123",
+        link_name="Reset Password",
+        template_variables={
+            "reset_link": "https://example.com/reset-password?token=abc123",
+            "expires_in_minutes": 60,
+        },
+    )
+    return {"notification_id": notification.uuid}
+```
+
+### Getting User Notifications
+
+```python
+# Get all notifications for a user
+notifications = await notification_client.get_user_notifications(
+    db_engine=db,
+    user_id="user_123",
+    page=1,
+)
+
+# Get only unseen notifications
+unseen_notifications = await notification_client.get_user_notifications(
+    db_engine=db,
+    user_id="user_123",
+    page=1,
+    seen=False,
+)
+
+# Get unseen count
+unseen_count = await notification_client.get_unseen_count(
+    db_engine=db,
+    user_id="user_123",
+)
+```
+
+### Marking Notifications as Seen
+
+```python
+# Mark a specific notification as seen
+notification = await notification_client.mark_as_seen(
+    db_engine=db,
+    notification_uuid="not_abc123",
+)
+```
+
+### Creating Notifications Without Email
+
+```python
+# Create notification without sending email
+notification = await notification_client.send_notification(
+    db_engine=db,
+    name="system_alert",
+    user_id="user_123",
+    user_email="user@example.com",
+    claims=request.state.claims,  # Required: user claims for ownership verification
+    metadata={"alert_type": "info"},
+    send_email=False,  # Don't send email
+)
+```
+
+## API Endpoints
+
+### Get My Notifications
+
+```http
+GET /notifications/me?page=1&seen=false
+```
+
+**Query Parameters:**
+- `page` (int): Page number (default: 1)
+- `seen` (bool, optional): Filter by seen status
+
+**Response:**
+```json
+{
+  "items": [
+    {
+      "uuid": "not_abc123",
+      "name": "welcome",
+      "user_id": "user_123",
+      "user_email": "user@example.com",
+      "metadata": {},
+      "link": "https://example.com/dashboard",
+      "seen": false,
+      "created_at": "2024-01-01T00:00:00Z",
+      "updated_at": "2024-01-01T00:00:00Z",
+      "deleted": false
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "pages": 1,
+  "size": 1
+}
+```
+
+### Get Unseen Count
+
+```http
+GET /notifications/count/unseen
+```
+
+**Response:**
+```json
+{
+  "count": 5
+}
+```
+
+### Get My Notification (Auto-marks as Seen)
+
+```http
+GET /notifications/me/{notification_id}
+```
+
+**Note:** This endpoint automatically marks the notification as `seen: true` when accessed. Only returns notifications belonging to the current user.
+
+**Response:**
+```json
+{
+  "uuid": "not_abc123",
+  "name": "welcome",
+  "user_id": "user_123",
+  "user_email": "user@example.com",
+  "metadata": {},
+  "link": "https://example.com/dashboard",
+  "link_name": "Go to Dashboard",
+  "seen": true,
+  "created_at": "2024-01-01T00:00:00Z",
+  "updated_at": "2024-01-01T00:00:00Z",
+  "deleted": false
+}
+```
+
+## Model Structure
+
+The `NotificationModel` includes:
+
+- `uuid`: Unique identifier (short UUID with "not" prefix)
+- `name`: Name/type of the notification
+- `metadata`: Additional metadata (dict)
+- `user_id`: ID of the user who should receive the notification
+- `user_email`: Email address of the user
+- `link`: Call to action link (optional)
+- `link_name`: Text to display on the call to action button/link in the email (optional)
+- `seen`: Whether the notification has been seen (default: False)
+- `created_at`: Creation timestamp
+- `updated_at`: Last update timestamp
+- `deleted`: Soft delete flag
+
+## Ownership and Permissions
+
+The plugin uses FastAPI SDK's ownership rules to ensure users can only access their own notifications. The ownership is based on the `user_id` claim in the JWT token.
+
+Required permissions:
+- `notification:create` - Create notifications
+- `notification:read` - Read notifications
+- `notification:update` - Update notifications
+- `notification:delete` - Delete notifications
+
+## Configuration
+
+### Custom Router Configuration
+
+```python
+from fastapi_plugin_notification.app import create_notification_router
+
+# Create router with custom prefix and tags
+notification_router = create_notification_router(
+    prefix="/notifications",
+    tags=["notifications", "alerts"],
+    get_db=lambda: engine,
+)
+```
+
+**Note:** All routes are user-specific and automatically filter by the current user's ID from JWT claims.
+
+### Custom Template Variables
+
+The notification client automatically includes:
+- `notification_name`: The name of the notification
+- `user_email`: The user's email
+- `link`: The notification link
+- `link_name`: The text for the call to action button/link
+- All `metadata` fields
+- All `template_variables` fields
+
+These are merged and passed to the Postmark template. You can use `link_name` in your email template to display custom button text for the call to action link.
+
+## Error Handling
+
+The plugin handles errors gracefully:
+- If email sending fails, the notification is still stored in the database
+- Errors are logged but don't interrupt the notification creation process
+- Database errors are propagated as HTTP exceptions
+
+## Development
+
+### Setup
+
+1. Clone the repository
+2. Install dependencies:
+```bash
+uv sync
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License - see LICENSE file for details
+

fastapi_plugin_notification-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fastapi_plugin_notification/__init__.py,sha256=Com8pdasPs9LAcqsmmSf0vax0DOjZYzrvXQ5xps_1xI,895
+fastapi_plugin_notification/app.py,sha256=pUku4yW7VgRH5SalRn5lT4lZZz1-3mSHYOk3oy5nUKs,5738
+fastapi_plugin_notification/client.py,sha256=9Z7-sxe8J4qqKrvcgQFan_2ecdFhEA3uZhBEAZWD6_s,7268
+fastapi_plugin_notification/controller.py,sha256=_IJh59F0zGg2la1yjLY-tGXKrC14dofCYgV3Bnk6CCI,547
+fastapi_plugin_notification/models.py,sha256=m-UrdUshVptxIZoAQxKaVz_qAQU77EyjbRxUyASzS-E,1583
+fastapi_plugin_notification/schemas.py,sha256=MyyIM0GS8u9WriX4RFsRKHxrCpAhavM1O43Dss8Waqk,2965
+fastapi_plugin_notification-0.1.0.dist-info/licenses/LICENSE,sha256=deA1OnQ6dNoSO7U62Kof2Dm8w3wiJVG43wen9Ayrvv4,1071
+fastapi_plugin_notification-0.1.0.dist-info/METADATA,sha256=rgkqeXvw6CWV3qnlIJhb7M8Xs9_3VTARLv95bk-dKuU,9953
+fastapi_plugin_notification-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fastapi_plugin_notification-0.1.0.dist-info/top_level.txt,sha256=ClKDla4uJBmjEnZuGLXNf3zXj0Ecz34wtRzesi3joBY,28
+fastapi_plugin_notification-0.1.0.dist-info/RECORD,,

fastapi_plugin_notification-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastapi_plugin_notification-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Guillaume Piot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_plugin_notification-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_plugin_notification