From 502ae5e07b7a8139d49660bf3beb3eee98e50a81 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Mon, 17 Aug 2026 15:04:57 +0200
Subject: [PATCH] feat(application): add IOAuth2AuthorizationService interface
 and UpdateAccountOAuth2RefreshTokenCommand handler

---
 .../Interfaces/IOAuth2AuthorizationService.cs | 35 +++++++++++++++++++
 .../UpdateAccountOAuth2RefreshTokenCommand.cs |  0
 2 files changed, 35 insertions(+)
 create mode 100644 src/core/DigitalData.MessagingService.Application/Common/Interfaces/IOAuth2AuthorizationService.cs
 create mode 100644 src/core/DigitalData.MessagingService.Application/EmailAccounts/Commands/UpdateAccountOAuth2RefreshTokenCommand.cs

diff --git a/src/core/DigitalData.MessagingService.Application/Common/Interfaces/IOAuth2AuthorizationService.cs b/src/core/DigitalData.MessagingService.Application/Common/Interfaces/IOAuth2AuthorizationService.cs
new file mode 100644
index 0000000..1e9f6cc
--- /dev/null
+++ b/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
diff --git a/src/core/DigitalData.MessagingService.Application/EmailAccounts/Commands/UpdateAccountOAuth2RefreshTokenCommand.cs b/src/core/DigitalData.MessagingService.Application/EmailAccounts/Commands/UpdateAccountOAuth2RefreshTokenCommand.cs
new file mode 100644
index 0000000..e69de29