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}