VAPI-3164 Add <Refer> BXML verb support

README.md

@@ -365,6 +365,7 @@ Class | Method | HTTP request | Description
  - [TranscribeRecording](docs/TranscribeRecording.md)
  - [Transcription](docs/Transcription.md)
  - [TranscriptionAvailableCallback](docs/TranscriptionAvailableCallback.md)
+ - [Refer (BXML verb)](docs/Refer.md)
  - [TransferAnswerCallback](docs/TransferAnswerCallback.md)
  - [TransferCompleteCallback](docs/TransferCompleteCallback.md)
  - [TransferDisconnectCallback](docs/TransferDisconnectCallback.md)

docs/Refer.md

@@ -0,0 +1,22 @@
+# Refer
+
+The <Refer> BXML verb initiates a SIP REFER on an existing inbound SIP URI call, instructing the remote SIP endpoint to contact a third party directly. On success the call is terminated — the remote endpoint redirects away from Bandwidth entirely. On failure, BXML returned from referCompleteUrl can be used for recovery.
+
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+|**sipUri** | **SipUri** | The SIP URI to refer the call to. Must start with sip:. | required |
+|**referCompleteUrl** | **URI** | URL to send the Refer Complete event to and request new BXML for failure recovery. May be a relative URL. |  [optional] |
+|**referCompleteMethod** | **String** | The HTTP method to use for the request to referCompleteUrl. GET or POST. Default value is POST. |  [optional] |
+|**referCompleteFallbackUrl** | **URI** | A fallback url which, if provided, will be used to retry the Refer Complete callback delivery in case referCompleteUrl fails to respond. |  [optional] |
+|**referCompleteFallbackMethod** | **String** | The HTTP method to use to deliver the Refer Complete callback to referCompleteFallbackUrl. GET or POST. Default value is POST. |  [optional] |
+|**username** | **String** | The username to send in the HTTP request to referCompleteUrl. |  [optional] |
+|**password** | **String** | The password to send in the HTTP request to referCompleteUrl. |  [optional] |
+|**fallbackUsername** | **String** | The username to send in the HTTP request to referCompleteFallbackUrl. |  [optional] |
+|**fallbackPassword** | **String** | The password to send in the HTTP request to referCompleteFallbackUrl. |  [optional] |
+|**tag** | **String** | A custom string that will be sent with these and all future callbacks unless overwritten by a future tag attribute or cleared. May be cleared by setting tag="". Max length 256 characters. |  [optional] |
+
+
+
+

src/main/java/com/bandwidth/sdk/model/bxml/Bxml.java

