(20250116) Day-end push.

controllers_v2/message/mail/gmail.py

@@ -53,6 +53,8 @@ from models.api.message.mail.oauth import (
     OAuthMailAuthorizationRequestData
 )
 from models.message.mail.oauth import OAuthMailGetAuthorizationURLResponse, OAuthMailHandleCallbackResponse
+from models.message.mail.sync import MailSyncOneResult, MailSyncManyResults
+from models.message.mail.send import MailSendOneResult
 
 # Mail Client(s):
 from utils_v2.goog.controllers.gmail.gmail_client import AsyncGMailClient, SCOPES_GMAIL_MAIL_MANAGEMENT
@@ -60,9 +62,19 @@ from utils_v2.goog.controllers.gmail.gmail_client import AsyncGMailClient, SCOPE
 # To work with datatypes:
 from typing import List, Any
 
+# To work with MongoDB:
+from bson import ObjectId
+
+# To work with LLMs:
+from controllers.core.ai.llm import CoreLLMController
+from models.core.ai.llm import LLMInput, LLMOutput
+
 # To make HTTP requests:
 import httpx
 
+# To work with date and time:
+import datetime
+
 # For asynchronous activities:
 import asyncio
 
@@ -222,6 +234,17 @@ class GmailController(MailController):
             session_token: str = None
     ) -> OAuthMailHandleCallbackResponse:
 
+        """
+        To handle the authorization callback for the mail client. The user may grant or deny authorization.
+        :param sql_conn: The database connection to use to perform this task.
+        :param mongo_data_conn: The database connection to use to perform this task.
+        :param mail_client: The instance of the third-party mail client that will be used to get the URL.
+        :param request_url: The full callback URL invoked by the third-party client.
+        :param inbound_data: The data that came in with the request (API call).
+        :param session_token: The session token of the user. It is expected that this will be null in all cases.
+        :return: A structured response of the process of handling the mail callback.
+        """
+
         # Start by assuming failure:
         response = OAuthMailHandleCallbackResponse()
 
@@ -353,7 +376,40 @@ class GmailController(MailController):
     # To synchronize the mails on the third-party client's server and your server. You are effectively making a copy of
     # the mail on your database.
 
-    pass
+    async def sync_mails(
+            self,
+            sql_conn: AsyncMySQL,
+            mongo_data_conn: AsyncMongo,
+            mail_client: AsyncGMailClient,
+            token_key: ObjectId | str,
+            user_info: CoreUserInfoModel | None,
+            llm: CoreLLMController = None,
+            force_sync: bool = False,
+            start_date: datetime.datetime = None,
+            end_date: datetime.datetime = None,
+            max_count: int = 100,
+            session_token: str = None
+    ) -> MailSyncManyResults:
+
+        """
+        To fetch mails from the third-party client and store them to your database.
+        :param sql_conn: The database connection to use to perform this task.
+        :param mongo_data_conn: The database connection to use to perform this task.
+        :param mail_client: The instance of the third-party mail client that will be used to get the URL.
+        :param token_key: The key by which the auth-tokens to this account are identified.
+        :param user_info: The information about your user who is trying to use this system. Needed to note LLM token
+            usage in the process of mail summarization.
+        :param llm: The instance of the LLm that can be used to summarize the contents of the mail.
+        :param force_sync: To forcefully sync a mail even if it already exists in the database.
+        :param start_date: The starting date (inclusive) from which mails must be sync'd.
+        :param end_date: The ending date (inclusive) till which mails must be sync'd.
+        :param max_count: The max. no. of mails to sync.
+        :param session_token: TO identify a user session. This will be null if a cron script invokes this method, else
+            it will be received from the inputs of the API call.
+        :return:
+        """
+
+        pass
 
     # ┳┳┓  •┓  ┓ •  •
     # ┃┃┃┏┓┓┃  ┃ ┓┏╋┓┏┓┏┓
@@ -372,6 +428,16 @@ class GmailController(MailController):
 
     pass
 
+    # ┳┳┓  •┓  ┳┳   ┓   •
+    # ┃┃┃┏┓┓┃  ┃┃┏┓┏┫┏┓╋┓┏┓┏┓
+    # ┛ ┗┗┻┗┗  ┗┛┣┛┗┻┗┻┗┗┛┗┗┫
+    #            ┛          ┛
+
+    # We cannot modify the mails themselves, but we can set/unset tags on them for internal referencing and filtering.
+    # This will help the users organize their inboxes well.
+
+    pass
+
 
 #   *****************************************************************************************************************
 #  *****                                                                                                          ****