VAPI-3161: Add <Refer> BXML verb support

bandwidth/models/bxml/verbs/__init__.py

@@ -11,6 +11,7 @@
 from .phone_number import PhoneNumber
 from .play_audio import PlayAudio
 from .record import Record
+from .refer import Refer
 from .redirect import Redirect
 from .resume_recording import ResumeRecording
 from .ring import Ring

bandwidth/models/bxml/verbs/refer.py

@@ -0,0 +1,58 @@
+"""
+refer.py
+
+Bandwidth's Refer BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..nestable_verb import NestableVerb
+from .sip_uri import SipUri
+
+
+class Refer(NestableVerb):
+
+    def __init__(
+        self, sip_uri: SipUri,
+        refer_complete_url: str=None, refer_complete_method: str=None,
+        tag: str=None
+    ):
+        """Initialize a <Refer> verb
+
+        The <Refer> verb sends a SIP REFER to the remote endpoint, asking it
+        to redirect the call to a new SIP URI. Unlike <Transfer>, a successful
+        REFER terminates the call on Bandwidth's side: the remote endpoint
+        redirects away from Bandwidth entirely. This is a SIP protocol
+        property, not a Bandwidth design choice. As a result, BXML returned in
+        response to the referComplete callback is only meaningful for failure
+        handling — there is no live call to act on after success.
+
+        Args:
+            sip_uri (SipUri): The SIP URI to refer the call to. Required.
+                Exactly one <SipUri> child element is allowed.
+            refer_complete_url (str, optional): URL to send the Refer Complete
+                event to when the REFER flow finishes (success or failure).
+                May be a relative URL. Defaults to None.
+            refer_complete_method (str, optional): The HTTP method to use for
+                the request to referCompleteUrl. GET or POST. Default value
+                is POST. Defaults to None.
+            tag (str, optional): A custom string that will be sent with this
+                and all future callbacks unless overwritten by a future tag
+                attribute or cleared. May be cleared by setting tag="". Max
+                length 256 characters. Defaults to None.
+        """
+        self.sip_uri = sip_uri
+        self.refer_complete_url = refer_complete_url
+        self.refer_complete_method = refer_complete_method
+        self.tag = tag
+        super().__init__(
+            tag="Refer",
+            nested_verbs=[self.sip_uri]
+        )
+
+    @property
+    def _attributes(self):
+        return {
+            "referCompleteUrl": self.refer_complete_url,
+            "referCompleteMethod": self.refer_complete_method,
+            "tag": self.tag
+        }

test/unit/models/bxml/test_refer.py

@@ -0,0 +1,38 @@
+"""
+test_refer.py
+
+Unit tests for the <Refer> BXML verb
+
+@copyright Bandwidth Inc.
+"""
+import unittest
+
+from bandwidth.models.bxml import Refer, SipUri, Verb, NestableVerb
+
+
+class TestRefer(unittest.TestCase):
+
+    def setUp(self):
+        self.sip_uri = SipUri(
+            uri="sip:alice@atlanta.example.com"
+        )
+        self.refer = Refer(
+            sip_uri=self.sip_uri,
+            refer_complete_url="https://example.com/handleRefer",
+            refer_complete_method="POST",
+            tag="test"
+        )
+
+    def test_instance(self):
+        assert isinstance(self.refer, Refer)
+        assert isinstance(self.refer, NestableVerb)
+        assert isinstance(self.refer, Verb)
+
+    def test_to_bxml(self):
+        expected = '<Refer referCompleteUrl="https://example.com/handleRefer" referCompleteMethod="POST" tag="test"><SipUri>sip:alice@atlanta.example.com</SipUri></Refer>'
+        assert expected == self.refer.to_bxml()
+
+    def test_minimal(self):
+        minimal_refer = Refer(sip_uri=SipUri(uri="sip:bob@example.com"))
+        expected = '<Refer><SipUri>sip:bob@example.com</SipUri></Refer>'
+        assert expected == minimal_refer.to_bxml()