From 051b4cf75cf12f6351c4e50190b6bd85b458ea18 Mon Sep 17 00:00:00 2001
From: cmyui <cmyuiosu@gmail.com>
Date: Sun, 19 May 2024 20:11:08 -0400
Subject: [PATCH] Some more intentional handling of some messaging error cases
 -- & docs

---
 constants/chatbotCommands.py         |  6 +++++-
 events/sendPrivateMessageEvent.py    |  5 ++++-
 events/sendPublicMessageEvent.py     |  5 ++++-
 handlers/apiChatbotMessageHandler.py | 11 +++++++----
 helpers/chatHelper.py                | 16 +++++++++++++++-
 5 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/constants/chatbotCommands.py b/constants/chatbotCommands.py
index 43e935c4..0068fdf4 100644
--- a/constants/chatbotCommands.py
+++ b/constants/chatbotCommands.py
@@ -1528,11 +1528,15 @@ async def postAnnouncement(fro: str, chan: str, message: list[str]) -> str:
     """Send a message to the #announce channel."""
     chatbot_token = await osuToken.get_token_by_user_id(CHATBOT_USER_ID)
     assert chatbot_token is not None
-    await chat.send_message(
+
+    messaging_error = await chat.send_message(
         sender_token_id=chatbot_token["token_id"],
         recipient_name="#announce",
         message=" ".join(message),
     )
+    if messaging_error is not None:
+        return "Failed to send announcement"
+
     return "Announcement successfully sent."
 
 
diff --git a/events/sendPrivateMessageEvent.py b/events/sendPrivateMessageEvent.py
index af7f6080..aa107693 100644
--- a/events/sendPrivateMessageEvent.py
+++ b/events/sendPrivateMessageEvent.py
@@ -11,11 +11,14 @@
 async def handle(userToken: Token, rawPacketData: bytes) -> None:
     # Send private message packet
     packetData = clientPackets.sendPrivateMessage(rawPacketData)
-    await chat.send_message(
+
+    messaging_error = await chat.send_message(
         sender_token_id=userToken["token_id"],
         recipient_name=packetData["to"],
         message=packetData["message"],
     )
+    if messaging_error is not None:
+        return None
 
     if glob.amplitude is not None:
         glob.amplitude.track(
diff --git a/events/sendPublicMessageEvent.py b/events/sendPublicMessageEvent.py
index 76fcc8a6..2484fbe1 100644
--- a/events/sendPublicMessageEvent.py
+++ b/events/sendPublicMessageEvent.py
@@ -11,11 +11,14 @@
 async def handle(userToken: Token, rawPacketData: bytes) -> None:
     # Send public message packet
     packetData = clientPackets.sendPublicMessage(rawPacketData)
-    await chat.send_message(
+
+    messaging_error = await chat.send_message(
         sender_token_id=userToken["token_id"],
         recipient_name=packetData["to"],
         message=packetData["message"],
     )
+    if messaging_error is not None:
+        return None
 
     if glob.amplitude is not None:
         glob.amplitude.track(
diff --git a/handlers/apiChatbotMessageHandler.py b/handlers/apiChatbotMessageHandler.py
index 1b409f14..1dedfd16 100644
--- a/handlers/apiChatbotMessageHandler.py
+++ b/handlers/apiChatbotMessageHandler.py
@@ -28,17 +28,20 @@ async def get(self) -> None:
             chatbot_token = await osuToken.get_token_by_user_id(CHATBOT_USER_ID)
             assert chatbot_token is not None
 
-            await chatHelper.send_message(
+            messaging_error = await chatHelper.send_message(
                 sender_token_id=chatbot_token["token_id"],
                 recipient_name=(
                     self.get_argument("to").encode().decode("utf-8", "replace")
                 ),
                 message=self.get_argument("msg").encode().decode("utf-8", "replace"),
             )
+            if messaging_error is None:
+                statusCode = 200
+                data["message"] = "ok"
+            else:
+                statusCode = 500
+                data["message"] = "Failed to send message"
 
-            # Status code and message
-            statusCode = 200
-            data["message"] = "ok"
         except exceptions.invalidArgumentsException:
             statusCode = 400
             data["message"] = "invalid parameters"
diff --git a/helpers/chatHelper.py b/helpers/chatHelper.py
index e7eb6358..0ba48417 100644
--- a/helpers/chatHelper.py
+++ b/helpers/chatHelper.py
@@ -690,7 +690,21 @@ async def send_message(
     sender_token_id: str,
     recipient_name: str,
     message: str,
-) -> SendMessageError | None:
+) -> None | SendMessageError:
+    """
+    A high level API for sending a message to a user or a channel.
+
+    Handles all the necessary checks and sends the message to the recipient, such as:
+    - Checking if the sender is connected to the server
+    - Checking if the sender is in restricted mode
+    - Checking if the sender is silenced
+    - Checking if the sender is using an acceptable client stream
+    - Checking if the message content is valid
+    Among other checks.
+
+    This will return `None` if the sending of the message was successful,
+    or a `SendMessageError` enum value if the sending of the message failed.
+    """
     sender_token = await osuToken.get_token(sender_token_id)
     if sender_token is None:
         logger.warning(