@@ -43,6 +43,7 @@ public class Bxml {
             @XmlElement(name = PlayAudio.TYPE_NAME, type = PlayAudio.class),
             @XmlElement(name = Record.TYPE_NAME, type = Record.class),
             @XmlElement(name = Redirect.TYPE_NAME, type = Redirect.class),
+            @XmlElement(name = Refer.TYPE_NAME, type = Refer.class),
             @XmlElement(name = ResumeRecording.TYPE_NAME, type = ResumeRecording.class),
             @XmlElement(name = Ring.TYPE_NAME, type = Ring.class),
             @XmlElement(name = SendDtmf.TYPE_NAME, type = SendDtmf.class),

src/main/java/com/bandwidth/sdk/model/bxml/Refer.java

@@ -0,0 +1,86 @@
+/**
+ * The {@code <Refer>} verb is used to initiate a SIP REFER on an existing call,
+ * instructing the remote SIP endpoint to contact a third party directly.
+ * On success the call is terminated — the remote endpoint redirects away from Bandwidth entirely.
+ */
+
+package com.bandwidth.sdk.model.bxml;
+
+import static com.bandwidth.sdk.model.bxml.utils.BxmlConstants.DEFAULT_CALLBACK_METHOD;
+
+import jakarta.xml.bind.annotation.XmlAccessType;
+import jakarta.xml.bind.annotation.XmlAccessorType;
+import jakarta.xml.bind.annotation.XmlAttribute;
+import jakarta.xml.bind.annotation.XmlElement;
+import jakarta.xml.bind.annotation.XmlType;
+import java.net.URI;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Builder.Default;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(name = Refer.TYPE_NAME)
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Getter
+@EqualsAndHashCode
+/**
+ *
+ * @param sipUri (SipUri, required): The SIP URI to refer the call to. Must start with "sip:".
+ * @param referCompleteUrl (str, optional): URL to send the Refer Complete event to and request new BXML for failure recovery. May be a relative URL. Defaults to None.
+ * @param referCompleteMethod (str, optional): The HTTP method to use for the request to referCompleteUrl. GET or POST. Default value is POST.
+ * @param referCompleteFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the Refer Complete callback delivery in case referCompleteUrl fails to respond. Defaults to None.
+ * @param referCompleteFallbackMethod (str, optional): The HTTP method to use to deliver the Refer Complete callback to referCompleteFallbackUrl. GET or POST. Default value is POST.
+ * @param username (str, optional): The username to send in the HTTP request to referCompleteUrl. Defaults to None.
+ * @param password (str, optional): The password to send in the HTTP request to referCompleteUrl. Defaults to None.
+ * @param fallbackUsername (str, optional): The username to send in the HTTP request to referCompleteFallbackUrl. Defaults to None.
+ * @param fallbackPassword (str, optional): The password to send in the HTTP request to referCompleteFallbackUrl. Defaults to None.
+ * @param tag (str, optional): A custom string that will be sent with these 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.
+ *
+ */
+public class Refer implements Verb {
+
+    public static final String TYPE_NAME = "Refer";
+
+    @XmlElement(name = SipUri.TYPE_NAME, type = SipUri.class)
+    protected SipUri sipUri;
+
+    @XmlAttribute
+    protected URI referCompleteUrl;
+
+    @XmlAttribute
+    @Default
+    protected String referCompleteMethod = DEFAULT_CALLBACK_METHOD;
+
+    @XmlAttribute
+    protected URI referCompleteFallbackUrl;
+
+    @XmlAttribute
+    @Default
+    protected String referCompleteFallbackMethod = DEFAULT_CALLBACK_METHOD;
+
+    @XmlAttribute
+    protected String username;
+
+    @XmlAttribute
+    protected String password;
+
+    @XmlAttribute
+    protected String fallbackUsername;
+
+    @XmlAttribute
+    protected String fallbackPassword;
+
+    @XmlAttribute
+    protected String tag;
+
+    @Override
+    public String getVerbName() {
+        return TYPE_NAME;
+    }
+}
+

src/test/java/com/bandwidth/sdk/unit/models/bxml/ReferVerbTest.java

@@ -0,0 +1,55 @@
+/**
+ *
+ * Unit tests for Refer Verb class
+ *
+ * @throws JAXBException if the test fails
+ */
+
+package com.bandwidth.sdk.unit.models.bxml;
+
+import com.bandwidth.sdk.model.bxml.Bxml;
+import com.bandwidth.sdk.model.bxml.Refer;
+import com.bandwidth.sdk.model.bxml.SipUri;
+
+import jakarta.xml.bind.JAXBContext;
+import jakarta.xml.bind.JAXBException;
+
+import org.junit.jupiter.api.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+import java.net.URI;
+
+public class ReferVerbTest {
+
+        SipUri sipUri = SipUri.builder()
+                        .uri("sip:alice@atlanta.example.com")
+                        .build();
+
+        Refer refer = Refer.builder()
+                        .sipUri(sipUri)
+                        .referCompleteUrl(URI.create("https://example.com/webhooks/refer_complete"))
+                        .referCompleteMethod("POST")
+                        .tag("test-tag")
+                        .build();
+
+        Refer referMinimal = Refer.builder()
+                        .sipUri(sipUri)
+                        .build();
+
+        @Test
+        public void referVerbWithAllAttributes() throws JAXBException {
+                JAXBContext jaxbContext = JAXBContext.newInstance(Bxml.class);
+                String expectedBxml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><Bxml><Refer referCompleteUrl=\"https://example.com/webhooks/refer_complete\" referCompleteMethod=\"POST\" referCompleteFallbackMethod=\"POST\" tag=\"test-tag\"><SipUri transferAnswerMethod=\"POST\" transferAnswerFallbackMethod=\"POST\" transferDisconnectMethod=\"POST\">sip:alice@atlanta.example.com</SipUri></Refer></Bxml>";
+                assertThat(new Bxml().with(refer).toBxml(jaxbContext), is(expectedBxml));
+        }
+
+        @Test
+        public void referVerbMinimal() throws JAXBException {
+                JAXBContext jaxbContext = JAXBContext.newInstance(Bxml.class);
+                String expectedBxml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><Bxml><Refer referCompleteMethod=\"POST\" referCompleteFallbackMethod=\"POST\"><SipUri transferAnswerMethod=\"POST\" transferAnswerFallbackMethod=\"POST\" transferDisconnectMethod=\"POST\">sip:alice@atlanta.example.com</SipUri></Refer></Bxml>";
+                assertThat(new Bxml().with(referMinimal).toBxml(jaxbContext), is(expectedBxml));
+        }
+}
+