plivo 0.3.19 → 4.20.0

data/lib/plivo/base/resource_interface.rb

@@ -0,0 +1,108 @@
+module Plivo
+  module Base
+    class ResourceInterface
+      include Plivo::Utils
+      def initialize(client, resource_list_json = nil)
+        configure_client(client)
+        configure_resource_uri
+        parse_and_set(resource_list_json) if resource_list_json
+        @_is_voice_request = false
+      end
+
+      private
+
+      def configure_client(client)
+        valid_param?(:client, client, [RestClient, Phlo], true)
+        @_client = client
+      end
+
+      def configure_resource_uri
+        to_join = ['', 'v1', 'Account', @_client.auth_id, @_name, '']
+        to_join = ['', 'v1', 'Account', ''] if @_name == 'Account'
+        to_join = ['', 'v1', @_name, ''] if @_name == 'phlo'
+        @_resource_uri = to_join.join('/')
+      end
+
+      def parse_and_set(resource_list_json)
+        return unless resource_list_json
+
+        valid_param?(:resource_list_json, resource_list_json, Hash, true)
+
+        resource_list_json.each do |k, v|
+          if k == 'objects'
+            parse_and_set_list(resource_list_json['objects'])
+          elsif k == 'meta'
+            @_meta = resource_list_json['meta']
+          else
+            instance_variable_set("@#{k}", v)
+            self.class.send(:attr_reader, k)
+          end
+        end
+      end
+
+      def perform_get(identifier, params = nil)
+        valid_param?(:identifier, identifier, [String, Symbol], true)
+        response_json = @_client.send_request(@_resource_uri + identifier.to_s + '/', 'GET', params, nil, false, is_voice_request: @_is_voice_request)
+        @_resource_type.new(@_client, resource_json: response_json)
+      end
+
+      def perform_get_without_identifier(params)
+        valid_param?(:params, params, Hash, true)
+        response_json = @_client.send_request(@_resource_uri, 'GET', params, nil, false, is_voice_request: @_is_voice_request)
+        @_resource_type.new(@_client, resource_json: response_json)
+      end
+
+      def perform_create(params, use_multipart_conn=false)
+        Response.new(
+          @_client.send_request(@_resource_uri, 'POST', params, nil, use_multipart_conn, is_voice_request: @_is_voice_request),
+          @_identifier_string
+        )
+      end
+
+      def perform_submit(identifier, params = nil)
+        valid_param?(:identifier, identifier, [String, Symbol], true)
+        response_json = @_client.send_request(@_resource_uri + identifier.to_s + '/Submit/', 'POST', params, nil, false, is_voice_request: @_is_voice_request)
+        @_resource_type.new(@_client, resource_json: response_json)
+      end
+
+      def perform_post(params)
+        response_json = @_client.send_request(@_resource_uri, 'POST', params, nil, false, is_voice_request: @_is_voice_request)
+
+        parse_and_set(response_json)
+        self
+      end
+
+      def parse_and_set_list(list_json)
+        return unless list_json
+        valid_param?(:list_json, list_json, Array, false)
+        @_resource_list = list_json.map do |resource|
+          @_resource_type.new(@_client, resource_json: resource)
+        end
+      end
+
+      def perform_list(params = nil)
+        response_json = @_client.send_request(@_resource_uri, 'GET', params, nil, false, is_voice_request: @_is_voice_request)
+        parse_and_set(response_json)
+        {
+          api_id: @api_id,
+          meta: @_meta,
+          objects: @_resource_list
+        }
+      end
+      
+      def perform_action(action = nil, method = 'GET', params = nil, parse = false)
+        resource_path = action ? @_resource_uri + action + '/' : @_resource_uri
+        response = @_client.send_request(resource_path, method, params, nil, false, is_voice_request: @_is_voice_request)
+        parse ? parse_and_set(response) : self
+        method == 'POST' ? parse_and_set(params) : self
+        self
+      end
+
+      def perform_list_without_object(params = nil)
+        response_json = @_client.send_request(@_resource_uri, 'GET', params, nil, false, is_voice_request: @_is_voice_request)
+        parse_and_set(response_json)
+        response_json
+      end
+    end
+  end
+end

