vonage 7.2.1 → 7.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc5bab327c1d3fb5c689bdd5c8958e3441332ad3e498da73bd1a82a67df6aaf9
-  data.tar.gz: 9c9964bd8cfc08afd014ec8f9af1e4ba1f3c3a58b9c53b223c62e64a2f86bfa2
+  metadata.gz: 8a1f06b8ae136e6b1f143c728880b50a76bc977e1126eee9d905dea632d70c8f
+  data.tar.gz: 457cca5f4c829ccd4a63365935b3b119d49464745f052ede7f973eac38fbcfdf
 SHA512:
-  metadata.gz: b6d915e490cbe3908dc5d62bfc3b2cf245611fcc5bbcd27b10a0c8af41fbc356f2322bd6c98c0fa46623e2a48dffef0ea1f5b831c059d9dd85380f0678eb03bf
-  data.tar.gz: e2abd40a4876cb74772884aaddedfd73726282939a9f1ef361684ff67963155cbe79374571e01a022270060c91a185180e384cf82a74d1ea0fa17a2a1ee3646b
+  metadata.gz: 30c2ff5cda3bf5132abed93e12f05113c523301f5b1aab5040a9c9f2f82d0baea9a0a0033f500376dc013a57e384fe01bbc83fa89eac31e208c8baab5700906d
+  data.tar.gz: 42586b2544c38fc72233a01af85130cf5d8e6a7b5385d096cb7fa5e74fec189a8977f051f69a760dcf1264247edf8710e59b00cad4e259207cdb69cd7d686c95

data/README.md

@@ -1,6 +1,7 @@
 # Vonage Server SDK for Ruby
 
