SWI-4292 Update add_verb Methods (#125)

* SWI-4292 Update `add_verb` Methods

* add deprecation warnings

lib/bandwidth-sdk/models/bxml/bxml.rb

@@ -2,7 +2,7 @@ module Bandwidth
   module Bxml
     class Bxml < Bandwidth::Bxml::Root
       # Initializer
-      # @param nested_verbs [Array<Verb>] XML element children. Defaults to an empty array.
+      # @param nested_verbs [Verb] or [Array<Verb>] XML element children. Defaults to an empty array.
       def initialize(nested_verbs = [])
         super(tag = 'Bxml', nested_verbs)
       end

lib/bandwidth-sdk/models/bxml/nestable_verb.rb

@@ -6,12 +6,12 @@ class NestableVerb < Bandwidth::Bxml::Verb
       # Initializer
       # @param tag [String] Name of the XML element.
       # @param content [String] XML element content. Defaults to nil.
-      # @param nested_verbs [Array] XML element children. Defaults to an empty array.
+      # @param nested_verbs [Verb] or [Array<Verb>] XML element children. Defaults to an empty array.
       # @param attributes [Hash] The attributes to add to the element. Defaults to an empty hash.
       def initialize(tag, content = nil, nested_verbs = [], attributes = {})
         @tag = tag
         @content = content
-        @nested_verbs = nested_verbs
+        @nested_verbs = Array(nested_verbs)
         @attributes = attributes
       end
 

lib/bandwidth-sdk/models/bxml/response.rb

@@ -2,7 +2,7 @@ module Bandwidth
   module Bxml
     class Response < Bandwidth::Bxml::Root
       # Initializer
-      # @param nested_verbs [Array<Verb>] XML element children. Defaults to an empty array.
+      # @param nested_verbs [Verb] or [Array<Verb>] XML element children. Defaults to an empty array.
       def initialize(nested_verbs = [])
         super(tag = 'Response', nested_verbs)
       end

lib/bandwidth-sdk/models/bxml/root.rb

@@ -8,10 +8,10 @@ module Bxml
     class Root
       # Initializer
       # @param tag [String] Name of the XML element.
-      # @param nested_verbs [Array<Verb>] XML element children. Defaults to an empty array.
+      # @param nested_verbs [Verb] or [Array<Verb>] XML element children. Defaults to an empty array.
       def initialize(tag, nested_verbs = [])
         @tag = tag
-        @nested_verbs = nested_verbs
+        @nested_verbs = Array(nested_verbs)
       end
 
       # Generate an XML element for the BXML response
@@ -30,12 +30,18 @@ def generate_xml
         xml
       end
 
-      # Add a verb to the nested verbs array
+      # Add a verb or verbs to the nested verbs array
       # @param *nested_verbs [Verb] or [Array<Verb>] Verb or verbs to add to the array.
-      def add_verb(nested_verbs)
+      def add_verbs(nested_verbs)
         @nested_verbs.push(*nested_verbs)
       end
 
+      extend Gem::Deprecate
+      def add_verb(nested_verbs)
+        add_verbs(nested_verbs)
+      end
+      deprecate(:add_verb, 'add_verbs', 2024, 7)
+
       # Return BXML representaion of this response
       # @return [String] The XML response in string format.
       def to_bxml

lib/bandwidth-sdk/models/bxml/verbs/gather.rb

@@ -2,7 +2,7 @@ module Bandwidth
   module Bxml
     class Gather < Bandwidth::Bxml::NestableVerb
       # Initializer
-      # @param audio_verbs [Array] XML element children. Defaults to an empty array. Valid nested audio verbs are: SpeakSentence, PlayAudio.
+      # @param audio_verbs [Verb] or [Array<Verb>] XML element children. Defaults to an empty array. Valid nested audio verbs are: SpeakSentence, PlayAudio.
       # @param attributes [Hash] The attributes to add to the element. Defaults to an empty hash.
       def initialize(audio_verbs = [], attributes = {})
         super('Gather', nil, audio_verbs, attributes)
@@ -32,11 +32,17 @@ def to_bxml
         bxml.gsub(SPEAK_SENTENCE_REGEX) { |text| text.gsub(SSML_REGEX, '<\1>') }
       end
 
-      # Add audio verb/s to the nested verbs array
-      # @param audio_verbs [SpeakSentence] || [PlayAudio] or [Array<SpeakSentence || PlayAudio>] Verb or verbs to add to the array.
-      def add_audio_verb(audio_verbs)
+      # Add audio verb or verbs to the nested verbs array
+      # @param audio_verbs [SpeakSentence] or [PlayAudio] or [Array<SpeakSentence || PlayAudio>] Verb or verbs to add to the array.
+      def add_audio_verbs(audio_verbs)
         @nested_verbs.push(*audio_verbs)
       end
+
+      extend Gem::Deprecate
+      def add_audio_verb(audio_verbs)
+        add_audio_verbs(audio_verbs)
+      end
+      deprecate(:add_audio_verb, 'add_audio_verbs', 2024, 7)
     end
   end
 end

lib/bandwidth-sdk/models/bxml/verbs/start_stream.rb

@@ -2,7 +2,7 @@ module Bandwidth
   module Bxml
     class StartStream < Bandwidth::Bxml::NestableVerb
       # Initializer
-      # @param stream_params [Array] XML element children. Defaults to an empty array. Valid nested stream params are: StreamParam. You may specify up to 12 <StreamParam/> elements nested within a <StartStream> tag.
+      # @param stream_params [Verb] or [Array<Verb>] XML element children. Defaults to an empty array. Valid nested stream params are: StreamParam. You may specify up to 12 <StreamParam/> elements nested within a <StartStream> tag.
       # @param attributes [Hash] The attributes to add to the element. Defaults to an empty hash.
       def initialize(stream_params = [], attributes = {})
         super('StartStream', nil, stream_params, attributes)
@@ -18,11 +18,17 @@ def initialize(stream_params = [], attributes = {})
         }
       end
 