data/lib/plivo/base/response.rb

@@ -0,0 +1,38 @@
+module Plivo
+  module Base
+    ##
+    # A class to provide a blanket response based on what is
+    # being received from Plivo servers.
+    #
+    # This will be used only during POST and DELETE requests.
+    class Response
+      ##
+      # Instantiating a new instance requires a response_hash
+      # The id_symbol should contain a Symbol that represents
+      # the identifier of the resource for which this response
+      # is being generated for.
+
+      def initialize(response_hash, id_symbol = nil)
+        return unless response_hash
+
+        response_hash.each do |k, v|
+          instance_variable_set("@#{k}", v)
+          self.class.send(:attr_reader, k)
+        end
+        return unless id_symbol && response_hash.key?(id_symbol)
+
+        self.class.send(:attr_reader, :id)
+        @id = response_hash[id_symbol]
+      end
+
+      def to_s
+        h = self.instance_variables.map do |attribute|
+          key = attribute.to_s.gsub('@','')
+          [key, self.instance_variable_get(attribute)]
+        end.to_h
+        h.to_s
+      end
+
+    end
+  end
+end

data/lib/plivo/base.rb

@@ -0,0 +1,17 @@
+require_relative 'base/resource_interface'
+require_relative 'base/resource'
+require_relative 'base/response'
+
+module Plivo
+  module Base
+    PLIVO_API_URL = 'https://api.plivo.com'.freeze
+
+    API_VOICE = 'https://voice.plivo.com'.freeze
+    API_VOICE_FALLBACK_1 = 'https://voice-usw1.plivo.com'.freeze
+    API_VOICE_FALLBACK_2 = 'https://voice-use1.plivo.com'.freeze
+
+    CALLINSIGHTS_API_URL = 'https://stats.plivo.com'.freeze
+    PHLO_API_URL = 'https://phlorunner.plivo.com'.freeze
+    LOOKUP_API_URL = 'https://lookup.plivo.com'.freeze
+  end
+end

data/lib/plivo/base_client.rb

