plivo 0.3.19 → 4.20.0

data/lib/plivo/utils.rb

@@ -0,0 +1,294 @@
+require 'openssl'
+require 'uri'
+require 'base64'
+
+module Plivo
+  # Utils module
+  module Utils
+    module_function
+
+    TYPE_WHITELIST = [Integer]
+    TYPE_WHITELIST.push(Fixnum, Bignum) unless 1.class == Integer
+
+    def valid_account?(account_id, raise_directly = false)
+      valid_subaccount?(account_id, raise_directly) || valid_mainaccount?(account_id, raise_directly)
+    end
+
+    # @param [String] account_id
+    # @param [Boolean] raise_directly
+    def valid_subaccount?(account_id, raise_directly = false)
+      unless account_id.is_a? String
+        return false unless raise_directly
+        raise_invalid_request('subaccount_id must be a string')
+      end
+
+      if account_id.length != 20
+        return false unless raise_directly
+        raise_invalid_request('subaccount_id should be of length 20')
+      end
+
+      if account_id[0..1] != 'SA'
+        return false unless raise_directly
+        raise_invalid_request("subaccount_id should start with 'SA'")
+      end
+      true
+    end
+
+    def valid_mainaccount?(account_id, raise_directly = false)
+      unless account_id.is_a? String
+        return false unless raise_directly
+        raise_invalid_request('account_id must be a string')
+      end
+
+      if account_id.length != 20
+        return false unless raise_directly
+        raise_invalid_request('account_id should be of length 20')
+      end
+
+      if account_id[0..1] != 'MA'
+        return false unless raise_directly
+        raise_invalid_request("account_id should start with 'SA'")
+      end
+      true
+    end
+
+    def raise_invalid_request(message = '')
+      raise Exceptions::InvalidRequestError, message
+    end
+
+    def valid_param?(param_name, param_value, expected_types = nil, mandatory = false, expected_values = nil)
+      if mandatory && param_value.nil?
+        raise_invalid_request("#{param_name} is a required parameter")
+      end
+
+      return true if param_value.nil?
+
+      return expected_type?(param_name, expected_types, param_value) unless expected_values
+      expected_value?(param_name, expected_values, param_value)
+    end
+
+    def valid_multiple_destination_nos?(param_name, param_value, options = nil)
+      if param_value.split(options[:delimiter]).size > 1 && options[:role].downcase != 'agent'
+        raise_invalid_request("Multiple #{param_name} values given for role #{options[:role]}")
+      elsif param_value.split(options[:delimiter]).size >= options[:agent_limit]
+        raise_invalid_request("No of #{param_name} values provided should be lesser than #{options[:agent_limit]}")
+      else
+        return true
+      end
+    end
+
+    def valid_multiple_destination_integers?(param_name, param_value)
+      if (param_value.is_a? String)
+        values = param_value.split("<")
+        for i in values
+          unless (Integer(i) rescue false)
+            raise_invalid_request("#{param_name} Destination Value must be integer")
+          end
+        end
+      end
+    end
+    
+    def valid_url?(param_name, param_value, mandatory = false)
+      if mandatory && param_value.nil?
+        raise_invalid_request("#{param_name} is a required parameter")
+      end
+
+      return true if param_value.nil?
+      return raise_invalid_request("#{param_name}: Expected a String but received #{param_value.class} instead") unless expected_type?(param_name, String, param_value)
+
+      if param_value =~ /^(http[s]?:\/\/([a-zA-Z]|[0-9]|[\$\-\_\@\.\&\+\/\#]|[\!\*\(\)\,]|(%[0-9a-fA-F][0-9a-fA-F]))+|nil)$/ix
+        return true
+      else
+        return raise_invalid_request("Invalid URL : Doesn't satisfy the URL format")
+      end
+    end
+
+    def valid_range?(param_name, param_value, mandatory = false, lower_bound = nil, upper_bound = nil)
+      if mandatory && param_value.nil?
+        raise_invalid_request("#{param_name} is a required parameter")
+      end
+
+      return true if param_value.nil?
+
+      return raise_invalid_request("#{param_name}: Expected an Integer but received #{param_value.class} instead") unless expected_type?(param_name, Integer, param_value)
+      if lower_bound && upper_bound
+        return raise_invalid_request("#{param_name} ranges between #{lower_bound} and #{upper_bound}") if param_value < lower_bound or param_value > upper_bound
+
+        return true if param_value >= lower_bound and param_value <= upper_bound
+      elsif lower_bound
+        return raise_invalid_request("#{param_name} should be greater than #{lower_bound}") if param_value < lower_bound
+
+        return true if param_value >= lower_bound
+      elsif upper_bound
+        return raise_invalid_request("#{param_name} should be lesser than #{upper_bound}") if param_value > upper_bound
+
+        return true if param_value <= upper_bound
+      else
+        return raise_invalid_request("Any one or both of lower and upper bound should be provided")
+      end
+    end
+
+    def multi_valid_param?(param_name, param_value, expected_types = nil, mandatory = false, expected_values = nil, make_down_case = false, seperator = ',')
+      if mandatory && param_value.nil?
+        raise_invalid_request("#{param_name} is a required parameter")
+      end
+
+      return true if param_value.nil?
+
+      if make_down_case
+        param_value = param_value.downcase
+      else
+        param_value = param_value.uppercase
+      end
+
+      for val in param_value.split(seperator)
+        return expected_type?(param_name, expected_types, val.strip) unless expected_values
+        expected_value?(param_name, expected_values, val.strip)
+      end
+    end
+
+    def valid_date_format?(param_name, param_value, mandatory = false)
+      if mandatory && param_value.nil?
+        raise_invalid_request("#{param_name} is a required parameter")
+      end
+
+      return true if param_value.nil?
+
+      if param_value =~ /^(\d{4}\-\d{2}\-\d{2}\ \d{2}\:\d{2}(\:\d{2}(\.\d{1,6})?)?)$/ix
+        return true
+      else
+        return raise_invalid_request("Invalid Date Format")
+      end
+    end
+
+    def is_one_among_string_url?(param_name, param_value, mandatory = false, expected_values= nil)
+      if mandatory && param_value.nil?
+        raise_invalid_request("#{param_name} is a required parameter")
+      end
+
+      return true if param_value.nil?
+      return raise_invalid_request("#{param_name}: Expected a String but received #{param_value.class} instead") unless expected_type?(param_name, String, param_value)
+
+      if expected_values.include? param_value.downcase or expected_values.include? param_value.upcase
+        return true
+      elsif valid_url?(param_name, param_value)
+        return true
+      else
+        raise_invalid_request("#{param_name} neither a valid URL nor in the expected values")
+      end
+    end
+
+    def expected_type?(param_name, expected_types, param_value)
+      return true if expected_types.nil?
+      param_value_class = param_value.class
+      param_value_class = Integer if TYPE_WHITELIST.include? param_value_class
+      if expected_types.is_a? Array
+        return true if expected_types.include? param_value_class
+        raise_invalid_request("#{param_name}: Expected one of #{expected_types}"\
+          " but received #{param_value.class} instead")
+      else
+        return true if expected_types == param_value_class
+        raise_invalid_request("#{param_name}: Expected a #{expected_types}"\
+          " but received #{param_value.class} instead")
+      end
+    end
+
+    def expected_value?(param_name, expected_values, param_value)
+      return true if expected_values.nil?
+      if expected_values.is_a? Array
+        return true if expected_values.include? param_value
+        raise_invalid_request("#{param_name}: Expected one of #{expected_values}"\
+          " but received '#{param_value}' instead")
+      else
+        return true if expected_values == param_value
+        raise_invalid_request("#{param_name}: Expected '#{expected_values}'"\
+          " but received '#{param_value}' instead")
+      end
+    end
+
+    # @param [String] uri
+    # @param [String] nonce
+    # @param [String] signature
+    # @param [String] auth_token
+    def valid_signature?(uri, nonce, signature, auth_token)
+      parsed_uri = URI.parse(uri)
+      uri_details = {host: parsed_uri.host, path: parsed_uri.path}
+      uri_builder_module = parsed_uri.scheme == 'https' ? URI::HTTPS : URI::HTTP
+      data_to_sign = uri_builder_module.build(uri_details).to_s + nonce
+      sha256_digest = OpenSSL::Digest.new('sha256')
+      Base64.encode64(OpenSSL::HMAC.digest(sha256_digest, auth_token, data_to_sign)).strip() == signature
+    end
+
+    def generate_url?(uri, params, method)
+      uri.sub!("+", "%20")
+      parsed_uri = URI.parse(uri)
+      uri = parsed_uri.scheme + "://" + parsed_uri.host + parsed_uri.path
+      if params.to_s.length > 0 || parsed_uri.query.to_s.length > 0
+        uri += "?"
+      end
+      if parsed_uri.query.to_s.length > 0
+        parsed_uri_query = URI.decode(parsed_uri.query)
+        if method == "GET"
+          queryParamMap = getMapFromQueryString?(parsed_uri_query)
+          params.keys.sort.each { |key|
+            queryParamMap[key] = params[key]
+          }
+          uri += GetSortedQueryParamString?(queryParamMap, true)
+        else
+          uri += GetSortedQueryParamString?(getMapFromQueryString?(parsed_uri_query), true) + "." + GetSortedQueryParamString?(params, false)
+          uri = uri.chomp(".")
+        end
+      else
+        if method == "GET"
+          uri += GetSortedQueryParamString?(params, true)
+        else
+          uri += GetSortedQueryParamString?(params, false)
+        end
+      end
+      return uri
+    end
+
+    def getMapFromQueryString?(query)
+      mp = Hash.new
+      if query.to_s.length == 0
+        return mp
+      end
+      keyValuePairs = query.split("&")
+      keyValuePairs.each { |key|
+        params = key.split("=", 2)
+        if params.length == 2
+          mp[params[0]] = params[1]
+        end
+      }
+      return mp
+    end
+
+    def GetSortedQueryParamString?(params, queryParams)
+      url = ""
+      if queryParams
+        params.keys.sort.each { |key|
+          url += key + "=" + params[key] + "&"
+        }
+        url = url.chomp("&")
+      else
+        params.keys.sort.each { |key|
+          url += key.to_s + params[key].to_s
+        }
+      end
+      return url
+    end
+
+
+    def compute_signatureV3?(url, auth_token, nonce)
+      sha256_digest = OpenSSL::Digest.new('sha256')
+      new_url = url + "." + nonce
+      return Base64.encode64(OpenSSL::HMAC.digest(sha256_digest, auth_token, new_url)).strip()
+    end
+
+    def valid_signatureV3?(uri, nonce, signature, auth_token, method, params={})
+      new_url = generate_url?(uri, params, method)
+      generated_signature = compute_signatureV3?(new_url, auth_token, nonce)
+      return signature.split(",").include? generated_signature
+    end
+  end
+end

data/lib/plivo/version.rb

@@ -0,0 +1,3 @@
+module Plivo
+  VERSION = "4.20.0".freeze
+end

data/lib/plivo/xml/break.rb

@@ -0,0 +1,31 @@
+module Plivo
+  module XML
+    class Break < Element
+      @nestables = []
+      @valid_attributes = %w(strength time)
+      VALID_STRENGTH_VALUES= %w(none x-weak weak medium strong x-strong)
+
+      def initialize(attributes = {})
+        if attributes && attributes[:strength] && !VALID_STRENGTH_VALUES.include?(attributes[:strength])
+          raise PlivoXMLError, "invalid attribute value #{attributes[:strength]} for strength"
+        end
+        if attributes && attributes[:time]
+          if attributes[:time].downcase().include?('ms')
+            time = attributes[:time].split('ms')[0].to_i
+            if  time<= 0 || time >10000
+              raise PlivoXMLError, "invalid attribute value #{attributes[:time]} for time attribute. Value for time in milliseconds should be > 0 or < 10000"
+            end
+          elsif attributes[:time].downcase().include?('s')
+            time = attributes[:time].split('s')[0].to_i
+            if  time<= 0 || time >10
+              raise PlivoXMLError, "invalid attribute value #{attributes[:time]} for time attribute. Value for time in seconds should be > 0 or < 10"
+            end
+          else
+            raise PlivoXMLError, "invalid attribute value #{attributes[:time]} for time attribute"
+          end
+        end
+        super(nil, attributes)
+      end
+    end
+  end
+end

data/lib/plivo/xml/conference.rb

@@ -0,0 +1,20 @@
+module Plivo
+  module XML
+    class Conference < Element
+      @nestables = []
+      @valid_attributes = %w[muted beep startConferenceOnEnter
+                             endConferenceOnExit waitSound enterSound exitSound
+                             timeLimit hangupOnStar maxMembers
+                             record recordFileFormat action method redirect
+                             digitsMatch callbackUrl callbackMethod
+                             stayAlone floorEvent
+                             transcriptionType transcriptionUrl
+                             transcriptionMethod recordWhenAlone relayDTMF]
+
+      def initialize(body, attributes = {})
+        raise PlivoXMLError, 'No conference name set for Conference' unless body
+        super(body, attributes)
+      end
+    end
+  end
+end

data/lib/plivo/xml/cont.rb

@@ -0,0 +1,13 @@
+module Plivo
+    module XML
+      class Cont < Element
+        @nestables = []
+        @valid_attributes = []
+  
+        def initialize(body)
+          super(body)
+        end
+      end
+    end
+  end
+  

data/lib/plivo/xml/dial.rb

@@ -0,0 +1,16 @@
+module Plivo
+  module XML
+    class Dial < Element
+      @nestables = %w[Number User]
+      @valid_attributes = %w[action method timeout hangupOnStar
+                             timeLimit callerId callerName confirmSound
+                             dialMusic confirmKey redirect
+                             callbackUrl callbackMethod digitsMatch digitsMatchBLeg
+                             sipHeaders]
+
+      def initialize(attributes = {}, &block)
+        super(nil, attributes, &block)
+      end
+    end
+  end
+end

data/lib/plivo/xml/dtmf.rb

@@ -0,0 +1,13 @@
+module Plivo
+  module XML
+    class DTMF < Element
+      @nestables = []
+      @valid_attributes = %w[async]
+
+      def initialize(body, attributes = {})
+        raise PlivoXMLError, 'No digits set for DTMF' unless body
+        super(body, attributes)
+      end
+    end
+  end
+end

data/lib/plivo/xml/element.rb

@@ -0,0 +1,106 @@
+module Plivo
+  module XML
+    class Element
+      class << self
+        attr_accessor :valid_attributes, :nestables
+      end
+      @nestables = []
+      @valid_attributes = []
+      SSML_TAGS=%w[Break Emphasis Lang P Phoneme Prosody S SayAs Sub W]
+
+      attr_accessor :node, :name
+
+      def hyphenate(pascal_cased_word)
+        pascal_cased_word.to_s.gsub(/::/, '/').
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1-\2').
+          gsub(/([a-z\d])([A-Z])/,'\1-\2').
+          downcase
+      end
+
+      def initialize(body = nil, attributes = {}, nestables=self.class.nestables)
+        @name = self.class.name.split('::')[2]
+        @body = body
+        tagname = @name
+        if SSML_TAGS.include?(@name)
+          tagname = hyphenate(@name)
+        end
+        @node = REXML::Element.new tagname
+        attributes.each do |k, v|
+          if self.class.valid_attributes.include?(k.to_s)
+            @node.attributes[k.to_s] = convert_value(v)
+          else
+            raise PlivoXMLError, "invalid attribute #{k} for #{@name}"
+          end
+        end
+        @nestables = nestables
+        @node.text = @body if @body
+
+        # Allow for nested "nestable" elements using a code block
+        # ie
+        # Plivo::XML::Response.new do |r|
+        #   r.Dial do |n|
+        #     n.Number '+15557779999'
+        #   end
+        # end
+        yield(self) if block_given?
+      end
+
+      def add_attribute(attribute, value)
+        @node.add_attribute(attribute, value)
+      end
+
+      def method_missing(method, *args, &block)
+        # Handle the addElement methods
+        method = Regexp.last_match(1).to_sym if method.to_s =~ /^add(.*)/
+        # Add the element
+        begin
+          add(Plivo::XML.const_get(method).new(*args, &block))
+        rescue StandardError => e
+          raise PlivoXMLError, e.message
+        end
+      end
+
+      def convert_value(v)
+        case v
+        when true
+          'true'
+        when false
+          'false'
+        when nil
+          'none'
+        when 'get'
+          'GET'
+        when 'post'
+          'POST'
+        else
+          v
+        end
+      end
+
+      def add(element)
+        raise PlivoXMLError, 'invalid element' unless element
+        if @nestables.include?(element.name)
+          if element.name == "Cont"
+            @node.elements << element.node 
+            element
+            temp = REXML::Text.new element.node.text
+            @node.elements['Cont'] = temp
+          else
+            @node.elements << element.node 
+            element
+          end
+        else
+          raise PlivoXMLError, "#{element.name} not nestable in #{@name}"
+        end
+      end
+
+      def to_xml
+        @node.to_s
+      end
+
+      def to_s
+        @node.to_s
+      end
+    end
+  end
+end

data/lib/plivo/xml/emphasis.rb

@@ -0,0 +1,17 @@
+module Plivo
+  module XML
+    class Emphasis < Element
+      @nestables = %w(Break Cont Emphasis Lang Phoneme Prosody SayAs Sub W)
+      @valid_attributes = %w(level)
+
+      VALID_LEVEL_ATTRIBUTE_VALUE=%w(strong moderate reduced)
+
+      def initialize(body, attributes = {})
+        if attributes && attributes[:level] && !VALID_LEVEL_ATTRIBUTE_VALUE.include?(attributes[:level])
+          raise PlivoXMLError, "invalid attribute value #{attributes[:level]} for level"
+        end
+        super(body, attributes)
+      end
+    end
+  end
+end

data/lib/plivo/xml/get_digits.rb

@@ -0,0 +1,15 @@
+module Plivo
+  module XML
+    class GetDigits < Element
+      @nestables = %w[Speak Play Wait]
+      @valid_attributes = %w[action method timeout digitTimeout
+                             numDigits retries invalidDigitsSound
+                             validDigits playBeep redirect finishOnKey
+                             digitTimeout log]
+
+      def initialize(attributes = {}, &block)
+        super(nil, attributes, &block)
+      end
+    end
+  end
+end

data/lib/plivo/xml/get_input.rb

@@ -0,0 +1,16 @@
+module Plivo
+  module XML
+    class GetInput < Element
+      @nestables = %w[Speak Play Wait]
+      @valid_attributes = %w[action method inputType executionTimeout
+                             digitEndTimeout speechEndTimeout finishOnKey
+                             numDigits speechModel hints profanityFilter
+                             interimSpeechResultsCallback log language
+                             interimSpeechResultsCallbackMethod redirect]
+
+      def initialize(attributes = {}, &block)
+        super(nil, attributes, &block)
+      end
+    end
+  end
+end

data/lib/plivo/xml/hangup.rb

@@ -0,0 +1,12 @@
+module Plivo
+  module XML
+    class Hangup < Element
+      @nestables = []
+      @valid_attributes = %w[schedule reason]
+
+      def initialize(attributes = {})
+        super(nil, attributes)
+      end
+    end
+  end
+end

data/lib/plivo/xml/lang.rb

@@ -0,0 +1,29 @@
+module Plivo
+  module XML
+    class Lang < Element
+      @nestables = %w(Break Cont Emphasis Lang P Phoneme Prosody S SayAs Sub W)
+      @valid_attributes = %w(xmllang)
+
+       VALID_LANG_ATTRIBUTE_VALUES = [
+        'arb', 'cmn-CN','da-DK','nl-NL','en-AU',
+        'en-GB', 'en-IN','en-US','en-GB-WLS','fr-FR',
+        'fr-CA','de-DE','hi-IN','is-IS','it-IT',
+        'ja-JP','ko-KR','nb-NO','pl-PL','pt-BR',
+        'pt-PT','ro-RO','ru-RU','es-ES','es-MX',
+        'es-US','sv-SE','tr-TR','cy-GB']
+
+
+      def initialize(body, attributes = {})
+        if attributes && attributes[:xmllang]
+          unless VALID_LANG_ATTRIBUTE_VALUES.include?(attributes[:xmllang])
+            raise PlivoXMLError, "invalid attribute value #{attributes[:xmllang]} for xmllang"
+          end
+          super(body, {})
+          add_attribute("xml:lang", attributes[:xmllang])
+        else
+          raise PlivoXMLError, 'xmllang attribute is a required attribute for lang'
+        end
+      end
+    end
+  end
+end

data/lib/plivo/xml/message.rb

@@ -0,0 +1,13 @@
+module Plivo
+  module XML
+    class Message < Element
+      @nestables = []
+      @valid_attributes = %w[src dst type callbackUrl callbackMethod]
+
+      def initialize(body, attributes = {})
+        raise PlivoXMLError, 'No text set for Message' unless body
+        super(body, attributes)
+      end
+    end
+  end
+end