nexmo 5.8.0 → 5.9.0

data/lib/nexmo/errors/error.rb

@@ -1,31 +1,4 @@
-# frozen_string_literal: true
-require 'json'
-
 module Nexmo
   class Error < StandardError
-    def self.parse(response) # :nodoc:
-      exception_class = case response
-        when Net::HTTPUnauthorized
-          AuthenticationError
-        when Net::HTTPClientError
-          ClientError
-        when Net::HTTPServerError
-          ServerError
-        else
-          Error
-        end
-
-      message = if content_type = response['Content-Type']
-        case content_type.split(';').first
-        when 'application/problem+json'
-          Problem.parse(response.body)
-        when 'application/json'
-          hash = ::JSON.parse(response.body)
-          hash['error_title']
-        end
-      end
-
-      exception_class.new(message)
-    end
   end
 end

data/lib/nexmo/form_data.rb

@@ -1,7 +1,9 @@
 module Nexmo
-  module FormData # :nodoc:
+  module FormData
     def self.update(http_request, params)
       http_request.form_data = params
     end
   end
+
+  private_constant :FormData
 end

data/lib/nexmo/http.rb

@@ -2,7 +2,7 @@
 require 'net/http'
 
 module Nexmo
-  module HTTP # :nodoc:
+  module HTTP
     class Options
       def initialize(hash)
         @hash = hash || {}
@@ -29,4 +29,6 @@ module Nexmo
       end
     end
   end
+
+  private_constant :HTTP
 end

data/lib/nexmo/json.rb

@@ -2,10 +2,12 @@
 require 'json'
 
 module Nexmo
-  module JSON # :nodoc:
+  module JSON
     def self.update(http_request, params)
       http_request['Content-Type'] = 'application/json'
       http_request.body = ::JSON.generate(params)
     end
   end
+
+  private_constant :JSON
 end

data/lib/nexmo/jwt.rb

@@ -5,6 +5,31 @@ require 'jwt'
 
 module Nexmo
   module JWT
+    # Generate an encoded JSON Web Token.
+    #
+    # By default the Nexmo Ruby SDK generates a short lived JWT per request.
+    #
+    # To generate a long lived JWT for multiple requests or to specify JWT claims
+    # directly call {Nexmo::JWT.generate} to generate a token, and set the token
+    # attribute on the client object.
+    #
+    # @example
+    #   claims = {
+    #     application_id: application_id,
+    #     nbf: 1483315200,
+    #     exp: 1514764800,
+    #     iat: 1483228800
+    #   }
+    #
+    #   private_key = File.read('path/to/private.key')
+    #
+    #   client.token = Nexmo::JWT.generate(claims, private_key)
+    #
+    # @param [Hash] payload
+    # @param [String, OpenSSL::PKey::RSA] private_key
+    #
+    # @return [String]
+    #
     def self.generate(payload, private_key)
       payload[:iat] = iat = Time.now.to_i unless payload.key?(:iat) || payload.key?('iat')
       payload[:exp] = iat + 60 unless payload.key?(:exp) || payload.key?('exp')

data/lib/nexmo/keys.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Nexmo
-  module Keys # :nodoc:
+  module Keys
     if {}.respond_to?(:transform_keys)
       def hyphenate(hash)
         hash.transform_keys { |k| hyphenate_key(k) }
@@ -42,4 +42,6 @@ module Nexmo
       ATTRIBUTE_KEYS[k]
     end
   end
+
+  private_constant :Keys
 end

data/lib/nexmo/logger.rb

@@ -3,7 +3,7 @@ require 'logger'
 require 'forwardable'
 
 module Nexmo
-  class Logger # :nodoc:
+  class Logger
     def initialize(logger)
       @logger = logger || ::Logger.new(nil)
     end
@@ -45,4 +45,6 @@ module Nexmo
       fields.join(' ')
     end
   end
+
+  private_constant :Logger
 end

data/lib/nexmo/namespace.rb

@@ -3,7 +3,7 @@ require 'net/http'
 require 'json'
 
 module Nexmo
-  class Namespace # :nodoc:
+  class Namespace
     def initialize(client)
       @client = client
 
@@ -102,8 +102,10 @@ module Nexmo
           response
         end
       else
-        raise Error.parse(response)
+        raise Errors.parse(response)
       end
     end
   end
+
+  private_constant :Namespace
 end

data/lib/nexmo/number_insight.rb