-      # Add stream param/s to the nested verbs array
+      # Add stream param or params to the nested verbs array
       # @param stream_params [StreamParam] or [Array<StreamParam>] Verb or verbs to add to the array.
-      def add_stream_param(stream_params)
+      def add_stream_params(stream_params)
         @nested_verbs.push(*stream_params)
       end
+
+      extend Gem::Deprecate
+      def add_stream_param(stream_params)
+        add_stream_params(stream_params)
+      end
+      deprecate(:add_stream_param, 'add_stream_params', 2024, 7)
     end
   end
 end

lib/bandwidth-sdk/models/bxml/verbs/start_transcription.rb

@@ -2,7 +2,7 @@ module Bandwidth
   module Bxml
     class StartTranscription < Bandwidth::Bxml::NestableVerb
       # Initializer
-      # @param custom_params [Array] XML element children. Defaults to an empty array. Valid nested custom params are: CustomParam. You may specify up to 12 <CustomParam/> elements nested within a <StartTranscription> tag.
+      # @param custom_params [Verb] or [Array<Verb>] XML element children. Defaults to an empty array. Valid nested custom params are: CustomParam. You may specify up to 12 <CustomParam/> elements nested within a <StartTranscription> tag.
       # @param attributes [Hash] The attributes to add to the element. Defaults to an empty hash.
       def initialize(custom_params = [], attributes = {})
         super('StartTranscription', nil, custom_params, attributes)
@@ -19,11 +19,17 @@ def initialize(custom_params = [], attributes = {})
         }
       end
 
-      # Add custom param/s to the nested verbs array
+      # Add custom param or params to the nested verbs array
       # @param custom_params [CustomParam] or [Array<CustomParam>] Verb or verbs to add to the array.
-      def add_custom_param(custom_params)
+      def add_custom_params(custom_params)
         @nested_verbs.push(*custom_params)
       end
+
+      extend Gem::Deprecate
+      def add_custom_param(custom_params)
+        add_custom_params(custom_params)
+      end
+      deprecate(:add_custom_param, 'add_custom_params', 2024, 7)
     end
   end
 end

lib/bandwidth-sdk/models/bxml/verbs/transfer.rb

@@ -2,7 +2,7 @@ module Bandwidth
   module Bxml
     class Transfer < Bandwidth::Bxml::NestableVerb
       # Initializer
