elements-pay 1.0.0

data/lib/elements/elements_client.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Elements
+  # ElementsClient executes HTTP requests against the Elements API, converts the response
+  # into a resource object or an error object accordingly.
+  class ElementsClient
+    include ::Elements::Logging
+
+    attr_reader :config
+
+    def initialize(config_arg = {})
+      @config = Elements.config.reverse_duplicate_merge(config_arg)
+    end
+
+    def self.current_thread_context
+      Thread.current[:elements_client__internal_use_only] ||= ThreadContext.new
+    end
+
+    def self.active_client
+      current_thread_context.active_client || default_client
+    end
+
+    def self.default_client
+      current_thread_context.default_client ||= ElementsClient.new
+    end
+
+    def execute_request(method, path, params: {}, headers: {}, opts: {})
+      api_base = opts[:api_base] || config.api_base
+      api_key = opts[:api_key] || config.api_key
+
+      body_params, query_params = if %i[get head delete].include?(method)
+                                    [nil, params]
+                                  else
+                                    [params, nil]
+                                  end
+
+      query_params, path = merge_query_params(query_params, path)
+      query = encode_query_params(query_params)
+
+      headers = request_headers(api_key, method).update(headers)
+
+      body = body_params ? JSON.generate(body_params) : nil
+
+      url = api_url(path, query, api_base)
+
+      context = {
+        method: method,
+        path: path,
+        query: query,
+        body: body_params,
+        idempotency_key: headers['Idempotency-Key']
+      }
+
+      log_request(context)
+      resp = with_retries do
+        execute_request_with_rescues(method, url, headers, body, context)
+      end
+      log_response(context, resp)
+      resp
+    end
+
+    private def with_retries(config = Elements.config)
+      attempts = 0
+      begin
+        resp = yield
+      rescue StandardError => e
+        raise e unless self.class.should_retry?(e, attempts, config)
+
+        attempts += 1
+        sleep sleep_duration(attempts, config)
+        retry
+      end
+      resp
+    end
+
+    def self.should_retry?(error, attempts, config)
+      return false if attempts >= config.max_network_retries
+      # retry if it is a connection issue
+      return true if error.is_a?(Elements::APIConnectionError)
+      # retry if it is a conflict, e.g., record not saved
+      return true if error.is_a?(Elements::ElementsError) && error.http_status == 409
+      # retry if service is temporarily unavailable
+      return true if error.is_a?(Elements::ElementsError) && error.http_status == 503
+
+      false
+    end
+
+    def self.sleep_duration(attempts, config)
+      duration = config.min_network_retry_delay * (2**(attempts - 1))
+      # adding jitter, https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+      duration = rand(duration)
+      duration = [config.min_network_retry_delay, duration].max
+      [config.max_network_retry_delay, duration].min
+    end
+
+    private def execute_request_with_rescues(method, url, headers, body, context)
+      resp, err = begin
+        context[:request_start] = Util.monotonic_time
+        [RestClient::Request.execute(method: method, url: url, headers: headers, payload: body, **request_options), nil]
+      rescue RestClient::ExceptionWithResponse => e
+        [e.response, e]
+      rescue StandardError => e
+        [nil, e]
+      end
+
+      if resp && resp.code >= 400
+        handle_error_with_response(resp, err, context)
+      elsif err
+        handle_error_without_response(err, context)
+      end
+      resp
+    end
+
+    private def handle_error_without_response(err, context)
+      if APIConnectionError::CAUSE_ERROR_CLASSES.any? { |cause| err.is_a?(cause) }
+        log_error('Network error',
+                  error_message: err.message,
+                  idempotency_key: context[:idempotency_key],
+                  method: context[:method],
+                  path: context[:path])
+
+        raise APIConnectionError,
+              "Encountered unexpected error #{err.class.name} " \
+              "while sending request, error message: #{err.message}"
+      end
+
+      # an unexpected error was raised
+      log_error('Unknown request error',
+                error_message: err.message,
+                idempotency_key: context[:idempotency_key],
+                method: context[:method],
+                path: context[:path])
+      raise err
+    end
+
+    private def handle_error_with_response(http_resp, err, context)
+      log_response(context, http_resp)
+
+      begin
+        resp = ElementsResponse.new(http_resp)
+        error_data = resp.data[:error]
+
+        raise ElementsError, 'Unknown error' unless error_data
+      rescue JSON::ParserError, ElementsError
+        raise GenericAPIError.new("Invalid response from Elements API: #{http_resp.body}, " \
+                                  "error message: #{err.message}",
+                                  http_status: http_resp.code,
+                                  http_headers: http_resp.headers,
+                                  http_body: http_resp.body)
+      end
+
+      log_error('Elements API error',
+                status: resp.status,
+                error_code: error_data[:code],
+                error_type: error_data[:type],
+                error_message: error_data[:message],
+                error_params: error_data[:data],
+                trace_id: error_data[:trace_id],
+                idempotency_key: context[:idempotency_key])
+
+      specific_error = api_error(http_resp, error_data)
+      specific_error.response = resp
+      raise specific_error
+    end
+
+    private def api_error(resp, error_data)
+      opts = {
+        http_body: resp.body,
+        http_headers: resp.headers,
+        http_status: resp.code
+      }
+
+      err_type = error_data[:type] || 'api_error'
+      error_class = Elements::Errors::ERROR_CODES_TO_TYPES[err_type.to_sym] || GenericAPIError
+      error_class.new(error_data[:message], **opts)
+    end
+
+    private def log_request(context)
+      log_info('Request info',
+               method: context[:method],
+               path: context[:path],
+               idempotency_key: context[:idempotency_key])
+      log_debug('Request details',
+                method: context[:method],
+                path: context[:path],
+                query: context[:query],
+                body: context[:body],
+                idempotency_key: context[:idempotency_key])
+    end
+
+    private def log_response(context, resp)
+      log_info('Response info',
+               method: context[:method],
+               path: context[:path],
+               idempotency_key: context[:idempotency_key],
+               elapsed: "#{(Util.monotonic_time - context[:request_start]) * 1_000}ms",
+               status: resp.code)
+      log_debug('Response details',
+                method: context[:method],
+                path: context[:path],
+                query: context[:query],
+                idempotency_key: context[:idempotency_key],
+                status: resp.code,
+                body: resp.body,
+                headers: resp.headers)
+    end
+
+    private def encode_query_params(params)
+      return nil if params.nil?
+
+      params.map { |k, v| "#{k}=#{v}" }.join('&')
+    end
+
+    private def request_headers(api_key, method)
+      headers = {}
+      headers['Authorization'] = "Bearer #{api_key}"
+      headers['Content-Type'] = 'application/json'
+      headers['Idempotency-Key'] ||= SecureRandom.uuid if %i[post delete].include?(method)
+      headers['User-Agent'] = "elements-ruby-sdk/#{Elements::VERSION}"
+      headers
+    end
+
+    private def request_options
+      options = {}
+      if config.ssl_verify_certs
+        options[:verify_ssl] = OpenSSL::SSL::VERIFY_PEER
+        options[:ssl_ca_file] = config.ssl_ca_file
+      else
+        options[:verify_ssl] = false
+      end
+      options
+    end
+
+    private def merge_query_params(query_params, path)
+      u = URI.parse(path)
+      return query_params, path if u.query.nil?
+
+      query_params ||= {}
+      query_params = query_params.merge(Hash[URI.decode_www_form(u.query)])
+      [query_params, u.path]
+    end
+
+    private def api_url(url, query, api_base = nil)
+      api_base ||= config.api_base
+      if query
+        "#{api_base}#{url}?#{query}"
+      else
+        "#{api_base}#{url}"
+      end
+    end
+
+    class ThreadContext
+      attr_accessor :active_client, :default_client
+    end
+  end
+end