@@ -0,0 +1,393 @@
+require 'json'
+require 'faraday'
+require 'faraday_middleware'
+
+require_relative 'exceptions'
+require_relative 'utils'
+require_relative 'resources'
+require_relative 'base'
+
+module Plivo
+  # Core client, used for all API requests
+  include Utils
+  class BaseClient
+    # Base stuff
+    attr_reader :headers, :auth_credentials
+    @@voice_retry_count = 0
+    def initialize(auth_id = nil, auth_token = nil, proxy_options = nil, timeout=5)
+      configure_credentials(auth_id, auth_token)
+      configure_proxies(proxy_options)
+      configure_timeout(timeout)
+      configure_headers
+      configure_connection
+    end
+
+    def auth_id
+      @auth_credentials[:auth_id]
+    end
+
+    def process_response(method, response)
+      handle_response_exceptions(response)
+      if method == 'DELETE'
+        if !([200, 204].include? response[:status])
+          raise Exceptions::PlivoRESTError, "Resource at #{response[:url]} "\
+          'couldn\'t be deleted'
+        end
+      elsif !([200, 201, 202, 204, 207].include? response[:status])
+        raise Exceptions::PlivoRESTError, "Received #{response[:status]} for #{method}"
+      end
+      @@voice_retry_count = 0
+      response[:body]
+    end
+
+    def send_request(resource_path, method = 'GET', data = {}, timeout = nil, use_multipart_conn = false, options = nil)
+      timeout ||= @timeout
+
+      if options[:is_voice_request] == true
+        response = case method
+                   when 'GET' then send_get(resource_path, data, timeout, is_voice_request: options[:is_voice_request], voice_retry_count: @@voice_retry_count)
+                   when 'POST' then send_post(resource_path, data, timeout, use_multipart_conn, is_voice_request: options[:is_voice_request], voice_retry_count: @@voice_retry_count)
+                   when 'DELETE' then send_delete(resource_path, data, timeout, is_voice_request: options[:is_voice_request], voice_retry_count: @@voice_retry_count)
+                   else raise_invalid_request("#{method} not supported by Plivo, yet")
+                   end
+
+        if response.status >= 500
+          @@voice_retry_count += 1
+          if @@voice_retry_count > 2
+            return process_response(method, response.to_hash)
+          end
+          is_voice_request = true
+          send_request(resource_path, method, data, timeout, use_multipart_conn, is_voice_request: is_voice_request)
+        else
+          process_response(method, response.to_hash)
+        end
+      elsif options[:is_lookup_request] == true
+        response = case method
+                   when 'GET' then send_get(resource_path, data, timeout, is_lookup_request: options[:is_lookup_request])
+                   else raise_invalid_request("#{method} not supported by Plivo, yet")
+                   end
+        process_response(method, response.to_hash)
+      else
+        response = case method
+                   when 'GET' then send_get(resource_path, data, timeout)
+                   when 'POST' then send_post(resource_path, data, timeout, use_multipart_conn)
+                   when 'DELETE' then send_delete(resource_path, data, timeout)
+                   else raise_invalid_request("#{method} not supported by Plivo, yet")
+                   end
+
+        process_response(method, response.to_hash)
+      end
+    end
+    
+    private
+
+    def auth_token
+      @auth_credentials[:auth_token]
+    end
+
+    def configure_credentials(auth_id, auth_token)
+      # Fetches and sets the right credentials
+      auth_id ||= ENV['PLIVO_AUTH_ID']
+      auth_token ||= ENV['PLIVO_AUTH_TOKEN']
+
+      raise Exceptions::AuthenticationError, 'Couldn\'t find auth credentials' unless
+          auth_id && auth_token
+
+      raise Exceptions::AuthenticationError, "Invalid auth_id: '#{auth_id}'" unless
+          Utils.valid_account?(auth_id)
+
+      @auth_credentials = {
+          auth_id: auth_id,
+          auth_token: auth_token
+      }
+    end
+
+    def configure_proxies(proxy_dict)
+      @proxy_hash = nil
+      return unless proxy_dict
+
+      @proxy_hash = {
+          uri: "#{proxy_dict[:proxy_host]}:#{proxy_dict[:proxy_port]}",
+          user: proxy_dict[:proxy_user],
+          password: proxy_dict[:proxy_pass]
+      }
+    end
+
+    def configure_timeout(timeout)
+      @timeout = timeout
+    end
+
+    def user_agent
+      "plivo-ruby/#{Plivo::VERSION} (Ruby #{RUBY_VERSION})"
+    end
+
+    def configure_headers
+      @headers = {
+          'User-Agent' => user_agent,
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json'
+      }
+    end
+
+
+    def configure_connection
+      @conn = Faraday.new(@base_uri) do |faraday|
+        faraday.headers = @headers
+
+        # DANGER: Basic auth should always come after headers, else
+        # The headers will replace the basic_auth
+
+        faraday.basic_auth(auth_id, auth_token)
+
+        faraday.proxy=@proxy_hash if @proxy_hash
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+
+      @voice_conn_no_retry = Faraday.new(@voice_base_uri) do |faraday|
+        faraday.headers = @headers
+
+        # DANGER: Basic auth should always come after headers, else
+        # The headers will replace the basic_auth
+
+        faraday.basic_auth(auth_id, auth_token)
+
+        faraday.proxy=@proxy_hash if @proxy_hash
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+
+      @voice_conn_retry_1 = Faraday.new(@voice_base_uri_fallback_1) do |faraday|
+        faraday.headers = @headers
+
+        # DANGER: Basic auth should always come after headers, else
+        # The headers will replace the basic_auth
+
+        faraday.basic_auth(auth_id, auth_token)
+
+        faraday.proxy=@proxy_hash if @proxy_hash
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+
+      @voice_conn_retry_2 = Faraday.new(@voice_base_uri_fallback_2) do |faraday|
+        faraday.headers = @headers
+
+        # DANGER: Basic auth should always come after headers, else
+        # The headers will replace the basic_auth
+
+        faraday.basic_auth(auth_id, auth_token)
+
+        faraday.proxy=@proxy_hash if @proxy_hash
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+
+      @callinsights_conn = Faraday.new(@callinsights_base_uri) do |faraday|
+        faraday.headers = @headers
+
+        # DANGER: Basic auth should always come after headers, else
+        # The headers will replace the basic_auth
+
+        faraday.basic_auth(auth_id, auth_token)
+
+        faraday.proxy=@proxy_hash if @proxy_hash
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+
+      @lookup_conn = Faraday.new(@lookup_base_uri) do |faraday|
+        faraday.headers = @headers
+
+        # DANGER: Basic auth should always come after headers, else
+        # The headers will replace the basic_auth
+
+        faraday.basic_auth(auth_id, auth_token)
+
+        faraday.proxy=@proxy_hash if @proxy_hash
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def send_get(resource_path, data, timeout, options = nil)
+      if options
+        if options[:voice_retry_count] == 0 and options[:is_voice_request] == true
+          response = @voice_conn_no_retry.get do |req|
+            req.url resource_path, data
+            req.options.timeout = timeout if timeout
+          end
+        elsif options[:voice_retry_count] == 1 and options[:is_voice_request] == true
+          response = @voice_conn_retry_1.get do |req|
+            req.url resource_path, data
+            req.options.timeout = timeout if timeout
+          end
+        elsif options[:voice_retry_count] == 2 and options[:is_voice_request] == true
+          response = @voice_conn_retry_2.get do |req|
+            req.url resource_path, data
+            req.options.timeout = timeout if timeout
+          end
+        elsif options[:is_lookup_request] == true
+          response = @lookup_conn.get do |req|
+            req.url resource_path, data
+            req.options.timeout = timeout if timeout
+          end
+        end
+      else
+        response = @conn.get do |req|
+          req.url resource_path, data
+          req.options.timeout = timeout if timeout
+        end
+      end
+      response
+    end
+
+    def send_post(resource_path, data, timeout, use_multipart_conn, options = nil)
+      if use_multipart_conn
+        multipart_conn = Faraday.new(@base_uri) do |faraday|
+          faraday.headers = {
+              'User-Agent' => @headers['User-Agent'],
+              'Accept' => @headers['Accept']
+          }
+
+          # DANGER: Basic auth should always come after headers, else
+          # The headers will replace the basic_auth
+
+          faraday.request :multipart
+          faraday.request :url_encoded
+          faraday.basic_auth(auth_id, auth_token)
+
+          faraday.proxy=@proxy_hash if @proxy_hash
+          faraday.response :json, content_type: /\bjson$/
+          faraday.adapter Faraday.default_adapter
+        end
+
+        response = multipart_conn.post do |req|
+          req.url resource_path
+          req.options.timeout = timeout if timeout
+          req.body = data
+          puts req
+        end
+      else
+        if !data.nil? && (data.has_key? 'is_callinsights_request')
+          callinsight_base_url = data['callinsight_base_url']
+          resource_path = data['request_url']
+          data.delete('is_callinsights_request')
+          data.delete('request_url')
+
+          response = @callinsights_conn.post do |req|
+            req.url resource_path
+            req.options.timeout = timeout if timeout
+            req.body = JSON.generate(data) if data
+          end
+        elsif options
+          if options[:voice_retry_count] == 0 and options[:is_voice_request] == true
+            response = @voice_conn_no_retry.post do |req|
+              req.url resource_path
+              req.options.timeout = timeout if timeout
+              req.body = JSON.generate(data) if data
+            end
+          elsif options[:voice_retry_count] == 1 and options[:is_voice_request] == true
+            response = @voice_conn_retry_1.post do |req|
+              req.url resource_path
+              req.options.timeout = timeout if timeout
+              req.body = JSON.generate(data) if data
+            end
+          elsif options[:voice_retry_count] == 2 and options[:is_voice_request] == true
+            response = @voice_conn_retry_2.post do |req|
+              req.url resource_path
+              req.options.timeout = timeout if timeout
+              req.body = JSON.generate(data) if data
+            end
+          end
+        else
+          response = @conn.post do |req|
+            req.url resource_path
+            req.options.timeout = timeout if timeout
+            req.body = JSON.generate(data) if data
+          end
+        end
+      end
+      response
+    end
+
+    def send_delete(resource_path, data, timeout, options = nil)
+      if options
+        if options[:voice_retry_count] == 0 and options[:is_voice_request] == true
+          response = @voice_conn_no_retry.delete do |req|
+            req.url resource_path
+            req.options.timeout = timeout if timeout
+            req.body = JSON.generate(data) if data
+          end
+        elsif options[:voice_retry_count] == 1 and options[:is_voice_request] == true
+          response = @voice_conn_retry_1.delete do |req|
+            req.url resource_path
+            req.options.timeout = timeout if timeout
+            req.body = JSON.generate(data) if data
+          end
+        elsif options[:voice_retry_count] == 2 and options[:is_voice_request] == true
+          response = @voice_conn_retry_2.delete do |req|
+            req.url resource_path
+            req.options.timeout = timeout if timeout
+            req.body = JSON.generate(data) if data
+          end
+        end
+      else
+        response = @conn.delete do |req|
+          req.url resource_path
+          req.options.timeout = timeout if timeout
+          req.body = JSON.generate(data) if data
+        end
+      end
+      response
+    end
+
+    def handle_response_exceptions(response)
+      exception_mapping = {
+          400 => [
+              Exceptions::ValidationError,
+              'A parameter is missing or is invalid while accessing resource'
+          ],
+          401 => [
+              Exceptions::AuthenticationError,
+              'Failed to authenticate while accessing resource'
+          ],
+          404 => [
+              Exceptions::ResourceNotFoundError,
+              'Resource not found'
+          ],
+          405 => [
+              Exceptions::InvalidRequestError,
+              'HTTP method used is not allowed to access resource'
+          ],
+          409 => [
+            Exceptions::InvalidRequestError,
+            'Conflict'
+          ],
+          422 => [
+            Exceptions::InvalidRequestError,
+            'Unprocessable Entity'
+          ],
+          500 => [
+              Exceptions::PlivoServerError,
+              'A server error occurred while accessing resource'
+          ]
+      }
+
+      response_json = response[:body]
+      return unless exception_mapping.key? response[:status]
+
+      exception_now = exception_mapping[response[:status]]
+      error_message = if (response_json.is_a? Hash) && (response_json.key? 'error')
+                        response_json['error']
+                      else
+                        exception_now[1] + " at: #{response[:url]}"
+                      end
+      if error_message.is_a?(Hash) && error_message.key?('error')
+        error_message = error_message['error']
+      end
+
+      raise exception_now[0], error_message.to_s
+    end
+  end
+end