-      # @param transfer_to [Array] XML element children. Defaults to an empty array. Valid nested transfer verbs are: PhoneNumber, SipUri.
+      # @param transfer_to [Verb] or [Array<Verb>] XML element children. Defaults to an empty array. Valid nested transfer verbs are: PhoneNumber, SipUri.
       # @param attributes [Hash] The attributes to add to the element. Defaults to an empty hash.
       def initialize(transfer_to = [], attributes = {})
         super('Transfer', nil, transfer_to, attributes)
@@ -24,11 +24,17 @@ def initialize(transfer_to = [], attributes = {})
         }
       end
 
-      # Add transfer recipient/s to the nested verbs array
-      # @param recipients [PhoneNumber] || [SipUri] or [Array<PhoneNumber || SipUri>] Verb or verbs to add to the array.
-      def add_transfer_recipient(recipients)
+      # Add transfer recipient or recipients to the nested verbs array
+      # @param recipients [PhoneNumber] or [SipUri] or [Array<PhoneNumber || SipUri>] Verb or verbs to add to the array.
+      def add_transfer_recipients(recipients)
         @nested_verbs.push(*recipients)
       end
+
+      extend Gem::Deprecate
+      def add_transfer_recipient(recipients)
+        add_transfer_recipients(recipients)
+      end
+      deprecate(:add_transfer_recipient, 'add_transfer_recipients', 2024, 7)
     end
   end
 end

spec/models/bxml/bxml_spec.rb

@@ -1,13 +1,38 @@
 # Unit tests for Bandwidth::Bxml::Bxml
 describe 'Bandwidth::Bxml::Bxml' do
   let(:instance) { Bandwidth::Bxml::Bxml.new }
+  let(:pause_recording) { Bandwidth::Bxml::PauseRecording.new }
 
   describe 'test an instance of Bxml' do
     it 'validates instance of Bxml' do
       expect(instance).to be_instance_of(Bandwidth::Bxml::Bxml)
       expect(instance).to be_a(Bandwidth::Bxml::Root)
     end
 
+    it 'test initializing with a single nested verb' do
+      instance = Bandwidth::Bxml::Bxml.new(pause_recording)
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Bxml>\n  <PauseRecording/>\n</Bxml>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
+    it 'test initializing with multiple nested verbs' do
+      instance = Bandwidth::Bxml::Bxml.new([pause_recording, pause_recording])
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Bxml>\n  <PauseRecording/>\n  <PauseRecording/>\n</Bxml>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
+    it 'test adding a single verb to the Bxml instance' do
+      instance.add_verbs(pause_recording)
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Bxml>\n  <PauseRecording/>\n</Bxml>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
+    it 'test adding multiple verbs to the Bxml instance' do
+      instance.add_verbs([pause_recording, pause_recording])
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Bxml>\n  <PauseRecording/>\n  <PauseRecording/>\n</Bxml>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
     it 'test the to_bxml method of the Bxml instance' do
       expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Bxml/>\n"
       expect(instance.to_bxml).to eq(expected)

spec/models/bxml/response_spec.rb

@@ -1,13 +1,38 @@
 # Unit tests for Bandwidth::Bxml::Response
 describe 'Bandwidth::Bxml::Response' do
   let(:instance) { Bandwidth::Bxml::Response.new }
+  let(:pause_recording) { Bandwidth::Bxml::PauseRecording.new }
 
   describe 'test an instance of Response' do
     it 'validates instance of Response' do
       expect(instance).to be_instance_of(Bandwidth::Bxml::Response)
       expect(instance).to be_a(Bandwidth::Bxml::Root)
     end
 
+    it 'test initializing with a single nested verb' do
+      instance = Bandwidth::Bxml::Response.new(pause_recording)
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n  <PauseRecording/>\n</Response>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
+    it 'test initializing with multiple nested verbs' do
+      instance = Bandwidth::Bxml::Response.new([pause_recording, pause_recording])
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n  <PauseRecording/>\n  <PauseRecording/>\n</Response>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
+    it 'test adding a single verb to the Response instance' do
+      instance.add_verbs(pause_recording)
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n  <PauseRecording/>\n</Response>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
+    it 'test adding multiple verbs to the Response instance' do
+      instance.add_verbs([pause_recording, pause_recording])
+      expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n  <PauseRecording/>\n  <PauseRecording/>\n</Response>\n"
+      expect(instance.to_bxml).to eq(expected)
+    end
+
     it 'test the to_bxml method of the Response instance' do
       expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response/>\n"
       expect(instance.to_bxml).to eq(expected)