data/lib/elements/elements_configuration.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Elements
+  # Configurations:
+  #
+  # api_base: The base URL of the Elements API, see https://elements-pay.readme.io/reference/set-up-elements.
+  #
+  # api_key: The client token required to execute requests, see https://elements-pay.readme.io/reference/fetch-client-token.
+  #
+  # max_network_retries, min_network_retry_delay, max_network_retry_delay:
+  # The client has the ability to perform automatic retries with exponential backoff,
+  # you may configure how the client retries with these variables, setting max_network_retries to 0 disable retries.
+  #
+  # ssl_ca_file: The location of a file containing a bundle of CA certificates,
+  # the library included one under lib/elements/certs and will use that as default.
+  #
+  # ssl_verify_certs: You may disable SSL verification by setting this to false.
+  #
+  # logger: When set, the library will log execution information to the prompt location.
+  # You may change the verbosity by supplying a log_level config.
+  #
+  class ElementsConfiguration
+    attr_accessor :api_base, :api_key, :max_network_retries, :min_network_retry_delay, :max_network_retry_delay,
+                  :ssl_ca_file, :ssl_verify_certs, :logger
+    attr_reader :log_level
+
+    SANDBOX_URL = 'https://api.elements-sandbox.io'
+    PRODUCTION_URL = 'https://api.elements.io'
+
+    def initialize
+      @api_base = PRODUCTION_URL
+      # disable log by default
+      @logger = Logger.new('/dev/null')
+      @log_level = Logger::DEBUG
+      @max_network_retries = 0
+      @min_network_retry_delay = 0.5
+      @max_network_retry_delay = 2.0
+      @ssl_verify_certs = true
+      @ssl_ca_file = File.expand_path('certs/cacert.pem', __dir__)
+    end
+
+    def log_level=(severity)
+      if severity.is_a?(Integer)
+        @log_level = severity
+      else
+        log_level_map = {
+          'debug' => Logger::DEBUG,
+          'info' => Logger::INFO,
+          'warn' => Logger::WARN,
+          'error' => Logger::ERROR,
+          'fatal' => Logger::FATAL,
+          'unknown' => Logger::UNKNOWN
+        }
+        severity = severity.to_s.downcase
+        raise ArgumentError, "invalid log level: #{severity}" unless
+          log_level_map.key?(severity)
+
+        @log_level = log_level_map[severity]
+      end
+    end
+
+    def reverse_duplicate_merge(hash)
+      dup.tap do |instance|
+        hash.each do |option, value|
+          instance.public_send("#{option}=", value)
+        end
+      end
+    end
+  end
+end

