hookburn-core 0.2.2

Shared HTTP client and WebhookSender trait for the Hookburn crates
Documentation
// crates/hookburn-core/src/message.rs
use crate::CoreError;
use rustc_hash::FxHashMap;
use serde::{Deserialize, Serialize};

/// A service-agnostic webhook message that can be converted to any service's format.
///
/// Use this type when you want to write code that works with multiple webhook
/// services (Discord, Slack, etc.) without knowing which one you're targeting.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GenericMessage {
    /// Plain text content
    pub content: Option<String>,
    /// Override the default username
    pub username: Option<String>,
    /// Override the default avatar
    pub avatar_url: Option<String>,
    /// Text-to-speech flag
    pub tts: bool,
    /// Rich embed attachments
    pub embeds: Vec<GenericEmbed>,
    /// Service-specific metadata
    pub metadata: FxHashMap<String, serde_json::Value>,
    /// File attachments
    pub attachments: Vec<Attachment>,
}

impl GenericMessage {
    /// Create a new message with text content.
    pub fn new(content: impl Into<String>) -> Self {
        Self { content: Some(content.into()), ..Default::default() }
    }

    /// Add an embed to the message.
    pub fn with_embed(mut self, embed: GenericEmbed) -> Self {
        self.embeds.push(embed);
        self
    }

    /// Set the username override.
    pub fn with_username(mut self, username: impl Into<String>) -> Self {
        self.username = Some(username.into());
        self
    }

    /// Set the avatar URL override.
    pub fn with_avatar(mut self, avatar_url: impl Into<String>) -> Self {
        self.avatar_url = Some(avatar_url.into());
        self
    }

    /// Add service-specific metadata.
    pub fn with_metadata(
        mut self,
        key: impl Into<String>,
        value: impl Serialize,
    ) -> Result<Self, CoreError> {
        self.metadata
            .insert(key.into(), serde_json::to_value(value)?);
        Ok(self)
    }

    /// Enable text-to-speech.
    pub fn with_tts(mut self, tts: bool) -> Self {
        self.tts = tts;
        self
    }

    /// Add a file attachment.
    pub fn with_attachment(mut self, attachment: Attachment) -> Self {
        self.attachments.push(attachment);
        self
    }
}

/// A rich embed that works across multiple webhook services.
///
/// Not all services support all fields. Check the service's capabilities
/// via `ServiceInfo::features`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GenericEmbed {
    /// The title of the embed, displayed prominently at the top.
    pub title: Option<String>,

    /// The main body text of the embed.
    pub description: Option<String>,

    /// A URL that the title links to when clicked.
    pub url: Option<String>,

    /// The color of the embed's left border, specified as a 24-bit integer.
    /// Example: `0x5865F2` for Discord blurple.
    pub color: Option<u32>,

    /// An ISO 8601 timestamp string displayed in the embed.
    /// Example: `"2024-01-01T00:00:00.000Z"`.
    pub timestamp: Option<String>,

    /// Footer text and optional icon displayed at the bottom of the embed.
    pub footer: Option<GenericEmbedFooter>,

    /// A large image displayed within the embed body.
    pub image: Option<GenericEmbedImage>,

    /// A smaller thumbnail image displayed in the top-right corner.
    pub thumbnail: Option<GenericEmbedThumbnail>,

    /// Author information including name, URL, and icon displayed at the top.
    pub author: Option<GenericEmbedAuthor>,

    /// A list of field objects displayed as key-value pairs in the embed.
    /// Fields can be displayed side-by-side when `inline` is set to `true`.
    pub fields: Vec<GenericEmbedField>,
}

impl GenericEmbed {
    /// Create a new embed with a title and description.
    pub fn new(title: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            title: Some(title.into()),
            description: Some(description.into()),
            ..Default::default()
        }
    }

    /// Set the embed color (24-bit integer).
    pub fn with_color(mut self, color: u32) -> Self {
        self.color = Some(color);
        self
    }

    /// Add a field to the embed.
    pub fn with_field(
        mut self,
        name: impl Into<String>,
        value: impl Into<String>,
        inline: bool,
    ) -> Self {
        self.fields
            .push(GenericEmbedField { name: name.into(), value: value.into(), inline });
        self
    }
}

/// A key-value field displayed within an embed.
///
/// Fields are used to display structured information in a clean format.
/// Multiple fields can be placed side-by-side using the `inline` flag.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GenericEmbedField {
    /// The field label displayed in bold.
    pub name: String,

    /// The field content displayed after the label.
    pub value: String,

    /// If true, this field can be displayed next to other inline fields.
    /// If false, the field takes the full width.
    pub inline: bool,
}

/// Footer text and optional icon displayed at the bottom of an embed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GenericEmbedFooter {
    /// The footer text.
    pub text: String,

    /// Optional URL to an icon displayed next to the footer text.
    pub icon_url: Option<String>,
}

/// An image displayed within an embed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GenericEmbedImage {
    /// The URL of the image.
    pub url: String,
}

/// A thumbnail image displayed in the corner of an embed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GenericEmbedThumbnail {
    /// The URL of the thumbnail image.
    pub url: String,
}

/// Author information displayed at the top of an embed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GenericEmbedAuthor {
    /// The author's name.
    pub name: String,

    /// Optional URL that the author name links to.
    pub url: Option<String>,

    /// Optional URL to an icon displayed next to the author's name.
    pub icon_url: Option<String>,
}

/// A file attachment to be sent with the message.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Attachment {
    /// The name of the file.
    pub filename: String,

    /// The raw binary content of the file.
    pub content: Vec<u8>,

    /// The MIME type of the file (e.g., "image/png", "application/pdf").
    pub content_type: String,
}
/// Converts between generic and service-specific message formats.
///
/// Service crates implement this trait to enable the use of `GenericMessage`
/// with their specific client types.
pub trait MessageConverter<T> {
    /// Convert a generic message to service-specific format.
    fn to_service(&self, generic: &GenericMessage) -> Result<T, CoreError>;

    /// Convert a service-specific message back to generic format.
    fn to_generic(&self, service_msg: &T) -> Result<GenericMessage, CoreError>;
}