VAPI-3161 Add ReferCompleteCallback model and scenario tests

Unblocked by api-specs#2142 merging. Hand-written to match the
OpenAPI generator output pattern (mirrors TransferCompleteCallback).

Fields: standard call fields + referCallStatus, referSipResponseCode,
notifySipResponseCode. Excludes cause/errorMessage/errorId (not in spec)
and enqueuedTime (inbound SIP URI calls only).

Adds scenario tests for all four referComplete outcomes:
- Success (202 REFER, 200 NOTIFY)
- Failure: REFER rejected (e.g. 405, no NOTIFY)
- Failure: destination unreachable (202 REFER, 4xx NOTIFY)
- Failure: NOTIFY timeout (202 REFER, no NOTIFY)

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: stampercasey

.openapi-generator/FILES

@@ -197,6 +197,7 @@ bandwidth/models/thumbnail_alignment_enum.py
 bandwidth/models/transcribe_recording.py
 bandwidth/models/transcription.py
 bandwidth/models/transcription_available_callback.py
+bandwidth/models/refer_complete_callback.py
 bandwidth/models/transfer_answer_callback.py
 bandwidth/models/transfer_complete_callback.py
 bandwidth/models/transfer_disconnect_callback.py

bandwidth/__init__.py

@@ -217,6 +217,7 @@
     "TranscribeRecording",
     "Transcription",
     "TranscriptionAvailableCallback",
+    "ReferCompleteCallback",
     "TransferAnswerCallback",
     "TransferCompleteCallback",
     "TransferDisconnectCallback",
@@ -443,6 +444,7 @@
 from bandwidth.models.transcribe_recording import TranscribeRecording as TranscribeRecording
 from bandwidth.models.transcription import Transcription as Transcription
 from bandwidth.models.transcription_available_callback import TranscriptionAvailableCallback as TranscriptionAvailableCallback
+from bandwidth.models.refer_complete_callback import ReferCompleteCallback as ReferCompleteCallback
 from bandwidth.models.transfer_answer_callback import TransferAnswerCallback as TransferAnswerCallback
 from bandwidth.models.transfer_complete_callback import TransferCompleteCallback as TransferCompleteCallback
 from bandwidth.models.transfer_disconnect_callback import TransferDisconnectCallback as TransferDisconnectCallback

bandwidth/models/__init__.py

@@ -191,6 +191,7 @@
 from bandwidth.models.transcribe_recording import TranscribeRecording
 from bandwidth.models.transcription import Transcription
 from bandwidth.models.transcription_available_callback import TranscriptionAvailableCallback
+from bandwidth.models.refer_complete_callback import ReferCompleteCallback
 from bandwidth.models.transfer_answer_callback import TransferAnswerCallback
 from bandwidth.models.transfer_complete_callback import TransferCompleteCallback
 from bandwidth.models.transfer_disconnect_callback import TransferDisconnectCallback

bandwidth/models/refer_complete_callback.py