data/lib/elements/elements_object.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Elements
+  # A mapping from the resource JSON to a PORO.
+  # Assumes the existence of attributes such as `id`, and encourages immutability.
+  class ElementsObject
+    PERMANENT_ATTRIBUTES = [:id].freeze
+    RESERVED_FIELD_NAMES = [:class].freeze
+
+    undef :id if method_defined?(:id)
+
+    def initialize(id, attributes = nil)
+      @id = id
+      @attributes = attributes || {}
+      add_readers(attributes)
+    end
+
+    def [](key)
+      @attributes[key.to_sym]
+    end
+
+    def to_json(*opts)
+      JSON.generate(@attributes, opts)
+    end
+
+    def as_json(*opts)
+      @attributes.as_json(*opts)
+    end
+
+    protected def metaclass
+      class << self; self; end
+    end
+
+    protected def add_readers(attributes)
+      metaclass.instance_eval do
+        attributes.each_key do |k|
+          next if RESERVED_FIELD_NAMES.include?(k)
+          next if PERMANENT_ATTRIBUTES.include?(k)
+
+          if k == :method # avoid method name collision
+            define_method(k) { |*args| args.empty? ? @attributes[k] : super(*args) }
+          else
+            define_method(k) { @attributes[k] }
+          end
+
+          define_method(:"#{k}?") { @attributes[k] } if [FalseClass, TrueClass].include?(attributes[k].class)
+        end
+
+        define_method(:id) { @id }
+      end
+    end
+
+    protected def respond_to_missing?(symbol, include_private = false)
+      @attributes && @attributes.key?(symbol) || super
+    end
+  end
+end

data/lib/elements/elements_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Elements
+  class ElementsResponse
+    attr_reader :data, :body, :headers, :status
+
+    def initialize(http_resp)
+      @body = http_resp.body
+      @headers = http_resp.headers
+      @status = http_resp.code
+      @data = JSON.parse(http_resp.body, symbolize_names: true)
+    end
+  end
+end

