Notifier un utilisateur

Un client paie une facture pendant la nuit, et le comptable doit le voir le lendemain matin. Un toast ne sert à rien ici : personne n'était devant l'écran. Ce guide montre comment un module dépose une notification que l'utilisateur retrouve dans la cloche de l'admin, et en option dans sa boîte courriel.

PrérequisCopier le lien de la section

• La migration 012-create-notifications du core est passée : npx fraza-db migrate.
• Le code qui notifie tourne côté serveur : une route API, une action serveur, une tâche cron, un webhook.

Notifier une personneCopier le lien de la section

import { notify } from '@fraza/core/notifications';

await notify({
  to: { userId: share.recipientId },
  type: 'drive.share',
  source: '@fraza/module-drive',
  title: 'Un dossier a été partagé',
  href: `/admin/drive/${share.folderId}`,
});

type dit ce qui s'est passé, source qui le dit. href est un chemin du site : la cloche l'ouvre au clic. La notification apparaît dans la cloche en 45 secondes au plus, avec un toast si l'admin est ouvert.

Notifier tous ceux qui ont une permissionCopier le lien de la section

Le module ne connaît pas toujours les destinataires : il sait seulement qui a le droit de voir l'événement. permission les trouve au moment de l'appel.

await notify({
  to: { permission: 'billing.view', exclude: [session.user.id] },
  type: 'billing.invoice-paid',
  source: '@fraza-pro/module-billing',
  title: `Facture ${invoice.number} payée`,
  body: `${invoice.clientName} a réglé ${formatAmount(invoice.total)}.`,
  href: `/admin/billing/invoices/${invoice.id}`,
});

exclude retire l'auteur de l'action : celui qui vient de marquer la facture payée n'a pas besoin qu'on le lui dise.

Ajouter une copie par courrielCopier le lien de la section

email: true met un courriel dans la file d'envoi pour chaque destinataire. Il reprend le titre, le corps et un bouton vers href. Un échec du fournisseur est repris par la file, comme pour queueEmail.

await notify({ ...notification, email: true });

Réserver le courriel à ce qui ne peut pas attendre la prochaine visite de l'admin. Une notification par courriel pour chaque événement mineur apprend vite à ignorer les deux.

Notifier dans une transactionCopier le lien de la section

Une notification qui part alors que l'écriture qu'elle annonce a échoué ment à son lecteur. Passer le client de la transaction : la notification et son courriel n'existent que si la transaction est validée.

import { transaction } from '@fraza/core/database';

await transaction(async (client) => {
  await client.query('UPDATE billing_invoices SET status = $1 WHERE id = $2', ['paid', invoice.id]);
  await notify({
    to: { permission: 'billing.view' },
    type: 'billing.invoice-paid',
    source: '@fraza-pro/module-billing',
    title: `Facture ${invoice.number} payée`,
    href: `/admin/billing/invoices/${invoice.id}`,
    email: true,
  }, { client });
});

Avec client, une erreur lève au lieu de retourner success: false : la transaction est annulée, et l'écriture avec elle.

Éviter les doublonsCopier le lien de la section

Un webhook peut arriver deux fois, une tâche cron peut être relancée. dedupeKey garantit une seule notification par utilisateur pour un même événement.

await notify({ ...notification, dedupeKey: `invoice:${invoice.id}:paid` });

Le second appel ne crée rien pour qui l'a déjà reçue, et data.count le dit.

Voir aussiCopier le lien de la section

• Notifications : la signature complète, les routes et la purge.
• Toasts : le retour immédiat d'une action dans l'interface.