Some more intentional handling of some messaging error cases -- & docs

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."
 
 

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(

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(

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"

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(