road-runner-common 0.22.0

//! What a service says happened.
//!
//! This is the extension point of the whole module. A service adds a notification by
//! implementing [`NotificationEvent`] for a struct that carries the facts — not by
//! writing another HTTP call, another locale lookup or another payload map inline at
//! the call site. The struct doubles as documentation of the workflow's template
//! variables, and its fields are the only thing a reviewer has to check against the
//! notification center.

use super::trigger::Severity;

/// One notifiable business fact, bound to the workflow that renders it.
///
/// Implementations should be plain data — build one at the point where the fact becomes
/// true, and hand it to [`Notifier`](super::Notifier). `Send + Sync` is required so an
/// event can be handed to a background task
/// ([`Notifier::notify_detached`](super::Notifier::notify_detached)); plain data
/// satisfies it automatically.
pub trait NotificationEvent: Send + Sync {
    /// Canonical trigger identifier. Use a constant from
    /// [`workflows`](super::workflows) rather than a literal — the value must match the
    /// notification center exactly or the trigger fails with 422.
    fn workflow(&self) -> &str;

    /// Template variables, by the names the workflow's template uses. A key the template
    /// does not reference is ignored; a key it references and this omits renders empty,
    /// so this is the contract worth reviewing against the template.
    fn payload(&self) -> serde_json::Value;

    /// Delivery severity — queue priority and SMS provider routing. Defaults to
    /// [`Severity::Normal`]; raise it for anything the user is waiting on.
    fn severity(&self) -> Severity {
        Severity::default()
    }

    /// Idempotency / dedup key. Return a stable id derived from the business fact (a
    /// request id, a settlement id) so a retried or replayed producer does not notify
    /// twice. `None` means the notification center will not deduplicate.
    fn transaction_id(&self) -> Option<String> {
        None
    }
}