capy-mail 0.10.0

Conventional SMTP mail, typed templates, and mail notifications for Capy.
Documentation
//! Small mail notifications, with explicit synchronous or queued delivery at the call site.
use crate::{DeliveryReceipt, Mail, MailResult, Mailbox, Mailer};

/// Mail-channel routing. No dependency on a generated user model or future channels.
pub trait MailRecipient {
    /// Return a parsed route, or None to intentionally skip mail for this recipient.
    fn mail_address(&self) -> Option<Mailbox>;
}
impl MailRecipient for Mailbox {
    fn mail_address(&self) -> Option<Mailbox> {
        Some(self.clone())
    }
}
/// An application event that may produce a mail message for a routed recipient.
pub trait Notification: Send + Sync {
    /// Stable safe diagnostic name.
    const NAME: &'static str;
    /// Render ordinary mail, or None to skip this notification.
    fn mail(&self, recipient: &Mailbox) -> MailResult<Option<Mail>>;
}
/// Explicit non-secret queue-storage opt-in; see `QueueableMail` for the threat boundary.
pub trait QueueableNotification: Notification {}
impl Mailer {
    /// Send a notification's mail channel once. Missing routes are an explicit skip.
    pub async fn notify<N: Notification>(
        &self,
        recipient: &impl MailRecipient,
        notification: N,
    ) -> MailResult<Option<DeliveryReceipt>> {
        let Some(route) = recipient.mail_address() else {
            return Ok(None);
        };
        let Some(mail) = notification.mail(&route)? else {
            return Ok(None);
        };
        self.send_mail(N::NAME, mail.to(route)).await.map(Some)
    }
    /// Durably queue a reviewed non-secret notification on the configured mail queue.
    #[cfg(feature = "jobs")]
    pub async fn queue_notification<N: QueueableNotification>(
        &self,
        ctx: &impl capy_jobs::JobDispatch,
        recipient: &impl MailRecipient,
        notification: N,
    ) -> MailResult<Option<String>> {
        let Some(route) = recipient.mail_address() else {
            return Ok(None);
        };
        let Some(mail) = notification.mail(&route)? else {
            return Ok(None);
        };
        let queue = ctx
            .jobs()
            .queue(self.settings.queue.clone())
            .map_err(|_| crate::MailError::Configuration)?;
        self.queue_rendered(
            crate::queued::QueueTarget::Pool(&queue),
            N::NAME,
            mail.to(route),
        )
        .await
        .map(Some)
    }
    /// Atomically enqueue using only the caller's native transaction; never a pool.
    #[cfg(feature = "jobs")]
    pub async fn queue_notification_in<N: QueueableNotification>(
        &self,
        transaction: &sea_orm::DatabaseTransaction,
        recipient: &impl MailRecipient,
        notification: N,
    ) -> MailResult<Option<String>> {
        let Some(route) = recipient.mail_address() else {
            return Ok(None);
        };
        let Some(mail) = notification.mail(&route)? else {
            return Ok(None);
        };
        let queue = capy_jobs::TransactionalQueue::new(transaction)
            .queue(self.settings.queue.clone())
            .map_err(|_| crate::MailError::Configuration)?;
        self.queue_rendered(
            crate::queued::QueueTarget::Transaction(queue),
            N::NAME,
            mail.to(route),
        )
        .await
        .map(Some)
    }
}