edits to voice api models

Author: maxkahan

voice/CHANGES.md

@@ -1,3 +1,9 @@
+# 1.3.0
+- Add new `headers` and `standard_headers` options to the `Sip` data model
+- Add new `standardHeaders` option to the `SipEndpoint` NCCO model
+- Add check for invalid hostnames when downloading a recording with `Voice.download_recording`
+- Allow the `CreateCallRequest` model to accept a SIP URI as well as a phone number in the `from_` field
+
 # 1.2.0
 - Make all models originally accessed by `vonage_voice.models.***` available at the top level of the package, i.e. `vonage_voice.***`
 

voice/src/vonage_voice/_version.py

@@ -1 +1 @@
-__version__ = '1.2.0'
+__version__ = '1.3.0'

voice/src/vonage_voice/models/common.py

@@ -3,6 +3,7 @@
 from pydantic import BaseModel, Field
 from vonage_utils.types import PhoneNumber, SipUri
 from vonage_voice.models.enums import Channel
+from vonage_voice.models.input_types import Dtmf
 
 
 class Phone(BaseModel):
@@ -21,9 +22,14 @@ class Sip(BaseModel):
 
     Args:
         uri (SipUri): The SIP URI.
+        headers (Optional[dict]): Metadata to include in the request. The headers are transmitted as part of the SIP INVITE as `X-key: value` headers.
+        standard_headers (Optional[dict]): Standard SIP headers to include in the request. Unlike `headers`, these are not prepended with `X-`.
+            This should be of the form `{'User-to-User': '342342ef34;encoding=hex'}
     """
 
     uri: SipUri
+    headers: Optional[dict] = None
+    standard_headers: Optional[dict] = None
     type: Channel = Channel.SIP
 
 

voice/src/vonage_voice/models/connect_endpoints.py

@@ -73,10 +73,14 @@ class SipEndpoint(BaseModel):
         headers (Optional[dict]): The headers to include with the SIP connection. To use
             TLS and/or SRTP, include respectively `transport=tls` or `media=srtp` to the URL with
             the semicolon `;` as a delimiter.
+        standardHeaders (Optional[dict]): Standard SIP headers to include in the request. Unlike
+            `headers`, these are not prepended with `X-`. This should be of the form
+            `{'User-to-User': '342342ef34;encoding=hex'}`.
     """
 
     uri: SipUri
     headers: Optional[dict] = None
+    standardHeaders: Optional[dict] = None
     type: ConnectEndpointType = ConnectEndpointType.SIP
 
 

voice/src/vonage_voice/models/requests.py

@@ -30,8 +30,7 @@ class CreateCallRequest(BaseModel):
         answer_method (Optional[Literal['POST', 'GET']]): The HTTP method used to send
             event information to `answer_url`.
         to (list[Union[ToPhone, Sip, Websocket, Vbc]]): The type of connection to call.
-        from_ (Optional[Phone]): The phone number to use when calling. Mutually exclusive
-            with the `random_from_number` property.
+        from_ (Optional[Union[Phone, str]]): The phone number or SIP URI to use when calling. Mutually exclusive with the `random_from_number` property.
         random_from_number (Optional[bool]): Whether to use a random number as the caller's
             phone number. The number will be selected from the list of the numbers assigned
             to the current application. Mutually exclusive with the `from_` property.
@@ -60,8 +59,7 @@ class CreateCallRequest(BaseModel):
     answer_url: list[str] = None
     answer_method: Optional[Literal['POST', 'GET']] = None
     to: list[Union[ToPhone, Sip, Websocket, Vbc]]
-
-    from_: Optional[Phone] = Field(None, serialization_alias='from')
+    from_: Optional[Union[Phone, str]] = Field(None, serialization_alias='from')
     random_from_number: Optional[bool] = None
     event_url: Optional[list[str]] = None
     event_method: Optional[Literal['POST', 'GET']] = None

voice/src/vonage_voice/voice.py

@@ -4,6 +4,7 @@
 from vonage_http_client.http_client import HttpClient
 from vonage_jwt.verify_jwt import verify_signature
 from vonage_utils.types import Dtmf
+from vonage_voice.errors import VoiceError
 from vonage_voice.models.ncco import NccoAction
 
 from .models.requests import (
@@ -272,6 +273,9 @@ def download_recording(self, url: str, file_path: str) -> None:
             url (str): The URL of the recording to get.
             file_path (str): The path to save the recording to.
         """
+        if not 'vonage.com' in url and not 'nexmo.com' in url:
+            raise VoiceError('The recording URL must be from a Vonage or Nexmo hostname.')
+
         self._http_client.download_file_stream(url=url, file_path=file_path)
 
     @validate_call

voice/tests/test_ncco_actions.py

@@ -113,10 +113,13 @@ def test_create_connect_endpoints():
     }
 
     assert connect_endpoints.SipEndpoint(
-        uri='sip:example@sip.example.com', headers={'qwer': 'asdf'}
+        uri='sip:example@sip.example.com',
+        headers={'qwer': 'asdf'},
+        standardHeaders={'User-to-User': '342342ef34;encoding=hex'},
     ).model_dump() == {
         'uri': 'sip:example@sip.example.com',
         'headers': {'qwer': 'asdf'},
+        'standardHeaders': {'User-to-User': '342342ef34;encoding=hex'},
         'type': 'sip',
     }
 

voice/tests/test_voice.py

@@ -1,3 +1,4 @@
+import json
 from os.path import abspath
 
 import responses
@@ -8,6 +9,7 @@
     AudioStreamOptions,
     CreateCallRequest,
     ListCallsFilter,
+    Sip,
     TtsStreamOptions,
 )
 from vonage_voice.errors import VoiceError
@@ -35,9 +37,42 @@ def test_create_call_basic_ncco():
     ncco = [Talk(text='Hello world')]
     call = CreateCallRequest(
         ncco=ncco,
-        to=[{'type': 'sip', 'uri': 'sip:test@example.com'}],
+        to=[
+            Sip(
+                uri='sip:test@example.com',
+                headers={'location': 'New York City'},
+                standard_headers={'User-to-User': '342342ef34;encoding=hex'},
+            )
+        ],
         random_from_number=True,
     )
+
+    response = voice.create_call(call)
+
+    body = json.loads(voice.http_client.last_request.body)
+    assert body['to'][0]['headers'] == {'location': 'New York City'}
+    assert body['to'][0]['standard_headers'] == {
+        'User-to-User': '342342ef34;encoding=hex'
+    }
+    assert type(response) == CreateCallResponse
+    assert response.uuid == '106a581a-34d0-432a-a625-220221fd434f'
+    assert response.status == 'started'
+    assert response.direction == 'outbound'
+    assert response.conversation_uuid == 'CON-2be039b2-d0a4-4274-afc8-d7b241c7c044'
+
+
+@responses.activate
+def test_create_call_basic_ncco_from_sip():
+    build_response(
+        path, 'POST', 'https://api.nexmo.com/v1/calls', 'create_call.json', 201
+    )
+    ncco = [Talk(text='Hello world')]
+    call = CreateCallRequest(
+        ncco=ncco,
+        to=[Sip(uri='sip:test@example.com')],
+        from_='sip:from_sip_uri@example.com',
+    )
+
     response = voice.create_call(call)
 
     assert type(response) == CreateCallResponse
@@ -429,6 +464,15 @@ def test_download_recording():
         assert file_content.startswith(b'ID3')
 
 
+def test_download_recording_invalid_url():
+    with raises(VoiceError) as e:
+        voice.download_recording(
+            url='https://invalid.com/v1/files/aaaaaaaa-bbbb-cccc-dddd-0123456789ab',
+            file_path='voice/tests/data/file_stream.mp3',
+        )
+    assert e.match('The recording URL must be from a Vonage or Nexmo hostname.')
+
+
 def test_verify_signature():
     token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPbmxpbmUgSldUIEJ1aWxkZXIiLCJpYXQiOjE2OTc2MzQ2ODAsImV4cCI6MzMyNTQ1NDA4MjgsImF1ZCI6IiIsInN1YiI6IiJ9.88vJc3I2HhuqEDixHXVhc9R30tA6U_HQHZTC29y6CGM'
     valid_signature = "qwertyuiopasdfghjklzxcvbnm123456"

vonage/CHANGES.md

@@ -1,3 +1,10 @@
+# 4.4.0
+Vonage Voice Package:
+- Add new `headers` and `standard_headers` options to the `Sip` data model
+- Add new `standardHeaders` option to the `SipEndpoint` NCCO model
+- Add check for invalid hostnames when downloading a recording with `Voice.download_recording`
+- Allow the `CreateCallRequest` model to accept a SIP URI as well as a phone number in the `from_` field
+
 # 4.3.0
 - Make all models originally accessed by `vonage_voice.models.***` available at the top level of the package, i.e. `vonage_voice.***`
 - Make all models originally accessed by `vonage_video.models.***` available at the top level of the package, i.e. `vonage_video.***`

vonage/pyproject.toml

@@ -21,7 +21,7 @@ dependencies = [
   "vonage-verify>=2.1.0",
   "vonage-verify-legacy>=1.0.1",
   "vonage-video>=1.2.0",
-  "vonage-voice>=1.2.0",
+  "vonage-voice>=1.3.0",
 ]
 classifiers = [
   "Programming Language :: Python",