data/lib/elements/errors.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Elements
+  # Contains the detail error information received from the Elements API,
+  # refer to https://elements-pay.readme.io/reference/errors for more information.
+  class ErrorDetails < ElementsObject
+    def type
+      @attributes[:type]
+    end
+
+    def code
+      @attributes[:code]
+    end
+
+    def message
+      @attributes[:message]
+    end
+
+    def trace_id
+      @attributes[:trace_id]
+    end
+
+    def psp_reference
+      @attributes[:psp_reference]
+    end
+
+    def param
+      @attributes[:param]
+    end
+
+    def decline_code
+      @attributes[:decline_code]
+    end
+
+    def self.from_http_body(body)
+      return nil if body.nil?
+
+      json_body = JSON.parse(body, symbolize_names: true)
+      return nil unless json_body.key?(:error)
+
+      error = json_body[:error]
+      Util.convert_to_elements_object(error)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  class ElementsError < StandardError
+    attr_reader :message, :http_status, :http_headers, :http_body, :error
+
+    attr_accessor :response
+
+    def initialize(message = nil, http_status: nil, http_headers: nil, http_body: nil)
+      super(message)
+      @message = message
+      @http_status = http_status
+      @http_headers = http_headers
+      @http_body = http_body
+      @error = ErrorDetails.from_http_body(http_body)
+    end
+  end
+
+  class APIConnectionError < ElementsError
+    CAUSE_ERROR_CLASSES = [
+      EOFError,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT,
+      SocketError,
+
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+
+      OpenSSL::SSL::SSLError,
+
+      RestClient::ServerBrokeConnection,
+      RestClient::SSLCertificateNotVerified,
+      RestClient::Exceptions::OpenTimeout,
+      RestClient::Exceptions::ReadTimeout
+    ].freeze
+  end
+
+  class GenericAPIError < ElementsError; end
+
+  class InvalidRequestError < ElementsError; end
+
+  class IdempotencyError < ElementsError; end
+
+  class AuthenticationError < ElementsError; end
+
+  class PermissionError < ElementsError; end
+
+  class RateLimitError < ElementsError; end
+
+  class CardError < ElementsError; end
+
+  class InternalServerError < ElementsError; end
+
+  module Errors
+    ERROR_CODES_TO_TYPES = {
+      "api_error": Elements::GenericAPIError,
+      "api_connection_error": Elements::APIConnectionError,
+      "authentication_error": Elements::AuthenticationError,
+      "invalid_request_error": Elements::InvalidRequestError,
+      "card_error": Elements::CardError,
+      "idempotency_error": Elements::IdempotencyError,
+      "rate_limit_error": Elements::RateLimitError,
+      "more_permissions_required": Elements::PermissionError,
+      "internal_server_error": Elements::InternalServerError
+    }.freeze
+  end
+end

data/lib/elements/logging.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Elements
+  module Logging
+    def log_error(message, data = {})
+      opts = data.delete(:opts) || {}
+      logger = opts.delete(:logger) || Elements.config.logger
+      log_level = Elements.config.log_level
+
+      log(message, data, level: Logger::ERROR, logger: logger) if logger && log_level <= Logger::ERROR
+    end
+
+    def log_warn(message, data = {})
+      opts = data.delete(:opts) || {}
+      logger = opts.delete(:logger) || Elements.config.logger
+      log_level = Elements.config.log_level
+
+      log(message, data, level: Logger::WARN, logger: logger) if logger && log_level <= Logger::WARN
+    end
+
+    def log_info(message, data = {})
+      opts = data.delete(:opts) || {}
+      logger = opts.delete(:logger) || Elements.config.logger
+      log_level = Elements.config.log_level
+
+      log(message, data, level: Logger::INFO, logger: logger) if logger && log_level <= Logger::INFO
+    end
+
+    def log_debug(message, data = {})
+      opts = data.delete(:opts) || {}
+      logger = opts.delete(:logger) || Elements.config.logger
+      log_level = Elements.config.log_level
+
+      log(message, data, level: Logger::DEBUG, logger: logger) if logger && log_level <= Logger::DEBUG
+    end
+
+    private def log(message, data = {}, level:, logger:)
+      data_str = data.map { |(k, v)| "#{k}=#{v.inspect}" }.join(' ')
+      log_str = "message=\"#{message}\" #{data_str}"
+      logger.log(level, log_str)
+    end
+  end
+end

data/lib/elements/object_types.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Elements
+  module ObjectTypes
+    def self.object_names_to_classes
+      {
+        Charge::OBJECT_NAME => Charge,
+        Dispute::OBJECT_NAME => Dispute,
+        Refund::OBJECT_NAME => Refund,
+        PaymentMethod::OBJECT_NAME => PaymentMethod,
+        PaymentMethodGateway::OBJECT_NAME => PaymentMethodGateway,
+        Token::OBJECT_NAME => Token,
+        CheckoutSession::OBJECT_NAME => CheckoutSession,
+        Customer::OBJECT_NAME => Customer
+      }
+    end
+  end
+end

