Metadata-Version: 2.4
Name: fastapi-plugin-notification
Version: 0.2.1
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
- 🗞️ **Digests**: Daily or weekly digest emails, grouped by category
- 🧹 **Retention**: Configurable cleanup of notifications past their retention window
- 🚀 **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
```

## At a Glance

```python
from fastapi_provider_postmark import PostmarkProvider
from fastapi_plugin_notification import NotificationClient

notification_client = NotificationClient(
    postmark_provider=PostmarkProvider(...),
    default_template_id=123456,
)

notification = await notification_client.send_notification(
    db_engine=db,
    name="welcome",
    user_id="user_123",
    user_email="user@example.com",
    claims=request.state.claims,
    link="https://example.com/dashboard",
    link_name="Go to Dashboard",
)
```

Full setup — client, router and dependencies — is in the [Quick Start](docs/quickstart.md).

## Documentation

| Guide | Contents |
| --- | --- |
| [Quick Start](docs/quickstart.md) | Initialize the client, mount the router, send your first notification |
| [Usage Examples](docs/usage.md) | Storing, sending, listing and acknowledging notifications |
| [Notification Digests](docs/digests.md) | Daily/weekly digests, category grouping, example payload, Postmark Mustachio templates |
| [Cleaning Up Old Notifications](docs/cleanup.md) | Retention window and permanently removing stale notifications |
| [API Endpoints](docs/api-endpoints.md) | HTTP routes with request parameters and response bodies |
| [Model Structure](docs/model.md) | Fields on `NotificationModel` |
| [Ownership and Permissions](docs/ownership.md) | Claim-based ownership and required permissions |
| [Configuration](docs/configuration.md) | Router options, template variables, error handling |
| [Development](docs/development.md) | Local setup and running the tests |

Release history is in the [Changelog](CHANGELOG.md).

## License

MIT License - see LICENSE file for details