@@ -0,0 +1,149 @@
+# coding: utf-8
+
+"""
+    Bandwidth
+
+    Bandwidth's Communication APIs
+
+    The version of the OpenAPI document: 1.0.0
+    Contact: letstalk@bandwidth.com
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional
+from bandwidth.models.call_direction_enum import CallDirectionEnum
+from typing import Optional, Set
+from typing_extensions import Self
+
+class ReferCompleteCallback(BaseModel):
+    """
+    The Refer Complete event is fired when the <Refer> verb finishes executing. This is sent to the referCompleteUrl specified on the <Refer> verb, and the BXML returned in it is executed on the call only on failure — the call is torn down on success.
+    """ # noqa: E501
+    event_type: Optional[StrictStr] = Field(default=None, description="The event type, value is referComplete.", alias="eventType")
+    event_time: Optional[datetime] = Field(default=None, description="The approximate UTC date and time when the event was generated by the Bandwidth server, in ISO 8601 format. This may not be exactly the time of event execution.", alias="eventTime")
+    account_id: Optional[StrictStr] = Field(default=None, description="The user account associated with the call.", alias="accountId")
+    application_id: Optional[StrictStr] = Field(default=None, description="The id of the application associated with the call.", alias="applicationId")
+    var_from: Optional[StrictStr] = Field(default=None, description="The provided identifier of the caller. Must be a phone number in E.164 format (e.g. +15555555555).", alias="from")
+    to: Optional[StrictStr] = Field(default=None, description="The phone number that received the call, in E.164 format (e.g. +15555555555).")
+    direction: Optional[CallDirectionEnum] = None
+    call_id: Optional[StrictStr] = Field(default=None, description="The call id associated with the event.", alias="callId")
+    call_url: Optional[StrictStr] = Field(default=None, description="The URL of the call associated with the event.", alias="callUrl")
+    start_time: Optional[datetime] = Field(default=None, description="Time the call was started, in ISO 8601 format.", alias="startTime")
+    answer_time: Optional[datetime] = Field(default=None, description="Time the call was answered, in ISO 8601 format.", alias="answerTime")
+    tag: Optional[StrictStr] = Field(default=None, description="(optional) The tag specified on call creation. If no tag was specified or it was previously cleared, this field will not be present.")
+    refer_call_status: Optional[StrictStr] = Field(default=None, description="The outcome of the REFER operation. Either 'success' or 'failure'.", alias="referCallStatus")
+    refer_sip_response_code: Optional[StrictInt] = Field(default=None, description="The SIP response code returned for the REFER request itself (e.g. 202, 405, 603). Present when a SIP response was received for the REFER.", alias="referSipResponseCode")
+    notify_sip_response_code: Optional[StrictInt] = Field(default=None, description="The final SIP response code reported via NOTIFY. Present only when the caller's endpoint sent a final NOTIFY (e.g. 200, 404, 486). Not present on NOTIFY timeout or when REFER was rejected before a subscription was established.", alias="notifySipResponseCode")
+    additional_properties: Dict[str, Any] = {}
+    __properties: ClassVar[List[str]] = ["eventType", "eventTime", "accountId", "applicationId", "from", "to", "direction", "callId", "callUrl", "startTime", "answerTime", "tag", "referCallStatus", "referSipResponseCode", "notifySipResponseCode"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of ReferCompleteCallback from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        * Fields in `self.additional_properties` are added to the output dict.
+        """
+        excluded_fields: Set[str] = set([
+            "additional_properties",
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # puts key-value pairs in additional_properties in the top level
+        if self.additional_properties is not None:
+            for _key, _value in self.additional_properties.items():
+                _dict[_key] = _value
+
+        # set to None if answer_time (nullable) is None
+        # and model_fields_set contains the field
+        if self.answer_time is None and "answer_time" in self.model_fields_set:
+            _dict['answerTime'] = None
+
+        # set to None if tag (nullable) is None
+        # and model_fields_set contains the field
+        if self.tag is None and "tag" in self.model_fields_set:
+            _dict['tag'] = None
+
+        # set to None if refer_sip_response_code (nullable) is None
+        # and model_fields_set contains the field
+        if self.refer_sip_response_code is None and "refer_sip_response_code" in self.model_fields_set:
+            _dict['referSipResponseCode'] = None
+
+        # set to None if notify_sip_response_code (nullable) is None
+        # and model_fields_set contains the field
+        if self.notify_sip_response_code is None and "notify_sip_response_code" in self.model_fields_set:
+            _dict['notifySipResponseCode'] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of ReferCompleteCallback from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "eventType": obj.get("eventType"),
+            "eventTime": obj.get("eventTime"),
+            "accountId": obj.get("accountId"),
+            "applicationId": obj.get("applicationId"),
+            "from": obj.get("from"),
+            "to": obj.get("to"),
+            "direction": obj.get("direction"),
+            "callId": obj.get("callId"),
+            "callUrl": obj.get("callUrl"),
+            "startTime": obj.get("startTime"),
+            "answerTime": obj.get("answerTime"),
+            "tag": obj.get("tag"),
+            "referCallStatus": obj.get("referCallStatus"),
+            "referSipResponseCode": obj.get("referSipResponseCode"),
+            "notifySipResponseCode": obj.get("notifySipResponseCode")
+        })
+        # store additional fields in additional_properties
+        for _key in obj.keys():
+            if _key not in cls.__properties:
+                _obj.additional_properties[_key] = obj.get(_key)
+
+        return _obj

test/unit/models/test_refer_complete_callback.py

