feat(email): introduce IEmailProvider seam + GmailProvider adapter

First slice toward multi-provider email (Gmail + Microsoft Graph + IMAP + manual/free-text, per docs/remaster/PRODUCT_DIRECTION.md). Adds a provider- neutral contract (search / list-thread / get-message / get-connection) with neutral DTOs, a registry to resolve providers by key, and a GmailProvider that adapts the existing IGmailOAuthService to it. No behaviour change: the seam is registered in DI but not yet consumed. Follow-up slices migrate GmailController's read paths onto IEmailProvider (folding in the N+1 fixes) and add MicrosoftGraphProvider / ImapProvider / a manual provider. Build clean; backend suite 135/135 green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-05 20:42:46 +02:00
parent 919f61dde6
commit c53d7978bb
3 changed files with 136 additions and 0 deletions
@@ -0,0 +1,63 @@
+using JobTrackerApi.Services;
+
+namespace JobTrackerApi.Services.EmailProviders
+{
+    /// <summary>
+    /// Gmail implementation of <see cref="IEmailProvider"/>. Adapts the existing
+    /// <see cref="IGmailOAuthService"/> (Gmail REST client) to the provider-neutral contract,
+    /// mapping Gmail DTOs to the neutral shapes.
+    /// </summary>
+    public sealed class GmailProvider : IEmailProvider
+    {
+        private readonly IGmailOAuthService _gmail;
+
+        public GmailProvider(IGmailOAuthService gmail)
+        {
+            _gmail = gmail;
+        }
+
+        public string ProviderKey => "gmail";
+
+        public async Task<EmailConnectionInfo?> GetConnectionAsync(string ownerUserId, CancellationToken cancellationToken)
+        {
+            var connection = await _gmail.GetConnectionAsync(ownerUserId, cancellationToken);
+            return connection is null ? null : new EmailConnectionInfo("gmail", connection.GmailAddress ?? "");
+        }
+
+        public async Task<IReadOnlyList<EmailMessageSummary>> SearchAsync(string ownerUserId, string? query, int maxResults, CancellationToken cancellationToken)
+        {
+            var messages = await _gmail.ListMessagesAsync(ownerUserId, query, maxResults, cancellationToken);
+            return messages.Select(ToSummary).ToList();
+        }
+
+        public async Task<IReadOnlyList<EmailMessageSummary>> ListThreadMessagesAsync(string ownerUserId, string threadId, CancellationToken cancellationToken)
+        {
+            var messages = await _gmail.ListThreadMessagesAsync(ownerUserId, threadId, cancellationToken);
+            return messages.Select(ToSummary).ToList();
+        }
+
+        public async Task<EmailMessageDetail> GetMessageAsync(string ownerUserId, string messageId, CancellationToken cancellationToken)
+        {
+            var detail = await _gmail.GetMessageAsync(ownerUserId, messageId, cancellationToken);
+            var attachments = detail.Attachments
+                .Select(a => new EmailAttachmentRef(a.FileName, a.MimeType, a.SizeBytes, a.GmailAttachmentId, a.Inline))
+                .ToList();
+
+            return new EmailMessageDetail(
+                detail.Id,
+                detail.ThreadId,
+                detail.Subject,
+                detail.From,
+                detail.To,
+                detail.Date,
+                detail.Snippet,
+                detail.BodyText,
+                detail.BodyHtml,
+                detail.Labels,
+                attachments);
+        }
+
+        private static EmailMessageSummary ToSummary(GmailMessageSummary m)
+            => new(m.Id, m.ThreadId, m.Subject, m.From, m.To, m.Date, m.Snippet);
+    }
+}
@@ -0,0 +1,69 @@
+namespace JobTrackerApi.Services.EmailProviders
+{
+    /// <summary>
+    /// Provider-neutral email operations so job correspondence can be sourced from Gmail,
+    /// Microsoft Graph, generic IMAP, or manual/free-text entry behind a single seam.
+    /// See docs/remaster/PRODUCT_DIRECTION.md (multi-provider email). Gmail is the first
+    /// implementation (<see cref="GmailProvider"/>); the controller migration and additional
+    /// providers land in follow-up slices.
+    /// </summary>
+    public interface IEmailProvider
+    {
+        /// <summary>Stable key: "gmail" | "microsoft" | "imap" | "manual".</summary>
+        string ProviderKey { get; }
+
+        /// <summary>The user's active connection for this provider, or null if not connected.</summary>
+        Task<EmailConnectionInfo?> GetConnectionAsync(string ownerUserId, CancellationToken cancellationToken);
+
+        /// <summary>Search the user's mailbox. <paramref name="query"/> is provider-specific syntax.</summary>
+        Task<IReadOnlyList<EmailMessageSummary>> SearchAsync(string ownerUserId, string? query, int maxResults, CancellationToken cancellationToken);
+
+        /// <summary>All messages in a thread/conversation.</summary>
+        Task<IReadOnlyList<EmailMessageSummary>> ListThreadMessagesAsync(string ownerUserId, string threadId, CancellationToken cancellationToken);
+
+        /// <summary>Full message content (body + attachments metadata).</summary>
+        Task<EmailMessageDetail> GetMessageAsync(string ownerUserId, string messageId, CancellationToken cancellationToken);
+    }
+
+    public sealed record EmailConnectionInfo(string ProviderKey, string Address);
+
+    public sealed record EmailMessageSummary(string Id, string ThreadId, string Subject, string From, string To, DateTimeOffset? Date, string Snippet);
+
+    public sealed record EmailAttachmentRef(string? FileName, string? MimeType, long? SizeBytes, string? ExternalAttachmentId, bool Inline);
+
+    public sealed record EmailMessageDetail(
+        string Id,
+        string ThreadId,
+        string Subject,
+        string From,
+        string To,
+        DateTimeOffset? Date,
+        string Snippet,
+        string BodyText,
+        string? BodyHtml,
+        IReadOnlyList<string> Labels,
+        IReadOnlyList<EmailAttachmentRef> Attachments);
+
+    /// <summary>Resolves a registered <see cref="IEmailProvider"/> by its key.</summary>
+    public interface IEmailProviderRegistry
+    {
+        IReadOnlyList<IEmailProvider> All { get; }
+        IEmailProvider? Get(string? providerKey);
+    }
+
+    public sealed class EmailProviderRegistry : IEmailProviderRegistry
+    {
+        private readonly Dictionary<string, IEmailProvider> _byKey;
+
+        public EmailProviderRegistry(IEnumerable<IEmailProvider> providers)
+        {
+            All = providers.ToList();
+            _byKey = All.ToDictionary(p => p.ProviderKey, StringComparer.OrdinalIgnoreCase);
+        }
+
+        public IReadOnlyList<IEmailProvider> All { get; }
+
+        public IEmailProvider? Get(string? providerKey)
+            => !string.IsNullOrWhiteSpace(providerKey) && _byKey.TryGetValue(providerKey, out var p) ? p : null;
+    }
+}