SWI-4292 Update add_verb Methods (#125)

* SWI-4292 Update `add_verb` Methods

* add deprecation warnings

Author: ckoegel

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)