spec/models/bxml/verbs/gather_spec.rb

@@ -42,7 +42,7 @@
   let (:speak_sentence) { Bandwidth::Bxml::SpeakSentence.new('<lang xml:lang="es-MX">Hola</lang>ruby speak sentence <emphasis>SSML test</emphasis>') }
 
   let(:instance) { Bandwidth::Bxml::Gather.new([], initial_attributes) }
-  let(:instance_nested) { Bandwidth::Bxml::Gather.new([play_audio], initial_attributes) }
+  let(:instance_nested) { Bandwidth::Bxml::Gather.new(play_audio, initial_attributes) }
 
   describe 'test an instance of Gather' do
     it 'validates instance of Gather' do
@@ -75,11 +75,11 @@
 
     it 'tests the add_verb method of the nested Gather instance' do
       expected_single = "\n<Gather gatherUrl=\"https://initial.com\" gatherMethod=\"POST\" gatherFallbackUrl=\"https://initial.com\" gatherFallbackMethod=\"POST\" username=\"initial_username\" password=\"initial_password\" fallbackUsername=\"initial_fallback_username\" fallbackPassword=\"initial_fallback_password\" tag=\"initial_tag\" terminatingDigits=\"5\" maxDigits=\"5\" interDigitTimeout=\"5\" firstDigitTimeout=\"5\" repeatCount=\"5\">\n  <PlayAudio>https://audio.url/audio1.wav</PlayAudio>\n  <SpeakSentence><lang xml:lang=\"es-MX\">Hola</lang>ruby speak sentence <emphasis>SSML test</emphasis></SpeakSentence>\n</Gather>\n"
-      instance_nested.add_audio_verb(speak_sentence)
+      instance_nested.add_audio_verbs(speak_sentence)
       expect(instance_nested.to_bxml).to eq(expected_single)
 
       expected_multiple = "\n<Gather gatherUrl=\"https://initial.com\" gatherMethod=\"POST\" gatherFallbackUrl=\"https://initial.com\" gatherFallbackMethod=\"POST\" username=\"initial_username\" password=\"initial_password\" fallbackUsername=\"initial_fallback_username\" fallbackPassword=\"initial_fallback_password\" tag=\"initial_tag\" terminatingDigits=\"5\" maxDigits=\"5\" interDigitTimeout=\"5\" firstDigitTimeout=\"5\" repeatCount=\"5\">\n  <PlayAudio>https://audio.url/audio1.wav</PlayAudio>\n  <SpeakSentence><lang xml:lang=\"es-MX\">Hola</lang>ruby speak sentence <emphasis>SSML test</emphasis></SpeakSentence>\n  <SpeakSentence><lang xml:lang=\"es-MX\">Hola</lang>ruby speak sentence <emphasis>SSML test</emphasis></SpeakSentence>\n  <PlayAudio>https://audio.url/audio1.wav</PlayAudio>\n</Gather>\n"
-      instance_nested.add_audio_verb([speak_sentence, play_audio])
+      instance_nested.add_audio_verbs([speak_sentence, play_audio])
       expect(instance_nested.to_bxml).to eq(expected_multiple)
     end
   end

spec/models/bxml/verbs/start_stream_spec.rb

@@ -28,7 +28,7 @@
   let (:stream_param_2) { Bandwidth::Bxml::StreamParam.new({ name: 'stream_param_name_2', value: 'stream_param_value_2' }) }
 
   let(:instance) { Bandwidth::Bxml::StartStream.new([], initial_attributes) }
-  let(:instance_nested) { Bandwidth::Bxml::StartStream.new([stream_param_1], initial_attributes) }
+  let(:instance_nested) { Bandwidth::Bxml::StartStream.new(stream_param_1, initial_attributes) }
 
   describe 'test an instance of StartStream' do
     it 'validates instance of StartStream' do
