linkbay-notifications 0.1.0
Real-time notification system for LinkBay CMS with multi-channel delivery (email, push, SMS, webhooks)
License: MIT
Requires Python: >=3.8
Keywords: linkbay, notifications, realtime, websocket, email, push, sms, fastapi

# LinkBay Notifications v0.1.0

[![License](https://img.shields.io/badge/license-MIT-blue)]() [![Python](https://img.shields.io/badge/python-3.8+-blue)]()

Real-time notification system for LinkBay CMS with multi-channel delivery (email, push, SMS, webhooks).

## Prima di iniziare

Questa libreria è perfetta se:
- Hai bisogno di notifiche multi-canale (email, push, SMS, in-app)
- Vuoi notifiche real-time via WebSocket
- Gestisci preferenze utente per opt-in/opt-out
- Lavori in ambiente multi-tenant
- Vuoi template dinamici con variabili

Non è adatta se cerchi solo un semplice invio email (usa direttamente smtplib).

## Installazione

```bash
pip install linkbay-notifications
```

Con supporto SMS (Twilio):
```bash
pip install linkbay-notifications[sms]
```

Oppure l'ultima versione dal repository:

```bash
pip install git+https://github.com/AlessioQuagliara/LinkBay-Notifications
```

## Come funziona (3 passi)

### 1. Implementa i callback per database

```python
# Implementa le funzioni di storage
async def get_user_context(user_id: str, tenant_id: str):
    """Recupera info utente (email, phone, lingua)"""
    user = await db.get_user(user_id)
    return {
        'user_email': user.email,
        'user_phone': user.phone,
        'language': user.language,
    }

async def check_preference(user_id, notification_type, channel_type):
    """Controlla se utente ha abilitato questo tipo di notifica"""
    pref = await db.get_preference(user_id, notification_type, channel_type)
    return pref.enabled if pref else True

async def store_notification(notification, context):
    """Salva notifica in-app nel database"""
    await db.notifications.create({
        'user_id': notification.user_id,
        'type': notification.type,
        'title': notification.title,
        'message': notification.message,
    })
```

### 2. Configura FastAPI

```python
from fastapi import FastAPI
from linkbay_notifications import (
    NotificationManager, NotificationWebSocket,
    notifications_router, init_router,
    EmailChannel, InAppChannel, ChannelType
)

app = FastAPI()

# Crea manager
manager = NotificationManager(
    preference_callback=check_preference,
    context_callback=get_user_context,
)

# Registra canali
manager.register_channel(
    ChannelType.EMAIL,
    EmailChannel(
        smtp_host='smtp.gmail.com',
        smtp_port=587,
        smtp_user='noreply@example.com',
        smtp_password='your-password',
    )
)

manager.register_channel(
    ChannelType.IN_APP,
    InAppChannel(storage_callback=store_notification)
)

# Inizializza WebSocket
ws = NotificationWebSocket(auth_callback=authenticate_token)

# Aggiungi router
init_router(manager=manager, websocket_handler=ws, storage_callback=storage)
app.include_router(notifications_router)
```

### 3. Avvia e testa

```python
# Invia una notifica
from linkbay_notifications import NotificationCreate, NotificationType, ChannelType

notification = NotificationCreate(
    tenant_id="agency-123",
    user_id="user-456",
    type=NotificationType.ORDER_CONFIRMED,
    title="Ordine Confermato",
    message="Il tuo ordine #12345 è stato confermato",
    channels=[ChannelType.EMAIL, ChannelType.IN_APP],
    data={"order_id": "12345", "customer_name": "Mario Rossi"}
)

results = await manager.send(notification)
# results: {ChannelType.EMAIL: True, ChannelType.IN_APP: True}
```

## Esempio avanzato

### Template con variabili

```python
from linkbay_notifications import NotificationTemplate, TemplateVariable

template = NotificationTemplate(
    id="tpl-order-confirmed",
    tenant_id="agency-123",
    type=NotificationType.ORDER_CONFIRMED,
    channel=ChannelType.EMAIL,
    language="it",
    subject="Ordine {{order_number}} confermato",
    body="Ciao {{customer_name}}, il tuo ordine {{order_number}} è stato confermato!",
    body_html="<h1>Ciao {{customer_name}}</h1><p>Il tuo ordine <strong>{{order_number}}</strong> è stato confermato!</p>",
    variables=[
        TemplateVariable(name="customer_name", required=True),
        TemplateVariable(name="order_number", required=True)
    ]
)
```

### WebSocket real-time (client JavaScript)

```javascript
const ws = new WebSocket('ws://localhost:8000/notifications/ws?token=YOUR_JWT_TOKEN');

ws.onopen = () => console.log('Connesso');

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    if (data.type === 'notification') {
        // Nuova notifica
        showNotification(data.data.title, data.data.message);
    }
};

// Heartbeat
setInterval(() => {
    ws.send(JSON.stringify({type: 'ping'}));
}, 30000);
```

## Caratteristiche principali

- ✅ **Multi-canale**: Email (SMTP), Web Push, SMS (Twilio), In-App, Webhooks
- ✅ **Real-time**: WebSocket per notifiche istantanee
- ✅ **Template dinamici**: Variabili con sintassi `{{var}}`
- ✅ **Multi-tenant**: Isolamento completo tra tenant
- ✅ **Preferenze utente**: Opt-in/opt-out per canale e tipo
- ✅ **Database-agnostic**: Usi i tuoi modelli e callback
- ✅ **Leggero**: Codice semplice e manutenibile
- ✅ **Type-safe**: Pydantic schemas per validazione

## API Endpoints

| Endpoint | Metodo | Descrizione |
|----------|--------|-------------|
| `/notifications` | POST | Crea e invia notifica |
| `/notifications` | GET | Lista notifiche utente |
| `/notifications/{id}/read` | PATCH | Marca come letta |
| `/notifications/preferences` | GET | Ottieni preferenze |
| `/notifications/preferences` | PATCH | Aggiorna preferenze |
| `/notifications/ws` | WS | WebSocket real-time |
| `/notifications/broadcast/{tenant_id}` | POST | Broadcast a tenant |

## Testing

```bash
# Installa dipendenze dev
pip install linkbay-notifications[dev]

# Esegui test
pytest tests/
```

## Limitazioni note

- SMS richiede account Twilio (opzionale)
- Web Push richiede VAPID keys (implementazione base)
- Template HTML non supportano logica condizionale (solo variabili)


## Roadmap consigliata


## Licenza

MIT. Puoi usarla e modificarla liberamente, assicurandoti di valutarne i rischi nel tuo contesto.

## Supporto

- Issues: https://github.com/AlessioQuagliara/linkbay_notifications/issues
- Email: quagliara.alessio@gmail.com

Contribuisci, apri una issue o raccontaci come stai usando la libreria 🧡