Metadata-Version: 2.4
Name: fastpluggy-notification-center
Version: 0.2.0
Summary: Persistent notification center with topbar bell, event bus integration, and optional Web Push
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: FastPluggy>=0.4.0
Provides-Extra: push
Requires-Dist: pywebpush>=2.0.0; extra == "push"
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == "tests"
Requires-Dist: pytest-cov>=4.0; extra == "tests"
Provides-Extra: e2e
Requires-Dist: fastpluggy-cli; extra == "e2e"

# fastpluggy-notification-center

![Notification Center](https://img.shields.io/badge/FastPluggy-Notification%20Center-blue)
[![Release](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/notification_center/-/badges/release.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/notification_center/-/releases)
[![Pipeline Status](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/notification_center/badges/main/pipeline.svg?key_text=CI)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/notification_center/-/pipelines?ignore_skipped=true)
[![Coverage](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/notification_center/badges/main/coverage.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/notification_center/-/pipelines)

Persistent notification center for FastPluggy with topbar bell icon, event bus integration, pluggable delivery channels, and optional Web Push support.

## Installation

```bash
pip install fastpluggy-notification-center
```

For Web Push support:

```bash
pip install fastpluggy-notification-center[push]
```

## Features

- **Topbar bell icon** — unread badge count, slide-out notification panel
- **Event bus integration** — listens to all `notification.*` events automatically
- **Pluggable channels** — any plugin can register as a delivery channel via the `NotificationChannel` protocol
- **Channel relay** — forward notifications to external channels (ntfy, email, etc.) based on category
- **Web Push** — browser push notifications via VAPID (auto-generates keys on first load)
- **Notification categories** — `info`, `success`, `warning`, `error` with colored badges
- **Read/unread tracking** — mark individual or bulk mark-as-read
- **Auto-cleanup** — configurable retention period (default 30 days)

## Configuration

Settings are managed via `NotificationCenterSettings` (database-backed). Configure through the FastPluggy settings UI.

| Setting | Default | Description |
|---------|---------|-------------|
| `notification_retention_days` | `30` | Days to keep notifications before cleanup |
| `max_notifications_per_page` | `50` | Pagination size for notification list |
| `relay_enabled` | `false` | Enable forwarding to delivery channels |
| `relay_channels` | `[]` | Channel names to relay to (empty = all discovered) |
| `relay_categories` | `["error"]` | Only relay notifications with these categories |
| `web_push_enabled` | `true` | Enable browser Web Push support |
| `vapid_private_key` | `""` | VAPID private key (auto-generated if empty) |
| `vapid_public_key` | `""` | VAPID public key (auto-generated if empty) |
| `vapid_contact_email` | `""` | Contact email for VAPID identification |

## Usage

### Sending notifications via event bus

Any plugin can emit a notification event:

```python
fast_pluggy.events.emit("notification.info", payload={
    "title": "Task completed",
    "message": "Backup finished successfully",
    "category": "success",
    "data": {"task_id": 42},
})
```

### Sending browser push notifications

```python
fast_pluggy.events.emit("notification.push", payload={
    "title": "Deployment ready",
    "message": "v1.2.0 is live",
    "url": "/plugin/ecosystem_status/",
})
```

### Explicit relay to all channels

Bypasses the category filter:

```python
fast_pluggy.events.emit("notification.relay", payload={
    "title": "Critical alert",
    "message": "Database connection lost",
    "category": "error",
})
```

### Registering a delivery channel

Any plugin can act as a delivery channel by implementing the `NotificationChannel` protocol:

```python
from fastpluggy_plugin.notification_center.channels import NotificationChannel

class MyChannel:
    channel_name = "my_channel"

    def send(self, title, message, category, data=None):
        # deliver the notification
        ...

class MyPlugin(FastPluggyBaseModule):
    notification_channel = MyChannel()
```

The notification center discovers channels automatically at startup.

## Dashboard

The notification panel is accessible via the topbar bell icon on every page. A full notification history page is available at `/plugin/notification_center/` (CI) or `/plugin-pkg/notification_center/` (local dev).
