(20241219) SMS module fully re-organized.

models/api/mail/send.py

@@ -36,7 +36,7 @@ sys.path.append(".")
 sys.path.append("..")
 
 # For making data behaviour_models:
-from pydantic import BaseModel, Field, field_validator, PastDatetime
+from pydantic import BaseModel, Field, field_validator, PastDatetime, EmailStr
 from typing import Optional, Literal, List
 
 # My utils:
@@ -103,9 +103,33 @@ class MailSendRequestHeaders(BaseModel):
 # ---------------------------------------------------------------------------------------------------------------------
 
 
+class MailSendInlineFiles(BaseModel):
+
+    key: str = Field(
+        description = "the key in the form data under which the file has been sent",
+        frozen = True
+    )
+
+    cid: str = Field(
+        description = "the content id to assign to the file",
+        frozen = True
+    )
+
+    # ┏┓    ┏•
+    # ┃ ┏┓┏┓╋┓┏┓
+    # ┗┛┗┛┛┗┛┗┗┫
+    #          ┛
+
+    class Config:
+        extra = "forbid"
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+
+
 class MailSendRequestData(BaseModel):
 
-    tokenKey: str = Field(
+    tokenKey: ObjectId = Field(
         description = "the account identifier (Mongo ObjectId)",
         frozen = True
     )
@@ -115,11 +139,34 @@ class MailSendRequestData(BaseModel):
         frozen = True
     )
 
-    inlineKeys: List[str] = Field(
+    to: List[EmailStr] = Field(
+        description = "the recipient of your mail",
+        # default = None,
+        # validate_default = True,
+        frozen = True
+    )
+
+    cc: List[EmailStr] = Field(
+        description = "the list of ids to add as cc",
+        default = None,
+        validate_default = True,
+        frozen = True
+    )
+
+    bcc: List[EmailStr] = Field(
+        description = "the list of ids to add as bcc",
+        default = None,
+        validate_default = True,
+        frozen = True
+    )
+
+    inlineFiles: List[MailSendInlineFiles] = Field(
         description = (
             "when sending files, this will be a list of keys whose "
             "associated files will be treated as inline files"
         ),
+        default = None,
+        validate_default = True,
         frozen = True
     )
 
@@ -142,13 +189,35 @@ class MailSendRequestData(BaseModel):
         except: pass
         return value
 
-    @field_validator("inlineKeys", mode = "before")
+    @field_validator("inlineFiles", mode = "before")
     def parse_json(cls, value):
-        try:
-            value = json.from_string(value)
-            if not isinstance(value, list): raise ValueError("'inlineKeys' needs to be an array")
-        except Exception as exception:
-            raise ValueError("'inlineKeys' could not be parsed")
+
+        # If we get a null value or an empty string:
+        if value is None: return []
+        if isinstance(value, str):
+            if not value.strip(): return []
+
+        # If we get a properly populated string:
+        try: value = json.from_string(value)
+        except: pass
+
+        # Done here:
+        return value
+
+    @field_validator("to", "cc", "bcc", mode = "before")
+    def parse_recipients(cls, value):
+
+        # If we get a null value or an empty string:
+        if value is None: return []
+        if isinstance(value, str):
+            if not value.strip(): return []
+
+        # If we get a properly populated string:
+        try: value = json.from_string(value)
+        except: value = [value.strip()]
+
+        # Done here:
+        return value
 
 
 #   *****************************************************************************************************************

models/api/mail/sync.py

@@ -219,6 +219,35 @@ class MailSyncManyResults(BaseModel):
         extra = "forbid"
 
 
+# ---------------------------------------------------------------------------------------------------------------------
+
+
+class MailSendOneResult(BaseModel):
+
+    success: bool = Field(
+        description = "whether, or not, the mail was successfully sent",
+        default = False
+    )
+
+    message: str | None = Field(
+        description = "a brief message to summarize the result of the process",
+        default = None
+    )
+
+    mailMessage: CoreMessageModel | None = Field(
+        description = "the actual data of the mail; can be null in a successful process if the mail is already sent",
+        default = None
+    )
+
+    # ┏┓    ┏•
+    # ┃ ┏┓┏┓╋┓┏┓
+    # ┗┛┗┛┛┗┛┗┗┫
+    #          ┛
+
+    class Config:
+        extra = "forbid"
+
+
 #   *****************************************************************************************************************
 #  *****                                                                                                          ****
 # ***                                               MAIN PROGRAM                                                    ***

models/api/sms/list.py

@@ -75,7 +75,7 @@ REGEX_SESSION_TOKEN = r"^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]
 #   *****************************************************************************************************************
 
 
-class MailListRequestHeaders(BaseModel):
+class SMSListRequestHeaders(BaseModel):
 
     sessionToken: str = Field(
         description = "the session token of the user who is requesting the service",
@@ -99,7 +99,7 @@ class MailListRequestHeaders(BaseModel):
 # ---------------------------------------------------------------------------------------------------------------------
 
 
-class MailListRequestData(BaseModel):
+class SMSListRequestData(BaseModel):
 
     tokenKeys: str | List[str] = Field(
         description = "the token identifier(s) that tell you which auth-tokens were used for fetching those messages",

models/api/sms/send.py

@@ -43,7 +43,7 @@ from typing import Optional, Literal, Union, List, Any
 from utils_v2.string import regex
 from utils_v2.date_time import date_time
 
-# Data models:
+# Models:
 from models.core.message import CoreMessageModel
 from utils_v2.sms.models.sms_message import SentSMSMessageModel
 

models/api/sms/tags.py

@@ -6,11 +6,11 @@
 
     DATE:
 
-        Friday, 13th Dec., 2024.
+        Thursday, 19th Dec., 2024.
 
     OBJECTIVE:
 
-        To provide a structure to work with the tags on mail messages.
+        To provide a structure to work with the tags on SMS messages.
 
     REFERENCES:
 
@@ -75,7 +75,7 @@ REGEX_SESSION_TOKEN = r"^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]
 #   *****************************************************************************************************************
 
 
-class MailUpdateTagsRequestHeaders(BaseModel):
+class SMSUpdateTagsRequestHeaders(BaseModel):
 
     sessionToken: str = Field(
         description = "the session token of the user who is requesting the service",
@@ -99,7 +99,7 @@ class MailUpdateTagsRequestHeaders(BaseModel):
 # ---------------------------------------------------------------------------------------------------------------------
 
 
-class MailUpdateTagsRequestData(BaseModel):
+class SMSUpdateTagsRequestData(BaseModel):
 
     messageId: str = Field(
         description = "the mail identifier (Mongo ObjectId) of the document that holds the mail",

models/core/message.py

@@ -82,11 +82,12 @@ import datetime
 
 class CoreMessageModel(BaseModel):
 
-    messageId: ObjectId = Field(
+    messageId: ObjectId | None = Field(
         description = "the id of the document in mongodb that holds this information",
         frozen = True,
         default = None,
-        alias = "_id"
+        alias = "_id",
+        exclude = True
     )
 
     ts: AwareDatetime = Field(
@@ -291,7 +292,7 @@ if __name__ == "__main__":
         },
         sender = "Polki",
         chat = "T6 Cats",
-        preview = "Hi, there! How do you do?"
+        snippet = "Hi, there! How do you do?"
     )
 
     print("MESSAGE MODEL:", json.to_string(message.model_dump(), default = str))