data/lib/elements/resources/api_resource.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Elements
+  # All API resources, such as Charges, Refunds, are defined under lib/elements/resources.
+  #
+  # Each API resource should have an OBJECT_NAME, corresponding to the "type" in a JSON response of that resource.
+  #
+  # API endpoints are defined with `api_method`, e.g.,
+  #
+  # class MyAPIResource < APIResource
+  #   api_method :create, method: :post, path: '/api/v1/my_api_resource'
+  # end
+  #
+  # To break it down:
+  # - `:create` defines the name of the class method that invokes the API request
+  # - `method: :post` defines the HTTP verb that is associated with this endpoint
+  # - `path: '/api/v1/my_api_resource'` defines the API path
+  #
+  # To invoke this API method:
+  #
+  # params = {
+  #   foo: "bar"
+  # }
+  # headers = {
+  #   MyHeaderVar: "value"
+  # }
+  # my_api_resource = MyAPIResource.create(params, headers)
+  #
+  # Here, `params` are the API params that will be encoded automatically according to the HTTP verb.
+  # You may also supply optional headers, common headers such as `Idempotency-Key`
+  # will be supplied with a default.
+  class APIResource < ElementsObject
+    class << self
+      def execute_resource_request(method, url, params = {}, headers = {}, opts = {})
+        client = opts[:client] || ElementsClient.active_client
+
+        client.execute_request(method, url,
+                               params: params, headers: headers, opts: opts)
+      end
+
+      def api_method(name, method:, path:, parser: nil)
+        unless %i[get post delete].include?(method)
+          raise ArgumentError,
+                "Invalid method value: #{method.inspect}. Should be one " \
+                'of :get, :post or :delete.'
+        end
+
+        url_template = Addressable::Template.new(path)
+        if url_template.variables.include?('id')
+          define_resource_method(name, method, path, parser)
+        else
+          define_api_method(name, method, path, parser)
+        end
+      end
+
+      private def define_api_method(name, method, path, parser)
+        define_singleton_method(name) do |params = {}, headers = {}, opts = {}|
+          params = Elements::Util.symbolize_names(params)
+          execute_request(path, params, method, parser, headers, opts)
+        end
+      end
+
+      private def define_resource_method(name, method, path, parser)
+        define_singleton_method(name) do |id = nil, params = {}, headers = {}, opts = {}|
+          raise ArgumentError 'Missing source id' if id.nil?
+
+          params = Elements::Util.symbolize_names(params.merge!(id: id))
+          execute_request(path, params, method, parser, headers, opts)
+        end
+      end
+
+      private def execute_request(path, params, method, parser, headers, opts)
+        url_template = Addressable::Template.new(path)
+        path_params = {}
+        url_template.variables.each do |var|
+          raise ArgumentError, "Missing path param #{var}" unless params.key? var.to_sym
+
+          val = params.delete(var.to_sym)
+          path_params[var] = val
+        end
+        url = Addressable::Template.new(path).expand(path_params)&.to_str
+
+        resp = execute_resource_request(method, url, params, headers, opts)
+        json_body = JSON.parse(resp.body, symbolize_names: true)
+        if parser
+          parser.call(json_body)
+        else
+          Util.convert_to_elements_object(json_body)
+        end
+      end
+    end
+  end
+end

data/lib/elements/resources/charge.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Elements
+  class Charge < APIResource
+    OBJECT_NAME = 'charge'
+
+    api_method :create, method: :post, path: '/api/v1/charges'
+    api_method :retrieve, method: :get, path: '/api/v1/charges/{id}'
+    api_method :list, method: :get, path: '/api/v1/charges'
+    api_method :capture, method: :post, path: '/api/v1/charges/{id}/capture'
+    api_method :cancel, method: :post, path: '/api/v1/charges/{id}/cancel'
+  end
+end

data/lib/elements/resources/checkout_session.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Elements
+  class CheckoutSession < APIResource
+    OBJECT_NAME = 'checkout_session'
+
+    api_method :create, method: :post, path: '/api/v1/checkout/sessions'
+    api_method :retrieve, method: :get, path: '/api/v1/checkout/sessions/{id}'
+    api_method :list, method: :get, path: '/api/v1/checkout/sessions'
+  end
+end