@@ -0,0 +1,161 @@
+# coding: utf-8
+
+"""
+    Bandwidth
+
+    Bandwidth's Communication APIs
+
+    The version of the OpenAPI document: 1.0.0
+    Contact: letstalk@bandwidth.com
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+import unittest
+from datetime import datetime
+
+from bandwidth.models.refer_complete_callback import ReferCompleteCallback
+
+
+class TestReferCompleteCallback(unittest.TestCase):
+    """ReferCompleteCallback unit test stubs"""
+
+    def setUp(self):
+        pass
+
+    def tearDown(self):
+        pass
+
+    def make_instance(self, include_optional) -> ReferCompleteCallback:
+        """Test ReferCompleteCallback
+            include_optional is a boolean, when False only required
+            params are included, when True both required and
+            optional params are included """
+        if include_optional:
+            return ReferCompleteCallback(
+                event_type = 'referComplete',
+                event_time = '2026-04-30T13:13:34.859Z',
+                account_id = '9900000',
+                application_id = '04e88489-df02-4e34-a0ee-27a91849555f',
+                var_from = '+15555555555',
+                to = '+15555555555',
+                direction = 'inbound',
+                call_id = 'c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85',
+                call_url = 'https://voice.bandwidth.com/api/v2/accounts/9900000/calls/c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85',
+                start_time = '2026-04-30T13:13:34.859Z',
+                answer_time = '2026-04-30T13:13:40.644Z',
+                tag = 'exampleTag',
+                refer_call_status = 'success',
+                refer_sip_response_code = 202,
+                notify_sip_response_code = 200
+            )
+        else:
+            return ReferCompleteCallback(
+        )
+
+    def testReferCompleteCallback(self):
+        """Test ReferCompleteCallback"""
+        instance = self.make_instance(True)
+        assert instance is not None
+        assert isinstance(instance, ReferCompleteCallback)
+        assert instance.event_type == 'referComplete'
+        assert isinstance(instance.event_time, datetime)
+        assert instance.account_id == '9900000'
+        assert instance.application_id == '04e88489-df02-4e34-a0ee-27a91849555f'
+        assert instance.var_from == '+15555555555'
+        assert instance.to == '+15555555555'
+        assert instance.direction == 'inbound'
+        assert instance.call_id == 'c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85'
+        assert instance.call_url == 'https://voice.bandwidth.com/api/v2/accounts/9900000/calls/c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85'
+        assert isinstance(instance.start_time, datetime)
+        assert isinstance(instance.answer_time, datetime)
+        assert instance.tag == 'exampleTag'
+        assert instance.refer_call_status == 'success'
+        assert instance.refer_sip_response_code == 202
+        assert instance.notify_sip_response_code == 200
+
+
+class TestReferCompleteCallbackScenarios(unittest.TestCase):
+    """Hand-written scenario tests for the four referComplete callback cases."""
+
+    BASE_PAYLOAD = {
+        "eventType": "referComplete",
+        "eventTime": "2026-04-30T13:13:34.859Z",
+        "accountId": "9900000",
+        "applicationId": "04e88489-df02-4e34-a0ee-27a91849555f",
+        "from": "+15555555555",
+        "to": "+15555555555",
+        "direction": "inbound",
+        "callId": "c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85",
+        "callUrl": "https://voice.bandwidth.com/api/v2/accounts/9900000/calls/c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85",
+        "startTime": "2026-04-30T13:13:34.859Z",
+        "answerTime": "2026-04-30T13:13:40.644Z",
+    }
+
+    def _parse(self, extra: dict) -> ReferCompleteCallback:
+        return ReferCompleteCallback.from_dict({**self.BASE_PAYLOAD, **extra})
+
+    def test_success(self):
+        """Successful REFER: remote answered, call torn down.
+        referSipResponseCode=202 (accepted), notifySipResponseCode=200 (OK via NOTIFY)."""
+        cb = self._parse({
+            "referCallStatus": "success",
+            "referSipResponseCode": 202,
+            "notifySipResponseCode": 200,
+        })
+        assert cb.refer_call_status == "success"
+        assert cb.refer_sip_response_code == 202
+        assert cb.notify_sip_response_code == 200
+
+    def test_failure_refer_rejected(self):
+        """REFER rejected by caller's endpoint (e.g. 405 Method Not Allowed).
+        No NOTIFY subscription was established, so notifySipResponseCode is absent."""
+        cb = self._parse({
+            "referCallStatus": "failure",
+            "referSipResponseCode": 405,
+        })
+        assert cb.refer_call_status == "failure"
+        assert cb.refer_sip_response_code == 405
+        assert cb.notify_sip_response_code is None
+
+    def test_failure_destination_unreachable(self):
+        """REFER accepted (202) but destination was unreachable.
+        NOTIFY reports a 4xx error code (e.g. 404 Not Found)."""
+        cb = self._parse({
+            "referCallStatus": "failure",
+            "referSipResponseCode": 202,
+            "notifySipResponseCode": 404,
+        })
+        assert cb.refer_call_status == "failure"
+        assert cb.refer_sip_response_code == 202
+        assert cb.notify_sip_response_code == 404
+
+    def test_failure_notify_timeout(self):
+        """REFER accepted (202) but no final NOTIFY arrived within 30 seconds.
+        notifySipResponseCode is absent because no NOTIFY was received."""
+        cb = self._parse({
+            "referCallStatus": "failure",
+            "referSipResponseCode": 202,
+        })
+        assert cb.refer_call_status == "failure"
+        assert cb.refer_sip_response_code == 202
+        assert cb.notify_sip_response_code is None
+
+    def test_from_json_round_trip(self):
+        """JSON round-trip: from_json -> to_json preserves all fields."""
+        payload = {**self.BASE_PAYLOAD, "referCallStatus": "success", "referSipResponseCode": 202, "notifySipResponseCode": 200}
+        cb = ReferCompleteCallback.from_json(str(payload).replace("'", '"'))
+        assert cb.refer_call_status == "success"
+
+    def test_no_cause_error_fields(self):
+        """referComplete callback does not carry cause/errorMessage/errorId fields."""
+        cb = self._parse({"referCallStatus": "failure", "referSipResponseCode": 405})
+        assert not hasattr(cb, 'cause')
+        assert not hasattr(cb, 'error_message')
+        assert not hasattr(cb, 'error_id')
+
+
+if __name__ == '__main__':
+    unittest.main()