universal-mcp-applications 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

universal_mcp/applications/whatsapp/app.py

@@ -58,7 +58,9 @@ class WhatsappApp(BaseApplication):
         self._api_key: str | None = None
 
     def get_api_key(self) -> str:
-        """Get the AgentR API key to use as for WhatsApp authentication."""
+        """
+        Extracts the 'X-API-KEY' from the AgentR integration client's headers to authenticate WhatsApp API requests. A ValueError is raised if the integration is missing or the key cannot be found, ensuring all operations are properly authorized before execution.
+        """
         if not self.integration:
             raise ValueError("No integration available to get API key from")
         
@@ -75,7 +77,9 @@ class WhatsappApp(BaseApplication):
 
     @property
     def api_key(self) -> str:
-        """Gets the API key from the integration, triggering authentication if needed."""
+        """
+        A cached property that retrieves the API key from the AgentrIntegration. It calls the `get_api_key` method on its first access and stores the result for efficient subsequent lookups, ensuring the integration object is queried only once.
+        """
         if self._api_key:
             return self._api_key
         self._api_key = self.get_api_key()
@@ -155,17 +159,17 @@ class WhatsappApp(BaseApplication):
         query: str,
     ) -> list[dict[str, Any]]:
         """
-        Search WhatsApp contacts by name or phone number.
-
+        Searches for WhatsApp contacts by name or phone number. This function takes a query string, handles user authentication, and calls the underlying API to find and return a list of matching contacts. It serves as the primary method to look up contact information within the application.
+        
         Args:
             query (string): Search term to match against contact names or phone numbers
-
+        
         Returns:
             List[Dict[str, Any]]: Retrieved collection
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.contacts, important
         """
@@ -179,7 +183,7 @@ class WhatsappApp(BaseApplication):
         contacts = whatsapp_search_contacts(query, user_id)
         return contacts
 
-    def list_messages(
+    def search_messages(
         self,
         after: str | None = None,
         before: str | None = None,
@@ -193,8 +197,8 @@ class WhatsappApp(BaseApplication):
         context_after: int = 1,
     ) -> list[dict[str, Any]]:
         """
-        Get WhatsApp messages matching specified criteria with optional context.
-
+        Searches for and retrieves a paginated list of WhatsApp messages using various filters like date, sender, chat, or content query. It can optionally include surrounding contextual messages for each result, unlike `get_message_context` which targets a single message ID.
+        
         Args:
             after (string): Optional ISO-8601 formatted string to only return messages after this date
             before (string): Optional ISO-8601 formatted string to only return messages before this date
@@ -206,13 +210,13 @@ class WhatsappApp(BaseApplication):
             include_context (boolean): Whether to include messages before and after matches (default True)
             context_before (integer): Number of messages to include before each match (default 1)
             context_after (integer): Number of messages to include after each match (default 1)
-
+        
         Returns:
             List[Dict[str, Any]]: Retrieved collection
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.messages, important
         """
@@ -235,7 +239,7 @@ class WhatsappApp(BaseApplication):
         )
         return messages
 
-    def list_chats(
+    def search_chats(
         self,
         query: str | None = None,
         limit: int = 20,
@@ -244,21 +248,21 @@ class WhatsappApp(BaseApplication):
         sort_by: str = "last_active",
     ) -> list[dict[str, Any]]:
         """
-        Get WhatsApp chats matching specified criteria.
-
+        Retrieves a paginated list of WhatsApp chats, allowing filtering by a search query and sorting by activity or name. Unlike `get_chat`, which fetches a single known chat, this function provides broad search and discovery capabilities across multiple user conversations.
+        
         Args:
             query (string): Optional search term to filter chats by name or JID
             limit (integer): Maximum number of chats to return (default 20)
             page (integer): Page number for pagination (default 0)
             include_last_message (boolean): Whether to include the last message in each chat (default True)
             sort_by (string): Field to sort results by, either "last_active" or "name" (default "last_active")
-
+        
         Returns:
             List[Dict[str, Any]]: Retrieved collection
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.chats, important
         """
@@ -276,24 +280,24 @@ class WhatsappApp(BaseApplication):
         )
         return chats
 