@@ -2,18 +2,120 @@
 
 module Nexmo
   class NumberInsight < Namespace
+    # Provides basic number insight information about a number.
+    #
+    # @example
+    #   response = client.number_insight.basic(number: '447700900000')
+    #
+    # @option params [required, String] :number
+    #   A single phone number that you need insight about in national or international format.
+    #
+    # @option params [String] :country
+    #   If a number does not have a country code or is uncertain, set the two-character country code.
+    #   This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US.
+    #   If you set country and number is already in E.164 format, country must match the country code in number.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/number-insight#getNumberInsightBasic
+    #
     def basic(params)
       request('/ni/basic/json', params: params)
     end
 
+    # Provides standard number insight information about a number.
+    #
+    # @example
+    #   response = client.number_insight.standard(number: '447700900000')
+    #
+    # @option params [required, String] :number
+    #   A single phone number that you need insight about in national or international format.
+    #
+    # @option params [String] :country
+    #   If a number does not have a country code or is uncertain, set the two-character country code.
+    #   This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US.
+    #   If you set country and number is already in E.164 format, country must match the country code in number.
+    #
+    # @option params [Boolean] :cnam
+    #   Indicates if the name of the person who owns the phone number should be looked up and returned in the response.
+    #   Set to true to receive phone number owner name in the response.
+    #   This features is available for US numbers only and incurs an additional charge.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/number-insight#getNumberInsightStandard
+    #
     def standard(params)
       request('/ni/standard/json', params: params)
     end
 
+    # Provides advanced number insight information about a number synchronously.
+    #
+    # @example
+    #   response = client.number_insight.advanced(number: '447700900000')
+    #
+    # @option params [required, String] :number
+    #   A single phone number that you need insight about in national or international format.
+    #
+    # @option params [String] :country
+    #   If a number does not have a country code or is uncertain, set the two-character country code.
+    #   This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US.
+    #   If you set country and number is already in E.164 format, country must match the country code in number.
+    #
+    # @option params [Boolean] :cnam
+    #   Indicates if the name of the person who owns the phone number should be looked up and returned in the response.
+    #   Set to true to receive phone number owner name in the response.
+    #   This features is available for US numbers only and incurs an additional charge.
+    #
+    # @option params [String] :ip
+    #   The IP address of the user.
+    #   If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/number-insight#getNumberInsightAdvanced
+    #
     def advanced(params)
       request('/ni/advanced/json', params: params)
     end
 
+    # Provides advanced number insight number information *asynchronously* using the URL specified in the callback parameter.
+    #
+    # @example
+    #   response = client.number_insight.advanced_async(number: '447700900000', callback: webhook_url)
+    #
+    # @option params [required, String] :callback
+    #   The callback URL.
+    #
+    # @option params [required, String] :number
+    #   A single phone number that you need insight about in national or international format.
+    #
+    # @option params [String] :country
+    #   If a number does not have a country code or is uncertain, set the two-character country code.
+    #   This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US.
+    #   If you set country and number is already in E.164 format, country must match the country code in number.
+    #
+    # @option params [Boolean] :cnam
+    #   Indicates if the name of the person who owns the phone number should be looked up and returned in the response.
+    #   Set to true to receive phone number owner name in the response.
+    #   This features is available for US numbers only and incurs an additional charge.
+    #
+    # @option params [String] :ip
+    #   The IP address of the user.
+    #   If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/number-insight#getNumberInsightAsync
+    #
     def advanced_async(params)
       request('/ni/advanced/async/json', params: params)
     end

data/lib/nexmo/numbers.rb

@@ -6,22 +6,177 @@ module Nexmo
 
     self.host = 'rest.nexmo.com'
 
+    # Retrieve all the inbound numbers associated with your Nexmo account.
+    #
+    # @example
+    #   response = client.numbers.list
+    #   response.numbers.each do |item|
+    #     puts "#{item.msisdn} #{item.country} #{item.type}"
+    #   end
+    #
+    # @option params [Integer] :index
+    #   Page index.
+    #
+    # @option params [Integer] :size
+    #   Page size.
+    #
+    # @option params [String] :pattern
+    #   The number pattern you want to search for. Use in conjunction with **:search_pattern**.
+    #
+    # @option params [Integer] :search_pattern
+    #   The strategy you want to use for matching:
+    #   - `0` - Search for numbers that start with **:pattern**
+    #   - `1` - Search for numbers that contain **:pattern**
+    #   - `2` - Search for numbers that end with **:pattern**
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/developer/numbers#getOwnedNumbers
+    #
     def list(params = nil)
       request('/account/numbers', params: params)
     end
 
