feat(application): add IOAuth2AuthorizationService interface and UpdateAccountOAuth2RefreshTokenCommand handler

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

@@ -0,0 +1,35 @@
+#if NET
+using DigitalData.MessagingService.Domain.Entities;
+
+namespace DigitalData.MessagingService.Application.Common.Interfaces;
+
+/// <summary>
+/// Manages the OAuth2 authorization code flow for providers that require
+/// user-delegated access (e.g. Google). Generates authorization URLs and
+/// exchanges authorization codes for refresh tokens.
+/// </summary>
+public interface IOAuth2AuthorizationService
+{
+    /// <summary>
+    /// Builds the authorization URL to redirect the user to for consent.
+    /// </summary>
+    /// <param name="account">The email account to authorize.</param>
+    /// <param name="redirectUri">The callback URI registered with the OAuth2 provider.</param>
+    /// <returns>The full authorization URL.</returns>
+    string GetAuthorizationUrl(EmailAccount account, string redirectUri);
+
+    /// <summary>
+    /// Exchanges an authorization code for tokens and returns the refresh token.
+    /// </summary>
+    /// <param name="account">The email account being authorized.</param>
+    /// <param name="code">The authorization code received from the provider callback.</param>
+    /// <param name="redirectUri">The same redirect URI used in <see cref="GetAuthorizationUrl"/>.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The refresh token to be stored on the account.</returns>
+    Task<string> ExchangeCodeForRefreshTokenAsync(
+        EmailAccount account,
+        string code,
+        string redirectUri,
+        CancellationToken cancellationToken = default);
+}
+#endif