-[![Gem Version](https://badge.fury.io/rb/vonage.svg)](https://badge.fury.io/rb/vonage) [![Coverage Status](https://github.com/Vonage/vonage-ruby-sdk/workflows/CI/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/Vonage/vonage-ruby-sdk/badge.svg?branch=master)](https://coveralls.io/github/Vonage/vonage-ruby-sdk?branch=master)
+[![Gem Version](https://badge.fury.io/rb/vonage.svg)](https://badge.fury.io/rb/vonage) ![Coverage Status](https://github.com/Vonage/vonage-ruby-sdk/workflows/CI/badge.svg) [![codecov](https://codecov.io/gh/Vonage/vonage-ruby-sdk/branch/7.x/graph/badge.svg?token=FKW6KL532P)](https://codecov.io/gh/Vonage/vonage-ruby-sdk)
+
 
 <img src="https://developer.nexmo.com/assets/images/Vonage_Nexmo.svg" height="48px" alt="Nexmo is now known as Vonage" />
 
@@ -14,6 +15,8 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
     * [Overriding the default hosts](#overriding-the-default-hosts)
     * [JWT authentication](#jwt-authentication)
     * [Webhook signatures](#webhook-signatures)
+    * [Pagination](#pagination)
+    * [NCCO Builder](#ncco-builder)
 * [Documentation](#documentation)
 * [Frequently Asked Questions](#frequently-asked-questions)
     * [Supported APIs](#supported-apis)
@@ -148,6 +151,48 @@ Alternatively you can set the `VONAGE_SIGNATURE_SECRET` environment variable.
 
 Note: you'll need to contact support@nexmo.com to enable message signing on your account.
 
+## Pagination
+
+Vonage APIs paginate list requests. This means that if a collection is requested that is larger than the API default, the API will return the first page of items in the collection. The Ruby SDK provides an `auto_advance` parameter that will traverse through the pages and return all the results in one response object.
+
+The `auto_advance` parameter is set to a default of `true` for the following APIs:
+
+* [Account API](https://developer.nexmo.com/api/developer/account)
+* [Application API](https://developer.nexmo.com/api/application.v2)
+* [Conversation API](https://developer.nexmo.com/api/conversation)
+* [Voice API](https://developer.nexmo.com/api/voice)
+
+To modify the `auto_advance` behavior you can specify it in your method:
+
+```ruby
+client.applications.list(auto_advance: false)
+```
+
+## NCCO Builder
+
+The Vonage Voice API accepts instructions via JSON objects called NCCOs. Each NCCO can be made up multiple actions that are executed in the order they are written. The Vonage API Developer Portal contains an [NCCO Reference](https://developer.vonage.com/voice/voice-api/ncco-reference) with instructions and information on all the parameters possible.
+
+The SDK includes an NCCO builder that you can use to build NCCOs for your Voice API methods.
+
+For example, to build `talk` and `input` NCCO actions and then combine them into a single NCCO you would do the following:
+
+```ruby
+talk = Vonage::Voice::Ncco.talk(text: 'Hello World!')
+input = Vonage::Voice::Ncco.input(type: ['dtmf'], dtmf: { bargeIn: true })
+ncco = Vonage::Voice::Ncco.build(talk, input)
+
+# => [{:action=>"talk", :text=>"Hello World!"}, {:action=>"input", :type=>["dtmf"], :dtmf=>{:bargeIn=>true}}]
+```
+
+Once you have the constructed NCCO you can then use it in a Voice API request:
+
+```ruby
+response = client.voice.create({
+  to: [{type: 'phone', number: '14843331234'}],
+  from: {type: 'phone', number: '14843335555'},
+  ncco: ncco
+})
+```
 
 ## Documentation
 

data/lib/vonage/abstract_authentication.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 
 module Vonage
   class AbstractAuthentication

data/lib/vonage/applications/list_response.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 
 class Vonage::Applications::ListResponse < Vonage::Response
   include Enumerable

data/lib/vonage/applications.rb

@@ -69,14 +69,22 @@ module Vonage
     # @option params [Integer] :page
     #   The current page number (starts at 1).
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.
     # @param [Hash] params
-    #
+    #  
     # @return [ListResponse]
     #
     # @see https://developer.nexmo.com/api/application.v2#listApplication
     #
-    sig { params(params: T.nilable(T::Hash[Symbol, Integer])).returns(Vonage::Response) }
-    def list(params = nil)
+    sig { params(
+      params: T.nilable(T::Hash[Symbol, Integer]), auto_advance: T::Boolean).returns(Vonage::Applications::ListResponse) }
+    def list(params = nil, auto_advance = true)
+      if params && !params.key?(:auto_advance)
+        params.merge!(auto_advance: true)
+      end
+
       request('/v2/applications', params: params, response_class: ListResponse)
     end
 

data/lib/vonage/basic.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 
 module Vonage
   class Basic < AbstractAuthentication

data/lib/vonage/bearer_token.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 # frozen_string_literal: true
 
 module Vonage

data/lib/vonage/config.rb

@@ -200,7 +200,7 @@ module Vonage
 
     protected
 
-    sig { params(name: Symbol, value: T.nilable(T.untyped)).void }
+    sig { params(name: Symbol, value: T.untyped).void }
     def write_attribute(name, value)
       public_send(:"#{name}=", value)
     end

data/lib/vonage/conversations/events.rb

@@ -36,12 +36,16 @@ module Vonage
     #
     # @param [String] conversation_id
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.
+    #    
     # @return [Response]
     #
     # @see https://developer.nexmo.com/api/conversation#getEvents
     #
-    def list(conversation_id)
-      request('/beta/conversations/' + conversation_id + '/events')
+    def list(conversation_id, params = nil, auto_advance = true)
+      request('/beta/conversations/' + conversation_id + '/events', params: params)
     end
 
     # Retrieve an event.

data/lib/vonage/conversations/legs.rb

@@ -7,12 +7,16 @@ module Vonage
 
     # List legs.
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.     
+    #
     # @return [Response]
     #
     # @see https://developer.nexmo.com/api/conversation#listLegs
     #
-    def list
-      request('/beta/legs')
+    def list(params = nil, auto_advance = true)
+      request('/beta/legs', params: params)
     end
 
     # Delete a leg.

data/lib/vonage/conversations/members.rb

@@ -47,12 +47,16 @@ module Vonage
     #
     # @param [String] conversation_id
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.
+    #
     # @return [Response]
     #
     # @see https://developer.nexmo.com/api/conversation#getMembers
     #
-    def list(conversation_id)
-      request('/beta/conversations/' + conversation_id + '/members')
+    def list(conversation_id, params = nil, auto_advance = true)
+      request('/beta/conversations/' + conversation_id + '/members', params: params)
     end
 
     # Retrieve a member.

data/lib/vonage/conversations/users.rb

@@ -31,12 +31,16 @@ module Vonage
 
     # List users.
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.
+    #
     # @return [Response]
     #
     # @see https://developer.nexmo.com/api/conversation#getUsers
     #
-    def list
-      request('/beta/users')
+    def list(params = nil, auto_advance = true)
+      request('/beta/users', params: params)
     end
 
     # Retrieve a user.

data/lib/vonage/conversations.rb

@@ -60,14 +60,21 @@ module Vonage
     # @option params ['asc', 'desc'] :order
     #   Return the records in ascending or descending order.
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.
     # @param [Hash, nil] params
-    #
+    #  
     # @return [Response]
     #
     # @see https://developer.nexmo.com/api/conversation#replaceConversation
     #
-    sig { params(params: T.nilable(T::Hash[Symbol, T.untyped])).returns(Vonage::Response) }
-    def list(params = nil)
+    sig { params(params: T.nilable(T::Hash[Symbol, T.untyped]), auto_advance: T::Boolean).returns(Vonage::Response) }
+    def list(params = nil, auto_advance = true)
+      if params && !params.key?(:auto_advance)
+        params.merge!(auto_advance: true)
+      end
+      
       request('/beta/conversations', params: params)
     end
 

data/lib/vonage/entity.rb

@@ -36,8 +36,6 @@ module Vonage
 
     attr_reader :attributes
 
-    protected :attributes
-
     def each_pair(&block)
       return to_enum(:each_pair) unless block
 

data/lib/vonage/form_data.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 
 module Vonage
   module FormData

data/lib/vonage/gsm7.rb

@@ -1,11 +1,14 @@
-# typed: ignore
+# typed: strong
 
 module Vonage
   module GSM7
+    extend T::Sig
+    
     CHARACTERS = "\n\f\r !\"\#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_abcdefghijklmnopqrstuvwxyz{|}~ ¡£¤¥§¿ÄÅÆÉÑÖØÜßàäåæçèéìñòöøùüΓΔΘΛΞΠΣΦΨΩ€"
 
     REGEXP = /\A[#{Regexp.escape(CHARACTERS)}]*\z/
 
+    sig { params(string: T.nilable(String)).returns(T.nilable(Integer)) }
     def self.encoded?(string)
       REGEXP =~ string
     end

data/lib/vonage/json.rb

@@ -6,7 +6,7 @@ module Vonage
   module JSON
     extend T::Sig
 
-    sig { params(http_request: T.any(Net::HTTP::Put, Net::HTTP::Post), params: T::Hash[Symbol, T.untyped]).void }
+    sig { params(http_request: T.any(Net::HTTP::Put, Net::HTTP::Post, Net::HTTP::Get), params: T::Hash[Symbol, T.untyped]).void }
     def self.update(http_request, params)
       http_request['Content-Type'] = 'application/json'
       http_request.body = ::JSON.generate(params)

data/lib/vonage/jwt.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 require 'securerandom'
 require 'openssl'

data/lib/vonage/namespace.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 # frozen_string_literal: true
 require 'net/http'
 require 'json'
@@ -47,41 +47,47 @@ module Vonage
     end
 
     protected
+    # :nocov:
 
     Get = Net::HTTP::Get
     Put = Net::HTTP::Put
     Post = Net::HTTP::Post
     Delete = Net::HTTP::Delete
 
-    def request(path, params: nil, type: Get, response_class: Response, &block)
-      uri = URI('https://' + @host + path)
-
-      params ||= {}
-
+    def build_request(path:, type: Get, params: {})
       authentication = self.class.authentication.new(@config)
       authentication.update(params)
 
-      unless type::REQUEST_HAS_BODY || params.empty?
+      uri = URI('https://' + @host + path)
+      unless type.const_get(:REQUEST_HAS_BODY) || params.empty?
         uri.query = Params.encode(params)
       end
 
+      # Set BasicAuth if neeeded
       authentication.update(uri)
 
-      message = type.new(uri)
-
-      message['User-Agent'] = UserAgent.string(@config.app_name, @config.app_version)
+      # instantiate request
+      request = type.new(uri)
 
+      # set headers
+      request['User-Agent'] = UserAgent.string(@config.app_name, @config.app_version)
       self.class.request_headers.each do |key, value|
-        message[key] = value
+        request[key] = value
       end
 
-      authentication.update(message)
+      # Set BearerToken if needed
+      authentication.update(request)
+
+      # set body
+      self.class.request_body.update(request, params) if type.const_get(:REQUEST_HAS_BODY)
 
-      self.class.request_body.update(message, params) if type::REQUEST_HAS_BODY
+      request
+    end
 
-      logger.log_request_info(message)
+    def make_request!(request, &block)
+      logger.log_request_info(request)
 
-      response = @http.request(message, &block)
+      response = @http.request(request, &block)
 
       logger.log_response_info(response, @host)
 
@@ -89,7 +95,105 @@ module Vonage
 
       logger.debug(response.body) if response.body
 
-      parse(response, response_class)
+      response
+    end
+
+    def request(path, params: nil, type: Get, response_class: Response, &block)
+      auto_advance = !params.nil? && params.key?(:auto_advance) ? params[:auto_advance] : false
+
+      params = params.tap { |params| params.delete(:auto_advance) } if !params.nil? && params.key?(:auto_advance)
+
+      request = build_request(path: path, params: params || {}, type: type)
+
+      response = make_request!(request, &block)
+
+      if auto_advance
+        iterable_request(path, response: response, response_class: response_class, &block)
+      else
+        return if block
+
+        parse(response, response_class)
+      end
+    end
+
+    def iterable_request(path, response: nil, response_class: nil, &block)
+      json_response = ::JSON.parse(response.body)
+      response = parse(response, response_class)
+      remainder = remaining_count(json_response)
+
+      while remainder > 0
+        params = { page_size: json_response['page_size'] }
+
+        if json_response['record_index'] && json_response['record_index'] == 0
+          params[:record_index] = json_response['page_size']
+        elsif json_response['record_index'] && json_response['record_index'] != 0
+          params[:record_index] = (json_response['record_index'] + json_response['page_size'])
+        end
+
+        if json_response['total_pages']
+          params[:page] = json_response['page'] + 1
+        end
+
+        request = build_request(path: path, type: Get, params: params)
+
+        # Make request...
+        paginated_response = make_request!(request)
+        next_response = parse(paginated_response, response_class)
+        json_response = ::JSON.parse(paginated_response.body)
+        remainder = remaining_count(json_response)
+
+        if response.respond_to?('_embedded')
+          collection_name = collection_name(response['_embedded'])
+          response['_embedded'][collection_name].push(*next_response['_embedded'][collection_name])
+        else
+          response[collection_name(response)].push(*next_response[collection_name(next_response)])
+        end
+      end
+
+      response
+    end
+
+    def remaining_count(params)
+      if params.key?('total_pages')
+        params['total_pages'] - params['page']
+      elsif params.key?('count')
+        params['count'] - (params['record_index'] == 0 ? params['page_size'] : (params['record_index'] + params['page_size']))
+      else
+        0
+      end
+    end
+
+    def collection_name(params)
+      @collection_name ||= case
+        when params.respond_to?('calls')
+          'calls'
+        when params.respond_to?('users')
+          'users'
+        when params.respond_to?('legs')
+          'legs'
+        when params.respond_to?('data')
+          'data'
+        when params.respond_to?('conversations')
+          'conversations'
+        when params.respond_to?('applications')
+          'applications'
+        when params.respond_to?('records')
+          'records'
+        when params.respond_to?('reports')
+          'reports'
+        when params.respond_to?('networks')
+          'networks'
+        when params.respond_to?('countries')
+          'countries'
+        when params.respond_to?('media')
+          'media'
+        when params.respond_to?('numbers')
+          'numbers'
+        when params.respond_to?('events')
+          'events'
+        else
+          params.entity.attributes.keys[0].to_s
+        end
     end
 
     def parse(response, response_class)
@@ -115,4 +219,5 @@ module Vonage
   end
 
   private_constant :Namespace
+  # :nocov:
 end

data/lib/vonage/numbers/list_response.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 
 class Vonage::Numbers::ListResponse < Vonage::Response
   include Enumerable

data/lib/vonage/numbers/response.rb

@@ -1,8 +1,8 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 class Vonage::Numbers::Response < Vonage::Response
   def success?
-    error_code == '200'
+    T.unsafe(self).error_code == '200'
   end
 end

data/lib/vonage/numbers.rb

@@ -40,7 +40,11 @@ module Vonage
     #
     # @option params [Integer] :index
     #   Page index.
-    #
+    # 
+    # @option params [Boolean] :auto_advance
+    #   Set this to `true` to auto-advance through all the pages in the record
+    #   and collect all the data. The default is `false`.
+    # 
     # @param [Hash] params
     #
     # @return [ListResponse]
@@ -85,6 +89,10 @@ module Vonage
     # @option params [Integer] :index
     #   Page index.
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `true` to auto-advance through all the pages in the record
+    #   and collect all the data. The default is `false`.
+    #  
     # @param [Hash] params
     #
     # @return [ListResponse]

data/lib/vonage/params.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 # frozen_string_literal: true
 require 'cgi'
 

data/lib/vonage/response.rb

@@ -9,6 +9,7 @@ module Vonage
     end
 
     attr_reader :http_response
+    attr_reader :entity
 
     def respond_to_missing?(name, include_private = false)
       return super if @entity.nil?

data/lib/vonage/secrets/list_response.rb

@@ -1,4 +1,4 @@
-# typed: ignore
+# typed: true
 
 class Vonage::Secrets::ListResponse < Vonage::Response
   include Enumerable

data/lib/vonage/secrets.rb

@@ -38,12 +38,16 @@ module Vonage
     #     puts "#{item.created_at} #{item.id}"
     #   end
     #
+    # @option params [Boolean] :auto_advance
+    #   Set this to `false` to not auto-advance through all the pages in the record
+    #   and collect all the data. The default is `true`.
+    #
     # @return [ListResponse]
     #
     # @see https://developer.nexmo.com/api/account#retrieveAPISecrets
     #
-    def list
-      request('/accounts/' + account_id + '/secrets', response_class: ListResponse)
+    def list(params = nil, auto_advance = true)
+      request('/accounts/' + account_id + '/secrets', params: params, response_class: ListResponse)
     end
 
     # Retrieve one API Secret.

data/lib/vonage/user_agent.rb

@@ -1,8 +1,11 @@
-# typed: ignore
+# typed: strong
 # frozen_string_literal: true
 
 module Vonage
   module UserAgent
+    extend T::Sig
+
+    sig { params(app_name: T.nilable(String), app_version: T.nilable(String)).returns(String) }
     def self.string(app_name, app_version)
       identifiers = []
       identifiers << 'vonage-ruby/' + VERSION

data/lib/vonage/verify.rb

@@ -42,7 +42,7 @@ module Vonage
     #   Use this parameter to explicitly control the language, accent and gender used for the Verify request.
     #
     # @option params [Integer] :pin_expiry
-    #   How log the generated verification code is valid for, in seconds.
+    #   How long the generated verification code is valid for, in seconds.
     #   When you specify both **:pin_expiry** and **:next_event_wait** then **:pin_expiry** must be an integer multiple of **:next_event_wait** otherwise **:pin_expiry** is defaulted to equal **:next_event_wait**.
     #   See [changing the event timings](https://developer.nexmo.com/verify/guides/changing-default-timings).
     #

data/lib/vonage/version.rb

@@ -1,5 +1,5 @@
 # typed: strong
 
 module Vonage
-  VERSION = '7.2.1'
+  VERSION = '7.4.1'
 end