data/lib/plivo/exceptions.rb

@@ -0,0 +1,50 @@
+module Plivo
+  ##
+  # The exceptions module that helps in passing on errors to the user in a better way.
+  module Exceptions
+    ##
+    # This is Plivo's base error and will be raised when there is an unknown
+    # error that is not covered by other errors.
+    PlivoRESTError = Class.new(StandardError)
+
+    ##
+    # This will be raised when A parameter is missing or is invalid while
+    # accessing resource.
+    ValidationError = Class.new(PlivoRESTError)
+    # 'A parameter is missing or is invalid while accessing resource'
+
+    ##
+    # This will be raised when there is an an error authenticating the request.
+    #
+    # It is because there were no authentication credentials found or passed
+    # or the auth credentials that were found or passed were incorrect.
+    AuthenticationError = Class.new(PlivoRESTError)
+
+    ##
+    # This will be raised when one or more parameters passed to Plivo servers
+    # is invalid.
+    #
+    # More specific error message will be displayed wherever possible.
+    InvalidRequestError = Class.new(PlivoRESTError)
+
+    ##
+    # This will be raised when there is a server error on the Plivo end.
+    #
+    # This is rarely encountered. You might want to catch this error and
+    # retry the request if needed.
+    #
+    # If retrying doesn't help, please contact https://support.plivo.com
+    # immediately.
+    PlivoServerError = Class.new(PlivoRESTError)
+
+    ##
+    # This will be raised when there is an XML generation error.
+    #
+    # Usually, the reason why this error is raised will be included.
+    PlivoXMLError = Class.new(PlivoRESTError)
+
+    ##
+    # This will be raised when there is an authentication error
+    ResourceNotFoundError = Class.new(PlivoRESTError)
+  end
+end