-    def get_chat(
+    def get_chat_by_jid(
         self,
         chat_jid: str,
         include_last_message: bool = True,
     ) -> dict[str, Any]:
         """
-        Get WhatsApp chat metadata by JID.
-
+        Retrieves metadata for a specific WhatsApp chat (direct or group) using its unique JID. It can optionally include the most recent message. This precise JID-based lookup distinguishes it from `get_direct_chat_by_contact`, which uses a phone number, and `list_chats`, which performs a broader search.
+        
         Args:
             chat_jid (string): The JID of the chat to retrieve
             include_last_message (boolean): Whether to include the last message (default True)
-
+        
         Returns:
             Dict[str, Any]: Retrieved chat metadata
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.chat, important
         """
@@ -307,22 +311,22 @@ class WhatsappApp(BaseApplication):
         chat = whatsapp_get_chat(chat_jid, include_last_message, user_id)
         return chat
 
-    def get_direct_chat_by_contact(
+    def get_direct_chat_by_phone_number(
         self,
         sender_phone_number: str,
     ) -> dict[str, Any]:
         """
-        Get WhatsApp chat metadata by sender phone number.
-
+        Retrieves metadata for a direct (one-on-one) WhatsApp chat using a contact's phone number. Unlike `get_chat` which requires a JID, this provides a simpler way to find direct conversations. Returns a dictionary containing the chat's details, such as its JID and name.
+        
         Args:
             sender_phone_number (string): The phone number to search for
-
+        
         Returns:
             Dict[str, Any]: Retrieved chat metadata
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.chat, important
         """
@@ -336,26 +340,26 @@ class WhatsappApp(BaseApplication):
         chat = whatsapp_get_direct_chat_by_contact(sender_phone_number, user_id)
         return chat
 
-    def get_contact_chats(
+    def list_chats_by_contact_jid(
         self,
         jid: str,
         limit: int = 20,
         page: int = 0,
     ) -> list[dict[str, Any]]:
         """
-        Get all WhatsApp chats involving the contact.
-
+        Retrieves a paginated list of all WhatsApp chats, including direct messages and groups, that a specific contact participates in. The contact is identified by their unique JID. This differs from `get_direct_chat_by_contact` which only finds one-on-one chats.
+        
         Args:
             jid (string): The contact's JID to search for
             limit (integer): Maximum number of chats to return (default 20)
             page (integer): Page number for pagination (default 0)
-
+        
         Returns:
             List[Dict[str, Any]]: Retrieved collection
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.contact_chats, important
         """
@@ -369,22 +373,22 @@ class WhatsappApp(BaseApplication):
         chats = whatsapp_get_contact_chats(jid, limit, page, user_id)
         return chats
 
-    def get_last_interaction(
+    def get_last_message_by_jid(
         self,
         jid: str,
     ) -> str:
         """
-        Get most recent WhatsApp message involving the contact.
-
+        Retrieves the content of the most recent message involving a specific contact, identified by their JID. It authenticates the user and returns the message directly as a string, offering a quick way to view the last communication without fetching full message objects or chat histories.
+        
         Args:
             jid (string): The JID of the contact to search for
-
+        
         Returns:
             string: Retrieved message
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.interaction, important
         """
@@ -405,19 +409,19 @@ class WhatsappApp(BaseApplication):
         after: int = 5,
     ) -> dict[str, Any]:
         """
-        Get context around a specific WhatsApp message.
-
+        Fetches the conversational context surrounding a specific WhatsApp message ID. It retrieves a configurable number of messages immediately preceding and following the target message. This provides a focused view of a dialogue, unlike `list_messages` which performs broader, filter-based searches.
+        
         Args:
             message_id (string): The ID of the message to get context for
             before (integer): Number of messages to include before the target message (default 5)
             after (integer): Number of messages to include after the target message (default 5)
-
+        
         Returns:
             Dict[str, Any]: Retrieved message context
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.message_context, important
         """
@@ -431,25 +435,25 @@ class WhatsappApp(BaseApplication):
         context = whatsapp_get_message_context(message_id, before, after, user_id)
         return context
 
-    def send_message(
+    def send_text_message(
         self,
         recipient: str,
         message: str,
     ) -> dict[str, Any]:
         """
-        Send a WhatsApp message to a person or group. For group chats use the JID.
-
+        Authenticates the user and sends a text message to a specified WhatsApp recipient. The recipient can be an individual (via phone number) or a group (via JID). It returns a dictionary indicating the operation's success status and a corresponding message.
+        
         Args:
             recipient (string): The recipient - either a phone number with country code but no + or other symbols,
                              or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
             message (string): The message text to send
-
+        
         Returns:
             Dict[str, Any]: A dictionary containing success status and a status message
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.send_message, important
         """
@@ -469,25 +473,25 @@ class WhatsappApp(BaseApplication):
             "message": status_message,
         }
 
-    def send_file(
+    def send_attachment(
         self,
         recipient: str,
         media_path: str,
     ) -> dict[str, Any]:
         """
-        Send a file such as a picture, raw audio, video or document via WhatsApp to the specified recipient. For group messages use the JID.
-
+        Sends a media file (image, video, document, raw audio) as a standard attachment to a WhatsApp contact or group using their phone number or JID. Unlike `send_audio_message`, which creates a playable voice note, this function handles general file transfers. Returns a success status dictionary.
+        
         Args:
             recipient (string): The recipient - either a phone number with country code but no + or other symbols,
                              or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
             media_path (string): The absolute path to the media file to send (image, video, document)
-
+        
         Returns:
             Dict[str, Any]: A dictionary containing success status and a status message
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.send_file, important
         """
@@ -507,25 +511,25 @@ class WhatsappApp(BaseApplication):
             "message": status_message,
         }
 
-    def send_audio_message(
+    def send_voice_message(
         self,
         recipient: str,
         media_path: str,
     ) -> dict[str, Any]:
         """
-        Send any audio file as a WhatsApp audio message to the specified recipient. For group messages use the JID. If it errors due to ffmpeg not being installed, use send_file instead.
-
+        Sends a local audio file as a playable WhatsApp voice message, converting it to the required format. Unlike `send_file` which sends audio as a document attachment, this function formats the audio as a voice note. It can be sent to an individual contact or a group chat.
+        
         Args:
             recipient (string): The recipient - either a phone number with country code but no + or other symbols,
                              or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
             media_path (string): The absolute path to the audio file to send (will be converted to Opus .ogg if it's not a .ogg file)
-
+        
         Returns:
             Dict[str, Any]: A dictionary containing success status and a status message
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.send_audio_message, important
         """
@@ -546,24 +550,24 @@ class WhatsappApp(BaseApplication):
             "message": status_message,
         }
 
-    def download_media(
+    def download_media_from_message(
         self,
         message_id: str,
         chat_jid: str,
     ) -> dict[str, Any]:
         """
-        Download media from a WhatsApp message and get the local file path.
-
+        Downloads media from a specific WhatsApp message, identified by its ID and chat JID. It saves the content to a local file and returns the file's path upon success. The function automatically handles user authentication before initiating the download.
+        
         Args:
             message_id (string): The ID of the message containing the media
             chat_jid (string): The JID of the chat containing the message
-
+        
         Returns:
             Dict[str, Any]: A dictionary containing success status, a status message, and the file path if successful
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
-
+        
         Tags:
             whatsapp.download_media, important
         """
@@ -596,15 +600,15 @@ class WhatsappApp(BaseApplication):
         """
         return [
             self.search_contacts,
-            self.list_messages,
-            self.list_chats,
-            self.get_chat,
-            self.get_direct_chat_by_contact,
-            self.get_contact_chats,
-            self.get_last_interaction,
+            self.search_messages,
+            self.search_chats,
+            self.get_chat_by_jid,
+            self.get_direct_chat_by_phone_number,
+            self.list_chats_by_contact_jid,
+            self.get_last_message_by_jid,
             self.get_message_context,
-            self.send_message,
-            self.send_file,
-            self.send_audio_message,
-            self.download_media,
+            self.send_text_message,
+            self.send_attachment,
+            self.send_voice_message,
+            self.download_media_from_message,
         ]