Notifications API

Boîte de réception et contrôles de livraison

Lire les notifications, régler la livraison, enregistrer les appareils et définir les règles de la boîte de réception

Ces itinéraires alimentent la boîte de réception des notifications de connexion, les préférences de livraison, le registre des appareils push, filtres et règles, étendues muettes et actions au niveau du thread.

JWT ou clé utilisateur APIFiltrage de la boîte de réceptionPériphériques pushRègles et sourdines

Authentification et autorisations

• Tous les itinéraires sur cette page nécessitent une authentification.
• Tout est limité à l'utilisateur authentifié.
• filters et rules sont des familles de routes parallèles pour le même concept sous-jacent dans la surface de contrôleur actuelle.

Référence du point de terminaison

Boîte de réception et livraison

Méthode	Chemin	Objectif	Demande ou requête	Authentification
GET	/api/notifications	Répertoriez les notifications.	Requête : unreadOnly,archived,threadId,afterCursor	Clé JWT ou utilisateur API
PATCH	/api/notifications/:id/read	Marquez une notification comme lue.	Chemin : id	Clé JWT ou utilisateur API
PATCH	/api/notifications/:id/unread	Marquez une notification comme non lue.	Chemin : id	Clé JWT ou utilisateur API
POST	/api/notifications/read-all	Marquez toutes les notifications comme lues.	Aucun	Clé JWT ou utilisateur API
GET	/api/notifications/catalog	Lisez le catalogue de notifications.	Aucun	Clé JWT ou utilisateur API
GET	/api/notifications/scopes	Lire les étendues disponibles pour un type.	Requête : type	Clé JWT ou utilisateur API
GET	/api/notifications/preferences	Lisez les préférences de livraison.	Aucun	Clé JWT ou utilisateur API
PUT	/api/notifications/preferences	Remplacez les préférences de livraison.	Corps : preferences	Clé JWT ou utilisateur API
POST	/api/notifications/devices	Enregistrez un appareil push.	Corps : platform,token,userAgent	Clé JWT ou utilisateur API
DELETE	/api/notifications/devices/:deviceId	Supprimer un périphérique push.	Chemin : deviceId	Clé JWT ou utilisateur API

Filtres et règles

Méthode	Chemin	Objectif	Demande ou requête	Authentification
GET	/api/notifications/filters	Répertoriez les règles de filtrage.	Aucun	Clé JWT ou utilisateur API
POST	/api/notifications/filters	Créez ou mettez à jour un filtre.	Corps : charge utile de la règle de boîte de réception	Clé JWT ou utilisateur API
PATCH	/api/notifications/filters	Remplacez ou réorganisez les filtres.	Corps : rules	Clé JWT ou utilisateur API
DELETE	/api/notifications/filters/:id	Supprimez un filtre.	Chemin : id	Clé JWT ou utilisateur API
GET	/api/notifications/rules	Répertoriez les règles.	Aucun	Clé JWT ou utilisateur API
POST	/api/notifications/rules	Créez ou mettez à jour une règle.	Corps : charge utile de la règle de boîte de réception	Clé JWT ou utilisateur API
PATCH	/api/notifications/rules	Remplacez ou réorganisez les règles.	Corps : rules	Clé JWT ou utilisateur API
DELETE	/api/notifications/rules/:id	Supprimez une règle.	Chemin : id	Clé JWT ou utilisateur API

Sourdines et fils

Méthode	Chemin	Objectif	Demande ou requête	Authentification
GET	/api/notifications/mutes	Répertoriez les étendues désactivées.	Aucun	Clé JWT ou utilisateur API
POST	/api/notifications/mutes	Créez ou mettez à jour une sourdine.	Corps : scopeType,scopeId,isMuted	Clé JWT ou utilisateur API
DELETE	/api/notifications/mutes/:scopeType/:scopeId	Supprimez une sourdine.	Chemin : scopeType,scopeId	Clé JWT ou utilisateur API
GET	/api/notifications/threads	Répertoriez les fils de notification.	Aucun	Clé JWT ou utilisateur API
PATCH	/api/notifications/threads/:id/mute	Coupez le son d'un fil.	Chemin : id	Clé JWT ou utilisateur API
PATCH	/api/notifications/threads/:id/unmute	Réactivez un fil de discussion.	Chemin : id	Clé JWT ou utilisateur API
PATCH	/api/notifications/threads/:id/archive	Archivez un fil de discussion.	Chemin : id	Clé JWT ou utilisateur API
PATCH	/api/notifications/threads/:id/unarchive	Désarchivez un fil de discussion.	Chemin : id	Clé JWT ou utilisateur API

Demander des formes

Requête de liste

ListNotificationsQueryDto

• unreadOnly : booléen facultatif
• archived : booléen facultatif
• threadId : numéro facultatif
• afterCursor : chaîne facultative