@@ -61,11 +61,11 @@
 
     it 'tests the add_stream_param method of the nested StartStream instance' do
       expected_single = "\n<StartStream name=\"initial_name\" tracks=\"inbound\" destination=\"https://initial.com\" streamEventUrl=\"https://initial.com\" streamEventMethod=\"POST\" username=\"initial_username\" password=\"initial_password\">\n  <StreamParam name=\"stream_param_name_1\" value=\"stream_param_value_1\"/>\n  <StreamParam name=\"stream_param_name_2\" value=\"stream_param_value_2\"/>\n</StartStream>\n"
-      instance_nested.add_stream_param(stream_param_2)
+      instance_nested.add_stream_params(stream_param_2)
       expect(instance_nested.to_bxml).to eq(expected_single)
 
       expected_multiple = "\n<StartStream name=\"initial_name\" tracks=\"inbound\" destination=\"https://initial.com\" streamEventUrl=\"https://initial.com\" streamEventMethod=\"POST\" username=\"initial_username\" password=\"initial_password\">\n  <StreamParam name=\"stream_param_name_1\" value=\"stream_param_value_1\"/>\n  <StreamParam name=\"stream_param_name_2\" value=\"stream_param_value_2\"/>\n  <StreamParam name=\"stream_param_name_2\" value=\"stream_param_value_2\"/>\n  <StreamParam name=\"stream_param_name_2\" value=\"stream_param_value_2\"/>\n</StartStream>\n"
-      instance_nested.add_stream_param([stream_param_2, stream_param_2])
+      instance_nested.add_stream_params([stream_param_2, stream_param_2])
       expect(instance_nested.to_bxml).to eq(expected_multiple)
     end
   end

spec/models/bxml/verbs/start_transcription_spec.rb

@@ -30,7 +30,7 @@
   let (:custom_param_2) { Bandwidth::Bxml::CustomParam.new({ name: 'custom_param_name_2', value: 'custom_param_value_2' }) }
 
   let(:instance) { Bandwidth::Bxml::StartTranscription.new([], initial_attributes) }
-  let(:instance_nested) { Bandwidth::Bxml::StartTranscription.new([custom_param_1], initial_attributes) }
+  let(:instance_nested) { Bandwidth::Bxml::StartTranscription.new(custom_param_1, initial_attributes) }
 
   describe 'test an instance of StartTranscription' do
     it 'validates instance of StartTranscription' do
@@ -63,11 +63,11 @@
 
     it 'tests the add_custom_param method of the nested StartTranscription instance' do
       expected_single = "\n<StartTranscription name=\"initial_name\" tracks=\"inbound\" transcriptionEventUrl=\"https://initial.com\" transcriptionEventMethod=\"POST\" username=\"initial_username\" password=\"initial_password\" destination=\"https://initial.com\" stabilized=\"true\">\n  <CustomParam name=\"custom_param_name_1\" value=\"custom_param_value_1\"/>\n  <CustomParam name=\"custom_param_name_2\" value=\"custom_param_value_2\"/>\n</StartTranscription>\n"
-      instance_nested.add_custom_param(custom_param_2)
+      instance_nested.add_custom_params(custom_param_2)
       expect(instance_nested.to_bxml).to eq(expected_single)
 
       expected_multiple = "\n<StartTranscription name=\"initial_name\" tracks=\"inbound\" transcriptionEventUrl=\"https://initial.com\" transcriptionEventMethod=\"POST\" username=\"initial_username\" password=\"initial_password\" destination=\"https://initial.com\" stabilized=\"true\">\n  <CustomParam name=\"custom_param_name_1\" value=\"custom_param_value_1\"/>\n  <CustomParam name=\"custom_param_name_2\" value=\"custom_param_value_2\"/>\n  <CustomParam name=\"custom_param_name_2\" value=\"custom_param_value_2\"/>\n  <CustomParam name=\"custom_param_name_2\" value=\"custom_param_value_2\"/>\n</StartTranscription>\n"
-      instance_nested.add_custom_param([custom_param_2, custom_param_2])
+      instance_nested.add_custom_params([custom_param_2, custom_param_2])
       expect(instance_nested.to_bxml).to eq(expected_multiple)
     end
   end