+    # Retrieve inbound numbers that are available for the specified country.
+    #
+    # @example
+    #   response = client.numbers.search(country: 'GB')
+    #   response.numbers.each do |item|
+    #     puts "#{item.msisdn} #{item.type} #{item.cost}"
+    #   end
+    #
+    # @option params [required, String] :country
+    #   The two character country code in ISO 3166-1 alpha-2 format.
+    #
+    # @option params [String] :type
+    #   Set this parameter to filter the type of number, such as mobile or landline.
+    #
+    # @option params [String] :pattern
+    #   The number pattern you want to search for.
+    #   Use in conjunction with **:search_pattern**.
+    #
+    # @option params [Integer] :search_pattern
+    #   The strategy you want to use for matching:
+    #   - `0` - Search for numbers that start with **:pattern**
+    #   - `1` - Search for numbers that contain **:pattern**
+    #   - `2` - Search for numbers that end with **:pattern**
+    #
+    # @option params [String] :features
+    #   Available features are `SMS` and `VOICE`.
+    #   To look for numbers that support both, use a comma-separated value: `SMS,VOICE`.
+    #
+    # @option params [Integer] :size
+    #   Page size.
+    #
+    # @option params [Integer] :index
+    #   Page index.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/developer/numbers#getAvailableNumbers
+    #
     def search(params)
       request('/number/search', params: params)
     end
 
+    # Request to purchase a specific inbound number.
+    #
+    # @example
+    #   response = client.numbers.buy(country: 'GB', msisdn: '447700900000')
+    #
+    # @option params [required, String] :country
+    #   The two character country code in ISO 3166-1 alpha-2 format.
+    #
+    # @option params [required, String] :msisdn
+    #   An available inbound virtual number.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/developer/numbers#buyANumber
+    #
     def buy(params)
       request('/number/buy', params: params, type: Post)
     end
 
+    # Cancel your subscription for a specific inbound number.
+    #
+    # @example
+    #   response = client.numbers.cancel(country: 'GB', msisdn: '447700900000')
+    #
+    # @option params [required, String] :country
+    #   The two character country code in ISO 3166-1 alpha-2 format.
+    #
+    # @option params [required, String] :msisdn
+    #   An available inbound virtual number.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/developer/numbers#cancelANumber
+    #
     def cancel(params)
       request('/number/cancel', params: params, type: Post)
     end
 
+    # Change the behaviour of a number that you own.
+    #
+    # @example
+    #   params = {
+    #     country: 'GB',
+    #     msisdn: '447700900000',
+    #     voice_callback_type: 'app',
+    #     voice_callback_value: application_id
+    #   }
+    #
+    #   response = client.numbers.update(params)
+    #
+    # @option params [required, String] :country
+    #   The two character country code in ISO 3166-1 alpha-2 format.
+    #
+    # @option params [required, String] :msisdn
+    #   An available inbound virtual number.
+    #
+    # @option params [String] :mo_http_url
+    #   An URL-encoded URI to the webhook endpoint that handles inbound messages.
+    #   Your webhook endpoint must be active before you make this request.
+    #   Nexmo makes a `GET` request to the endpoint and checks that it returns a `200 OK` response.
+    #   Set this parameter's value to an empty string to remove the webhook.
+    #
+    # @option params [String] :mo_smpp_sys_type
+    #   The associated system type for your SMPP client.
+    #
+    # @option params [String] :messages_callback_type
+    #   The SMS webhook type (always `app`).
+    #   Must be used with the **:messages_callback_value** option.
+    #
+    # @option params [String] :messages_callback_value
+    #   A Nexmo Application ID.
+    #   Must be used with the **:messages_callback_type** option.
+    #
+    # @option params [String] :voice_callback_type
+    #   The voice webhook type.
+    #   Must be used with the **:voice_callback_value** option.
+    #
+    # @option params [String] :voice_callback_value
+    #   A SIP URI, telephone number or Application ID.
+    #   Must be used with the **:voice_callback_type** option.
+    #
+    # @option params [String] :voice_status_callback
+    #   A webhook URI for Nexmo to send a request to when a call ends.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/developer/numbers#updateANumber
+    #
     def update(params)
       request('/number/update', params: camelcase(params), type: Post)
     end