Add support for optional email attachments fetching

Introduced a `withAttachments` parameter to the `FetchEmailsAsync` method in `IImapEmailService` and related layers, allowing callers to include or exclude attachment data when fetching emails. Updated `FetchEmailsQuery` and `FetchEmailsQueryHandler` to propagate this parameter.

Refactored `LimilabsImapEmailService` to conditionally process attachments and inline visuals based on the `withAttachments` flag, improving performance when attachments are not required. Replaced `Flag.Unseen` with `Expression.HasFlag(Flag.Unseen)` for better criteria handling. Cleaned up attachment-processing logic for improved readability and maintainability.

src/core/DigitalData.MessagingService.Application/Common/Interfaces/IImapEmailService.cs

@@ -13,10 +13,12 @@ public interface IImapEmailService
     /// </summary>
     /// <param name="account">Account whose IMAP settings will be used.</param>
     /// <param name="filter">Filter to apply when fetching emails.</param>
+    /// <param name="withAttachments">When <see langword="true"/>, attachment data is included in the results; otherwise attachments are omitted. Defaults to <see langword="false"/>.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
     Task<IEnumerable<ReceivedEmailContext>> FetchEmailsAsync(
         EmailAccountDto account,
         MailSearchFilter filter,
+        bool withAttachments = false,
         CancellationToken cancellationToken = default);
 
     /// <summary>

src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailsQuery.cs

@@ -21,6 +21,12 @@ public record FetchEmailsQuery : IRequest<IEnumerable<ReceivedEmailContext>>
     /// Mail query used to filter and limit the emails retrieved.
     /// </summary>
     public MailSearchFilter Mail { get; init; } = new();
+
+    /// <summary>
+    /// When <see langword="true"/>, attachment data is included in the results; otherwise attachments are omitted.
+    /// Defaults to <see langword="false"/>.
+    /// </summary>
+    public bool WithAttachments { get; init; } = false;
 }
 
 public class FetchEmailsQueryHandler(
@@ -40,6 +46,7 @@ public class FetchEmailsQueryHandler(
         return await ImapService.FetchEmailsAsync(
             account,
             request.Mail,
+            request.WithAttachments,
             cancellationToken);
     }
 }

src/infrastructure/DigitalData.MessagingService.Infrastructure/Services/LimilabsImapEmailService.cs

@@ -27,6 +27,7 @@ public class LimilabsImapEmailService(
     public async Task<IEnumerable<ReceivedEmailContext>> FetchEmailsAsync(
         EmailAccountDto account,
         MailSearchFilter filter,
+        bool withAttachments = false,
         CancellationToken cancellationToken = default)
     {
         using var imap = new Imap();
@@ -38,7 +39,7 @@ public class LimilabsImapEmailService(
             List<ICriterion> criterions = [];
 
             if (filter.UnseenOnly)
-                criterions.Add((ICriterion)Flag.Unseen);
+                criterions.Add(Expression.HasFlag(Flag.Unseen));
 
             if (filter.SubjectContains is not null)
                 criterions.Add(Expression.Subject(filter.SubjectContains));
@@ -103,7 +104,7 @@ public class LimilabsImapEmailService(
                     if (filter.HasAttachments && mail.Attachments.Count == 0 && mail.Visuals.Count == 0)
                         continue;
 
-                    results.Add(MapToContext(uid, mail, flags));
+                    results.Add(MapToContext(uid, mail, flags, withAttachments));
                 }
                 catch (Exception ex)
                 {
@@ -179,32 +180,35 @@ public class LimilabsImapEmailService(
             await imap.SelectAsync(folder);
     }
 
-    private static ReceivedEmailContext MapToContext(long uid, IMail mail, List<Flag> flags)
+    private static ReceivedEmailContext MapToContext(long uid, IMail mail, List<Flag> flags, bool withAttachments = false)
     {
         var attachments = new List<EmailAttachmentContext>();
 
-        foreach (var att in mail.Attachments)
+        if (withAttachments)
         {
-            attachments.Add(new EmailAttachmentContext
+            foreach (var att in mail.Attachments)
             {
-                FileName    = att.FileName ?? "attachment",
-                Content     = att.Data,
-                ContentType = att.ContentType?.ToString() ?? "application/octet-stream",
-                IsInline    = false,
-                ContentId   = att.ContentId
-            });
-        }
+                attachments.Add(new EmailAttachmentContext
+                {
+                    FileName    = att.FileName ?? "attachment",
+                    Content     = att.Data,
+                    ContentType = att.ContentType?.ToString() ?? "application/octet-stream",
+                    IsInline    = false,
+                    ContentId   = att.ContentId
+                });
+            }
 
-        foreach (var vis in mail.Visuals)
-        {
-            attachments.Add(new EmailAttachmentContext
+            foreach (var vis in mail.Visuals)
             {
-                FileName    = vis.FileName ?? "inline",
-                Content     = vis.Data,
-                ContentType = vis.ContentType?.ToString() ?? "application/octet-stream",
-                IsInline    = true,
-                ContentId   = vis.ContentId
-            });
+                attachments.Add(new EmailAttachmentContext
+                {
+                    FileName    = vis.FileName ?? "inline",
+                    Content     = vis.Data,
+                    ContentType = vis.ContentType?.ToString() ?? "application/octet-stream",
+                    IsInline    = true,
+                    ContentId   = vis.ContentId
+                });
+            }
         }
 
         return new ReceivedEmailContext