forge-mvc-notifications

Notifications in-app opt-in pour Forge : créer des notifications destinées aux utilisateurs (élève inscrit, note publiée, devoir à rendre) dans une table notifications, les lire, les marquer comme lues.

Périmètre V1 : notifications in-app (des lignes en base, affichées dans l'IHM). La livraison hors application (email, push) reste à la charge de l'application, par exemple en combinant ce paquet avec forge-mvc-jobs et forge-mvc-mail.

Installation

pip install --pre forge-mvc-notifications

En développement : pip install -e ./packages/forge-mvc-notifications.

Mise en place de la table

forge notifications:init   # copie la migration dans mvc/migrations/
forge migration:apply      # crée la table notifications

Utilisation

from forge_mvc_notifications import notify, get_notifications, unread_count, mark_read

notify("eleve.42", "Votre note est publiée", type="info", data={"cours": "maths"})

print(unread_count("eleve.42"))            # 1
for n in get_notifications("eleve.42", unread_only=True):
    print(n.message, n.created_at)
mark_read(1)

L'API expose notify, get_notifications, unread_count, mark_read, mark_all_read, plus Notification, NotificationError, TABLE_NAME, MAX_LIMIT.

Afficher les notifications dans une page

from forge_mvc_notifications import register_notification_routes

register_notification_routes(router, recipient_of=lambda r: destinataire_de(r))

Quatre routes JSON : GET /api/notifications/unread-count, GET /api/notifications (paginée par curseur), POST /api/notifications/{id}/read et POST /api/notifications/read-all.

recipient_of est obligatoire. Le destinataire vient de la session, jamais de la requête : accepter ?recipient=... donnerait à quiconque les notifications de n'importe qui. Le marquage est borné au même destinataire.

Ces routes rendent du JSON et ne poussent rien ; le rafraîchissement s'écrit avec HTMX, que le squelette livre déjà.

Périmètre

• Stockage in-app uniquement (lignes en base).
• Routes JSON de lecture et de marquage, à câbler explicitement.
• Hors périmètre : livraison email/push (à combiner avec forge-mvc-jobs + forge-mvc-mail), préférences de notification, poussée temps réel (SSE, WebSocket) et script de rafraîchissement.

Documentation complète : https://forgemvc.com/docs/forge/.