Skip to main content

hookburn_core/
message.rs

1// crates/hookburn-core/src/message.rs
2use crate::CoreError;
3use rustc_hash::FxHashMap;
4use serde::{Deserialize, Serialize};
5
6/// A service-agnostic webhook message that can be converted to any service's format.
7///
8/// Use this type when you want to write code that works with multiple webhook
9/// services (Discord, Slack, etc.) without knowing which one you're targeting.
10#[derive(Debug, Clone, Default, Serialize, Deserialize)]
11pub struct GenericMessage {
12    /// Plain text content
13    pub content: Option<String>,
14    /// Override the default username
15    pub username: Option<String>,
16    /// Override the default avatar
17    pub avatar_url: Option<String>,
18    /// Text-to-speech flag
19    pub tts: bool,
20    /// Rich embed attachments
21    pub embeds: Vec<GenericEmbed>,
22    /// Service-specific metadata
23    pub metadata: FxHashMap<String, serde_json::Value>,
24    /// File attachments
25    pub attachments: Vec<Attachment>,
26}
27
28impl GenericMessage {
29    /// Create a new message with text content.
30    pub fn new(content: impl Into<String>) -> Self {
31        Self { content: Some(content.into()), ..Default::default() }
32    }
33
34    /// Add an embed to the message.
35    pub fn with_embed(mut self, embed: GenericEmbed) -> Self {
36        self.embeds.push(embed);
37        self
38    }
39
40    /// Set the username override.
41    pub fn with_username(mut self, username: impl Into<String>) -> Self {
42        self.username = Some(username.into());
43        self
44    }
45
46    /// Set the avatar URL override.
47    pub fn with_avatar(mut self, avatar_url: impl Into<String>) -> Self {
48        self.avatar_url = Some(avatar_url.into());
49        self
50    }
51
52    /// Add service-specific metadata.
53    pub fn with_metadata(
54        mut self,
55        key: impl Into<String>,
56        value: impl Serialize,
57    ) -> Result<Self, CoreError> {
58        self.metadata
59            .insert(key.into(), serde_json::to_value(value)?);
60        Ok(self)
61    }
62
63    /// Enable text-to-speech.
64    pub fn with_tts(mut self, tts: bool) -> Self {
65        self.tts = tts;
66        self
67    }
68
69    /// Add a file attachment.
70    pub fn with_attachment(mut self, attachment: Attachment) -> Self {
71        self.attachments.push(attachment);
72        self
73    }
74}
75
76/// A rich embed that works across multiple webhook services.
77///
78/// Not all services support all fields. Check the service's capabilities
79/// via `ServiceInfo::features`.
80#[derive(Debug, Clone, Default, Serialize, Deserialize)]
81pub struct GenericEmbed {
82    /// The title of the embed, displayed prominently at the top.
83    pub title: Option<String>,
84
85    /// The main body text of the embed.
86    pub description: Option<String>,
87
88    /// A URL that the title links to when clicked.
89    pub url: Option<String>,
90
91    /// The color of the embed's left border, specified as a 24-bit integer.
92    /// Example: `0x5865F2` for Discord blurple.
93    pub color: Option<u32>,
94
95    /// An ISO 8601 timestamp string displayed in the embed.
96    /// Example: `"2024-01-01T00:00:00.000Z"`.
97    pub timestamp: Option<String>,
98
99    /// Footer text and optional icon displayed at the bottom of the embed.
100    pub footer: Option<GenericEmbedFooter>,
101
102    /// A large image displayed within the embed body.
103    pub image: Option<GenericEmbedImage>,
104
105    /// A smaller thumbnail image displayed in the top-right corner.
106    pub thumbnail: Option<GenericEmbedThumbnail>,
107
108    /// Author information including name, URL, and icon displayed at the top.
109    pub author: Option<GenericEmbedAuthor>,
110
111    /// A list of field objects displayed as key-value pairs in the embed.
112    /// Fields can be displayed side-by-side when `inline` is set to `true`.
113    pub fields: Vec<GenericEmbedField>,
114}
115
116impl GenericEmbed {
117    /// Create a new embed with a title and description.
118    pub fn new(title: impl Into<String>, description: impl Into<String>) -> Self {
119        Self {
120            title: Some(title.into()),
121            description: Some(description.into()),
122            ..Default::default()
123        }
124    }
125
126    /// Set the embed color (24-bit integer).
127    pub fn with_color(mut self, color: u32) -> Self {
128        self.color = Some(color);
129        self
130    }
131
132    /// Add a field to the embed.
133    pub fn with_field(
134        mut self,
135        name: impl Into<String>,
136        value: impl Into<String>,
137        inline: bool,
138    ) -> Self {
139        self.fields
140            .push(GenericEmbedField { name: name.into(), value: value.into(), inline });
141        self
142    }
143}
144
145/// A key-value field displayed within an embed.
146///
147/// Fields are used to display structured information in a clean format.
148/// Multiple fields can be placed side-by-side using the `inline` flag.
149#[derive(Debug, Clone, Serialize, Deserialize)]
150pub struct GenericEmbedField {
151    /// The field label displayed in bold.
152    pub name: String,
153
154    /// The field content displayed after the label.
155    pub value: String,
156
157    /// If true, this field can be displayed next to other inline fields.
158    /// If false, the field takes the full width.
159    pub inline: bool,
160}
161
162/// Footer text and optional icon displayed at the bottom of an embed.
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub struct GenericEmbedFooter {
165    /// The footer text.
166    pub text: String,
167
168    /// Optional URL to an icon displayed next to the footer text.
169    pub icon_url: Option<String>,
170}
171
172/// An image displayed within an embed.
173#[derive(Debug, Clone, Serialize, Deserialize)]
174pub struct GenericEmbedImage {
175    /// The URL of the image.
176    pub url: String,
177}
178
179/// A thumbnail image displayed in the corner of an embed.
180#[derive(Debug, Clone, Serialize, Deserialize)]
181pub struct GenericEmbedThumbnail {
182    /// The URL of the thumbnail image.
183    pub url: String,
184}
185
186/// Author information displayed at the top of an embed.
187#[derive(Debug, Clone, Serialize, Deserialize)]
188pub struct GenericEmbedAuthor {
189    /// The author's name.
190    pub name: String,
191
192    /// Optional URL that the author name links to.
193    pub url: Option<String>,
194
195    /// Optional URL to an icon displayed next to the author's name.
196    pub icon_url: Option<String>,
197}
198
199/// A file attachment to be sent with the message.
200#[derive(Debug, Clone, Serialize, Deserialize)]
201pub struct Attachment {
202    /// The name of the file.
203    pub filename: String,
204
205    /// The raw binary content of the file.
206    pub content: Vec<u8>,
207
208    /// The MIME type of the file (e.g., "image/png", "application/pdf").
209    pub content_type: String,
210}
211/// Converts between generic and service-specific message formats.
212///
213/// Service crates implement this trait to enable the use of `GenericMessage`
214/// with their specific client types.
215pub trait MessageConverter<T> {
216    /// Convert a generic message to service-specific format.
217    fn to_service(&self, generic: &GenericMessage) -> Result<T, CoreError>;
218
219    /// Convert a service-specific message back to generic format.
220    fn to_generic(&self, service_msg: &T) -> Result<GenericMessage, CoreError>;
221}