jobtrackingapp/JobTrackerApi/Services/EmailProviders/IEmailProvider.cs

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);

        Task<EmailDeliveryResult> SendAsync(string ownerUserId, EmailDeliveryRequest request, CancellationToken cancellationToken);
    }

    public sealed record EmailConnectionInfo(string ProviderKey, string Address, bool CanSend = false);

    public sealed record EmailDeliveryRequest(string To, string Subject, string BodyText, string? ThreadId = null);
    public sealed record EmailDeliveryResult(string? ExternalMessageId, string? ExternalThreadId);

    public sealed class EmailProviderDeliveryException(string category, bool uncertain, string message, Exception? innerException = null)
        : Exception(message, innerException)
    {
        public string Category { get; } = category;
        public bool Uncertain { get; } = uncertain;
    }

    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;
    }
}