Préférences

UpdateNotificationPreferencesDto.preferences[]

• eventType : chaîne obligatoire
• channels : mappe d'objets requise
• digest : chaîne facultative
• fallbackOrder : tableau de chaînes facultatif
• quietHours : objet optionnel ou null

Enregistrement de l'appareil

RegisterDeviceDto

• platform : obligatoire web|ios|android
• token : chaîne obligatoire
• userAgent : chaîne facultative

Mode Pack et retour d'information

Corps de PUT /api/notifications/mode-pack :

• modePack : "focus_adhd" | "work_store" | "family" | null — null efface la sélection

Sélectionner un pack (re)génère un petit ensemble de règles de boîte de réception globales appartenant à ce pack (marquées en interne via une colonne packOwned, afin que le changement de pack ne touche jamais vos propres règles créées manuellement) et supprime les règles que le pack précédent avait générées. family ne génère actuellement aucune règle (aucun rôle enfant/lecture uniquement n'existe encore sur la plateforme), donc le sélectionner ne fait qu'enregistrer la préférence. Renvoie la ligne UserNotificationSettings enregistrée (userId, modePack, feedbackTuning, createdAt, updatedAt).

GET /api/notifications/mode-pack renvoie la même structure, ou null si l'utilisateur n'en a jamais défini.

Corps de POST /api/notifications/feedback :

• class : obligatoire, l'un des critical|time_critical|coordination|operational|fyi (énumération NotificationClass)
• direction : obligatoire, "too_much" | "too_quiet"

too_much rend cette classe un palier plus silencieuse pour les futures notifications (vers un routage hold_for_gap/batch_digest) ; too_quiet la rend un palier plus bruyante (vers interrupt_now). critical n'est jamais ajustable de cette façon - le moteur de triage ignore toujours le réglage du retour d'information pour cette classe. Renvoie la ligne UserNotificationSettings mise à jour avec la nouvelle carte feedbackTuning (par exemple { "operational": -1 }).

Filtres et règles

InboxRuleDto

• id : numéro facultatif
• name : chaîne obligatoire
• scopeType : obligatoire global|organisation|calendar|reservation
• scopeId : facultatif
• isEnabled : booléen obligatoire
• conditions : tableau requis de { field, operator, value }
• actions : tableau requis de { type, payload }
• continueProcessing : booléen facultatif
• order : numéro facultatif

UpdateInboxRulesDto.rules : tableau requis de InboxRuleDto

Sourdines

ScopeMuteDto

• scopeType : obligatoire organisation|calendar|reservation|resource|thread
• scopeId : chaîne obligatoire
• isMuted : booléen obligatoire

Exemples d'appels

Répertorier les notifications non lues

curl "$PRIMECAL_API/api/notifications?unreadOnly=true" \
  -H "Authorization: Bearer $TOKEN"

Mettre à jour les préférences

curl -X PUT "$PRIMECAL_API/api/notifications/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [
      {
        "eventType": "event.reminder",
        "channels": {
          "inapp": true,
          "email": false,
          "webpush": true
        },
        "digest": "immediate",
        "fallbackOrder": ["webpush"]
      }
    ]
  }'

Enregistrer un appareil

curl -X POST "$PRIMECAL_API/api/notifications/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "web",
    "token": "push-token-example",
    "userAgent": "Chrome 135"
  }'

Créer un muet

curl -X POST "$PRIMECAL_API/api/notifications/mutes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scopeType": "calendar",
    "scopeId": "12",
    "isMuted": true
  }'

Notes de réponse et de comportement

• GET /api/notifications/catalog est la source la plus sûre pour créer des éditeurs de préférences ou de règles.
• GET /api/notifications/scopes renvoie les options de portée actuellement valides pour le type de notification demandé.
• Les routes de filtre et de règle sont toutes deux actives dans la surface du contrôleur ; traitez-les comme des points d’entrée parallèles au même modèle.
• La suppression de périphérique et la suppression muette renvoient des réponses de type réussite plutôt que des objets riches.

Meilleures pratiques

• Utilisez afterCursor pour le chargement incrémentiel de la boîte de réception au lieu de récupérer une grande liste illimitée.
• Créez des éditeurs de règles à partir du catalogue actif et des points de terminaison de portée au lieu de types d'événements codés en dur.
• Gardez l’enregistrement de l’appareil idempotent dans le client. Le backend peut réutiliser une association de jetons existante.
• Préférez les sourdines pour la suppression temporaire et les règles pour un comportement de routage ou d'archivage de longue durée.
• Exposez les actions de thread séparément dans l’interface utilisateur. La mise en sourdine/archive du thread est un concept différent des paramètres de mise en sourdine au niveau de la portée.