prepare for messages release

http_client/src/vonage_http_client/http_client.py

@@ -225,8 +225,6 @@ def _parse_response(self, response: Response) -> Union[dict, None]:
         )
         self._last_response = response
         if 200 <= response.status_code < 300:
-            if response.status_code == 204:
-                return None
             try:
                 return response.json()
             except JSONDecodeError:

messages/README.md

@@ -6,5 +6,72 @@ This package contains the code to use [Vonage's Messages API](https://developer.
 
 It is recommended to use this as part of the main `vonage` package. The examples below assume you've created an instance of the `vonage.Vonage` class called `vonage_client`.
 
+### How to Construct a Message
+
+In order to send a message, you must construct a message object of the correct type. These are all found under `vonage_messages.models`.
+
+```python
+from vonage_messages.models import Sms
+
+message = Sms(
+    from_='Vonage APIs',
+    to='1234567890',
+    text='This is a test message sent from the Vonage Python SDK',
+)
+```
+
+This message can now be sent with
+
+```python
+vonage_client.messages.send(message)
+```
+
+All possible message types from every message channel have their own message model. They are named following this rule: {Channel}{MessageType}, e.g. `Sms`, `MmsImage`, `MessengerAudio`, `WhatsappSticker`, `ViberVideo`, etc.
+
+The different message models are listed at the bottom of the page.
+
+Some message types have submodels with additional fields. In this case, import the submodels as well and use them to construct the overall options.
+
+e.g.
+
+```python
+from vonage_messages import MessengerImage, MessengerOptions, MessengerResource
+
+messenger = MessengerImage(
+    to='1234567890',
+    from_='1234567890',
+    image=MessengerResource(url='https://example.com/image.jpg'),
+    messenger=MessengerOptions(category='message_tag', tag='invalid_tag'),
+)
+```
+
 ### Send a message
 
+To send a message, access the `Messages.send` method via the main Vonage object, passing in an instance of a subclass of `BaseMessage` like this:
+
+```python
+from vonage import Auth, Vonage
+from vonage_messages.models import Sms
+
+vonage_client = Vonage(Auth(application_id='my-application-id', private_key='my-private-key'))
+
+message = Sms(
+    from_='Vonage APIs',
+    to='1234567890',
+    text='This is a test message sent from the Vonage Python SDK',
+)
+
+vonage_client.messages.send(message)
+```
+
+## Message Models
+
+To send a message, instantiate a message model of the correct type as described above. This is a list of message models that can be used:
+
+```
+Sms
+MmsImage, MmsVcard, MmsAudio, MmsVideo
+WhatsappText, WhatsappImage, WhatsappAudio, WhatsappVideo, WhatsappFile, WhatsappTemplate, WhatsappSticker, WhatsappCustom
+MessengerText, MessengerImage, MessengerAudio, MessengerVideo, MessengerFile
+ViberText, ViberImage, ViberVideo, ViberFile
+```

messages/src/vonage_messages/__init__.py

@@ -1,12 +1,5 @@
 from . import models
-from .enums import ChannelType, EncodingType, MessageType, WebhookVersion
 from .messages import Messages
+from .responses import SendMessageResponse
 
-__all__ = [
-    'models',
-    'Messages',
-    'ChannelType',
-    'MessageType',
-    'WebhookVersion',
-    'EncodingType',
-]
+__all__ = ['models', 'Messages', 'SendMessageResponse']

messages/src/vonage_messages/messages.py

@@ -2,7 +2,7 @@
 from vonage_http_client.http_client import HttpClient
 
 from .models import BaseMessage
-from .responses import MessageUuid
+from .responses import SendMessageResponse
 
 
 class Messages:
@@ -18,19 +18,20 @@ def __init__(self, http_client: HttpClient) -> None:
         self._http_client = http_client
 
     @validate_call
-    def send(self, message: BaseMessage) -> MessageUuid:
+    def send(self, message: BaseMessage) -> SendMessageResponse:
         """Send a message using Vonage's Messages API.
 
         Args:
-            message (BaseMessage): The message to be sent.
+            message (BaseMessage): The message to be sent as a Pydantic model.
+                Use the provided models (in `vonage_messages.models`) to create messages and pass them in to this method.
 
         Returns:
-            MessageUuid: The unique identifier of the sent message.
+            SendMessageResponse: Response model containing the unique identifier of the sent message.
+                Access the identifier with the `message_uuid` attribute.
         """
         response = self._http_client.post(
             self._http_client.api_host,
             '/v1/messages',
-            message.model_dump(by_alias=True, exclude_none=True),
+            message.model_dump(by_alias=True, exclude_none=True) or message,
         )
-
-        return MessageUuid(**response)
+        return SendMessageResponse(**response)

messages/src/vonage_messages/models/__init__.py

@@ -1,4 +1,5 @@
 from .base_message import BaseMessage
+from .enums import ChannelType, EncodingType, MessageType, WebhookVersion
 from .messenger import (
     MessengerAudio,
     MessengerFile,
@@ -46,6 +47,9 @@
 
 __all__ = [
     'BaseMessage',
+    'ChannelType',
+    'EncodingType',
+    'MessageType',
     'MessengerAudio',
     'MessengerFile',
     'MessengerImage',
@@ -72,6 +76,7 @@
     'ViberVideo',
     'ViberVideoOptions',
     'ViberVideoResource',
+    'WebhookVersion',
     'WhatsappAudio',
     'WhatsappAudioResource',
     'WhatsappContext',

messages/src/vonage_messages/models/base_message.py

@@ -3,7 +3,7 @@
 from pydantic import BaseModel, Field
 from vonage_utils.types.phone_number import PhoneNumber
 
-from ..enums import WebhookVersion
+from .enums import WebhookVersion
 
 
 class BaseMessage(BaseModel):

messages/src/vonage_messages/models/messenger.py

@@ -2,8 +2,8 @@
 
 from pydantic import BaseModel, Field, model_validator
 
-from ..enums import ChannelType, MessageType
 from .base_message import BaseMessage
+from .enums import ChannelType, MessageType
 
 
 class MessengerResource(BaseModel):

messages/src/vonage_messages/models/mms.py

@@ -3,8 +3,8 @@
 from pydantic import BaseModel, Field
 from vonage_utils.types.phone_number import PhoneNumber
 
-from ..enums import ChannelType, MessageType
 from .base_message import BaseMessage
+from .enums import ChannelType, MessageType
 
 
 class MmsResource(BaseModel):

messages/src/vonage_messages/models/sms.py

@@ -3,8 +3,8 @@
 from pydantic import BaseModel, Field
 from vonage_utils.types.phone_number import PhoneNumber
 
-from ..enums import ChannelType, EncodingType, MessageType
 from .base_message import BaseMessage
+from .enums import ChannelType, EncodingType, MessageType
 
 
 class SmsOptions(BaseModel):

messages/src/vonage_messages/models/viber.py

@@ -2,8 +2,8 @@
 
 from pydantic import BaseModel, Field, field_validator
 
-from ..enums import ChannelType, MessageType
 from .base_message import BaseMessage
+from .enums import ChannelType, MessageType
 
 
 class ViberAction(BaseModel):

messages/src/vonage_messages/models/whatsapp.py

@@ -3,8 +3,8 @@
 from pydantic import BaseModel, ConfigDict, Field
 from vonage_utils.types.phone_number import PhoneNumber
 
-from ..enums import ChannelType, MessageType
 from .base_message import BaseMessage
+from .enums import ChannelType, MessageType
 
 
 class WhatsappContext(BaseModel):

messages/src/vonage_messages/responses.py

@@ -1,7 +1,11 @@
 from pydantic import BaseModel
 
 
-class MessageUuid(BaseModel):
-    """Response from Vonage's Messages API."""
+class SendMessageResponse(BaseModel):
+    """Response from Vonage's Messages API.
+
+    Attributes:
+        message_uuid (str): The UUID of the sent message.
+    """
 
     message_uuid: str

messages/tests/data/invalid_error.json

@@ -0,0 +1,12 @@
+{
+    "type": "https://developer.vonage.com/api-errors/messages#1150",
+    "title": "Invalid params",
+    "detail": "The value of one or more parameters is invalid.",
+    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
+    "invalid_parameters": [
+        {
+            "name": "messenger.tag",
+            "reason": "invalid value"
+        }
+    ]
+}

messages/tests/data/low_balance_error.json

@@ -0,0 +1,6 @@
+{
+    "type": "https://developer.nexmo.com/api-errors/#low-balance",
+    "title": "Low balance",
+    "detail": "This request could not be performed due to your account balance being low.",
+    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
+}

messages/tests/data/send_message.json

@@ -0,0 +1,3 @@
+{
+    "message_uuid": "d8f86df1-dec6-442f-870a-2241be27d721"
+}