direct-sdk-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 608d59a24ebd4eb3ec8e92c39cce3c00f4feeb684e8d7488dcfa84cb116a393f
+  data.tar.gz: f1361fbd5ea74f47a3c2b98cb4ab1a035c375e5874f9588b0fa4ff7842a609a8
+SHA512:
+  metadata.gz: ad5862eb925037956977f3461badbff8e317cc2748b31704649e9d82221d2a8455bc1a9bf9c646d46ab23f08918b2d9cc6583e6227f1cb2d9c140a6d0201e906
+  data.tar.gz: a7e2c636f4b33918ad34d1985a7b29e56b26bcd69ce40b633d2983f53e7a4cea5353b3a0f6e659dd951c7e76442d938cdd3c3a9a0e68ca03c3af8f335d7a14e7

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Global Collect Services B.V.
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# Ingenico Direct Ruby SDK
+
+## Introduction
+
+The Ruby SDK helps you to communicate with the [Ingenico Direct](https://support.direct.ingenico.com/) Server API. Its primary features are:
+
+* convenient Ruby library for the API calls and responses
+    * marshalls Ruby request objects to HTTP requests
+    * unmarshalls HTTP responses to Ruby response objects or Ruby exceptions
+* handling of all the details concerning authentication
+* handling of required meta data
+
+Its use is demonstrated by an example for each possible call. The examples execute a call using the provided API keys. 
+
+See the [Ingenico Direct Developer Hub](https://support.direct.ingenico.com/documentation/sdk/server/ruby/) for more information on how to use the SDK.
+
+## Structure of this repository
+
+This repository consists out of three main components:
+
+1. The source code of the SDK itself: `/lib/ingenico/direct/sdk/`
+2. The source code of the SDK unit tests: `/spec/lib/`
+3. The source code of the SDK integration tests: `/spec/integration/`
+
+Note that the source code of the unit tests and integration tests can only be found on GitHub.
+
+## Requirements
+
+Ruby 2.3 or higher is required.
+As for JRuby, version 9.0.0.0 and higher are supported.
+In addition, the following packages are required:
+
+* [httpclient](https://github.com/nahi/httpclient) 2.8 or higher
+* [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) 1.0 or higher
+
+## Installation
+
+### Using RubyGems
+
+To install the SDK using `gem`, execute the following command:
+
+    gem install direct-sdk-ruby
+
+### Using a pre-built gem
+
+1. Download the latest version of the Ruby SDK from GitHub. Choose the `direct-sdk-ruby-x.y.z.gem` file from the [releases](https://github.com/Ingenico/direct-sdk-ruby/releases) page, where `x.y.z` is the version number.
+2. Navigate into the folder where the gem file is downloaded to, and execute the following command:
+
+    ```
+    gem install direct-sdk-ruby-x.y.z.gem
+    ```
+3. Feel free to delete the gem file at this point, it is no longer required.
+
+### From source
+
+1. Download the latest version of the Ruby SDK from GitHub. Choose the `direct-sdk-ruby-x.y.z.zip` file from the [releases](https://github.com/Ingenico/direct-sdk-ruby/releases) page, where `x.y.z` is the version number.
+2. Unzip the file, navigate into the folder where the file is unzipped to, and execute the following commands:
+
+    ```
+    gem build direct-sdk-ruby.gemspec
+    gem install direct-sdk-ruby-x.y.z.gem
+    ```
+3. Feel free to delete the unzipped archive, the zip file, and the gem file at this point; they are no longer required.
+
+## Uninstalling
+
+After the Ruby SDK has been installed, it can be uninstalled using the
+following command:
+
+    gem uninstall direct-sdk-ruby
+
+The required packages can be uninstalled in the same way.
+
+## Usage
+
+After the Ruby SDK has been installed, it can be required in Ruby program as follows:
+
+    require 'ingenico/direct/sdk'
+
+## Running tests
+
+There are two types of tests: unit tests and integration tests. The unit tests will work out-of-the-box; for the integration tests some configuration is required.
+First, some environment variables need to be set:
+
+* `direct_api_apiKeyId` for the API key id to use. This can be retrieved from the Configuration Center.
+* `direct_api_secretApiKey` for the secret API key to use. This can be retrieved from the Configuration Center.
+* `direct_api_merchantId` for your merchant ID.
+
+In addition, to run the proxy integration tests, the proxy URI, username and password should be set in the `spec/fixtures/resources/properties.proxy.yml` file.
+
+In order to run the unit and integration tests, some additional dependencies are required:
+
+* [rake](https://ruby.github.io/rake/) 12.3.3 or higher
+* [rspec](https://github.com/rspec/rspec) 3.5 or higher
+* [webmock](https://github.com/bblimke/webmock) 2.1 or higher
+* [sinatra](https://github.com/sinatra/sinatra) 1.4 or higher
+
+They can be installed using the following command:
+
+    gem install rake rspec webmock sinatra
+
+*Note: if rake is already installed as part of the Ruby installation, this will cause a conflict error. This can safely be ignored.*
+
+The following commands can now be executed from the root directory of the SDK folder (/) to execute the tests:
+
+* Unit tests:
+
+    ```
+    rake unit
+    ```
+
+* Integration tests:
+
+    ```
+    rake integration
+    ```
+
+* Both unit and integration tests:
+
+    ```
+    rake spec
+    ```
+
+## Generating documentation
+
+Documentation can be generated with YARD. YARD can be installed as a gem. The gems required to generate documentation are:
+
+* [rake](https://ruby.github.io/rake/) 12.3.3 or higher
+* [yard](https://github.com/lsegal/yard) 0.9.5 or higher
+
+They can be installed using the following command:
+
+    gem install rake yard
+
+*Note: if rake is already installed as part of the Ruby installation, this will cause a conflict error. This can safely be ignored.*
+
+Once YARD and rake are installed, documentation can be generated with the following command (ran from the root folder):
+
+    rake yard
+
+Documentation will be generated in the `/doc` folder. The file `/doc/index.html` is the main documentation file.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec) do |t|  # supports automated testing using the command *rake* *spec*
+    t.rspec_opts = '--color --format documentation'
+  end
+
+  RSpec::Core::RakeTask.new(:unit) do |t|  # supports automated testing using unit tests using the command *rake* *unit*
+    t.rspec_opts = '--color --format documentation'
+    t.exclude_pattern = 'spec/integration/**'
+  end
+
+  RSpec::Core::RakeTask.new(:integration) do |t|  # supports automated testing of integration using the command *rake* *integration*
+    t.rspec_opts = '--color --format documentation'
+    t.pattern = 'spec/integration/**_spec.rb'
+  end
+
+  task :default => :spec
+rescue LoadError
+  puts '[*] error -- development dependency is not installed'
+end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new(:yard) do |t|  # supports generating documentation using the command *rake* *yard*
+      # t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+      t.options = ['--no-private']
+  end
+
+  task :doc => :yard  # alternative alias to generate documentation
+rescue LoadError
+  puts '[*] error -- development dependency is not installed'
+end

data/direct-sdk-ruby.gemspec

@@ -0,0 +1,28 @@
+Gem::Specification.new do |spec|
+  spec.name           = 'direct-sdk-ruby'
+  spec.version        = '1.0.0'
+  spec.authors        = ['Ingenico ePayments']
+  spec.email          = ['60233882+ingenico-dev-team@users.noreply.github.com']
+  spec.summary        = %q{SDK to communicate with the Ingenico ePayments platform using the Ingenico Direct Server API}
+  spec.description    = %q{SDK to communicate with the Ingenico ePayments platform using the Ingenico Direct Server API}
+  spec.homepage       = %q{https://github.com/Ingenico/direct-sdk-ruby}
+  spec.license        = 'MIT'
+
+  # exclude hidden files like .gitignore
+  spec.files          = Dir['lib/**/*'] + %w[direct-sdk-ruby.gemspec Gemfile LICENSE.txt Rakefile README.md]
+  spec.executables    = spec.files.grep(%r{^bin\/}) { |f| File.basename(f) }
+  spec.test_files     = spec.files.grep(%r{^(test|spec|features)\/})
+  spec.require_paths  = ['lib']
+
+  spec.required_ruby_version = '>= 2.0'
+
+  spec.add_dependency 'httpclient', '~> 2.8'
+  spec.add_dependency 'concurrent-ruby', '~>1.0'
+
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'rspec', '~> 3.5'
+  spec.add_development_dependency 'webmock', '~> 2.1'
+  spec.add_development_dependency 'sinatra', '~> 1.4'
+  spec.add_development_dependency 'rake', '~> 12.3', '>= 12.3.3'
+  # spec.metadata['yard.run'] = 'yri'  # compiles yard doc on install
+end

data/lib/ingenico/direct/sdk.rb

@@ -0,0 +1,26 @@
+prefix = 'ingenico/direct/sdk'
+
+require "#{prefix}/logging"
+require "#{prefix}/exceptions"
+
+require "#{prefix}/marshaller"
+require "#{prefix}/response_header"
+require "#{prefix}/authenticator"
+require "#{prefix}/data_object"
+require "#{prefix}/proxy_configuration"
+require "#{prefix}/connection"
+require "#{prefix}/pooled_connection"
+require "#{prefix}/communicator"
+require "#{prefix}/endpoint_configuration"
+require "#{prefix}/communicator_configuration"
+require "#{prefix}/client"
+require "#{prefix}/call_context"
+require "#{prefix}/api_resource"
+require "#{prefix}/request_param"
+require "#{prefix}/request_header"
+require "#{prefix}/param_request"
+require "#{prefix}/meta_data_provider"
+require "#{prefix}/factory"
+
+require "#{prefix}/defaultimpl"
+require "#{prefix}/webhooks"

data/lib/ingenico/direct/sdk/api_exception.rb

@@ -0,0 +1,42 @@
+module Ingenico::Direct::SDK
+
+  # Base class for many exceptions raised by the SDK.
+  # It is raised when an error response is received from the Ingenico ePayments platform.
+  # It contains data about the returned response.
+  #
+  # @attr_reader [Integer] status_code   HTTP status code of the returned response.
+  # @attr_reader [String]  response_body Message body of the returned response.
+  # @attr_reader [String]  error_id      An error id corresponding to the error that occurred, if available.
+  # @attr_reader [Array<Ingenico::Direct::SDK::Domain::APIError>] errors A list of errors received from the Ingenico ePayments platform;
+  #              may be empty but never _nil_
+  class ApiException < RuntimeError
+
+    # Creates a new ApiException that reports an error response from the Ingenico ePayments platform.
+    #
+    # @param status_code   (Integer) HTTP status code the response
+    # @param response_body (String) HTTP response body
+    # @param error_id      (String) error id of the error, may be _nil_
+    # @param errors        (Array<Ingenico::Direct::SDK::Domain::APIError>) a list of errors that occurred, may be empty
+    # @param message       (String) error message to include
+    def initialize(status_code, response_body, error_id, errors,
+                   message = 'the Ingenico ePayments platform returned an error response')
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+      @error_id = error_id
+      @errors = errors || [].freeze
+    end
+
+    attr_reader :status_code
+    attr_reader :response_body
+    attr_reader :error_id
+    attr_reader :errors
+
+    def to_s
+      str = super.to_s
+      str += "; status_code=#{@status_code}" if @status_code.positive?
+      str += "; response_body='#{@response_body}'" if @response_body&.length&.positive?
+      str.to_s
+    end
+  end
+end

data/lib/ingenico/direct/sdk/api_resource.rb

@@ -0,0 +1,115 @@
+require 'ingenico/direct/sdk/domain/error_response'
+
+module Ingenico::Direct::SDK
+
+  # Base class of all Ingenico ePayments platform API resources.
+  # Provides shared functionality to facilitate communication with the Ingenico ePayments platform.
+  #
+  # @attr_reader [Ingenico::Direct::SDK::Communicator] communicator Communicator instance that provides communication with the Ingenico ePayments platform.
+  # @attr_reader [String] client_meta_info JSON string containing client info specific to the current client.
+  class ApiResource
+
+    # Creates a new ApiResource.
+    #
+    # @param arg              [Ingenico::Direct::SDK::ApiResource, Ingenico::Direct::SDK::Communicator] parent class or Communicator instance.
+    #                         If a parent class is given its communicator will be used for communication.
+    # @param path_context     [Hash, nil] hash that contains substitutions for generic locations in the URL path.
+    #                         This hash will be used to instantiate a concrete URL used to access specific resources.
+    #                         For example in the URL https://payment.preprod.direct.ingenico.com/!{version}/!{merchantId}/payments
+    #                         !{version} and !{merchantId} can be instantiated using the hash
+    #                         !{'version' => 'v2', 'merchantId' => '1'}. The final URL in this case will be
+    #                         https://payment.preprod.direct.ingenico.com/v2/1/payments.
+    # @param client_meta_info [String, nil] JSON string containing the meta data for the client.
+    def initialize(arg, path_context = nil, client_meta_info = false)
+      if client_meta_info == false
+        raise ArgumentError, 'parent is required' unless arg
+
+        @parent = arg
+        @communicator = arg.communicator
+        @client_meta_info = arg.client_meta_info
+      else
+        raise ArgumentError, 'communicator is required' unless arg
+
+        @parent = nil
+        @communicator = arg
+        @client_meta_info = client_meta_info
+      end
+      @path_context = path_context
+    end
+
+    attr_reader :communicator
+    attr_reader :client_meta_info
+
+    protected
+
+    # @return [Array<Ingenico::Direct::SDK::RequestHeader>, nil] the X-GCS-ClientMetaInfo header.
+    def client_headers
+      @client_meta_info ?
+        [RequestHeader.new('X-GCS-ClientMetaInfo', @client_meta_info)] :
+        nil
+    end
+
+    def instantiate_uri(uri, path_context = nil)
+      uri = replace_all(uri, path_context) if path_context
+      uri = replace_all(uri, @path_context)
+      @parent ? @parent.instantiate_uri(uri) : uri
+    end
+
+    def create_exception(status_code, response_body, error_object, context)
+      if error_object.nil?
+        error_id = nil
+        errors = []
+      elsif error_object.is_a?(Ingenico::Direct::SDK::Domain::PaymentErrorResponse) && error_object.payment_result
+        return DeclinedPaymentException.new(status_code, response_body, error_object)
+      elsif error_object.is_a?(Ingenico::Direct::SDK::Domain::PayoutErrorResponse) && error_object.payout_result
+        return DeclinedPayoutException.new(status_code, response_body, error_object)
+      elsif error_object.is_a?(Ingenico::Direct::SDK::Domain::RefundErrorResponse) && error_object.refund_result
+        return DeclinedRefundException.new(status_code, response_body, error_object)
+      elsif error_object.is_a?(Ingenico::Direct::SDK::Domain::PaymentErrorResponse) ||
+          error_object.is_a?(Ingenico::Direct::SDK::Domain::PayoutErrorResponse) ||
+          error_object.is_a?(Ingenico::Direct::SDK::Domain::RefundErrorResponse) ||
+          error_object.is_a?(Ingenico::Direct::SDK::Domain::ErrorResponse)
+        error_id = error_object.error_id
+        errors = error_object.errors
+      else
+        raise ArgumentError, "unsupported error object type: #{error_object.class.name}"
+      end
+
+      case status_code
+        when 400
+           return ValidationException.new(status_code, response_body, error_id, errors)
+        when 403
+          return AuthorizationException.new(status_code, response_body, error_id, errors)
+        when 404, 410
+          return ReferenceException.new(status_code, response_body, error_id, errors)
+        when 409
+          if is_idempotence_error(errors, context)
+            idempotence_key = context.idempotence_key
+            idempotence_request_timestamp = context.idempotence_request_timestamp
+            return IdempotenceException.new(status_code, response_body, error_id,
+                                            errors, idempotence_key,
+                                            idempotence_request_timestamp)
+          else
+            return ReferenceException.new(status_code, response_body, error_id, errors)
+          end
+        when 500, 502, 503
+          return DirectException.new(status_code, response_body, error_id, errors)
+        else
+          return ApiException.new(status_code, response_body, error_id, errors)
+      end
+    end
+
+    private
+
+    def replace_all(uri, path_context)
+      path_context&.each do |key, value|
+        uri = uri.gsub("{#{key}}", value)
+      end
+      uri
+    end
+
+    def is_idempotence_error(errors, context)
+      context&.idempotence_key && errors.length == 1 && errors[0].code == '1409'
+    end
+  end
+end

data/lib/ingenico/direct/sdk/authenticator.rb

@@ -0,0 +1,16 @@
+module Ingenico::Direct::SDK
+
+  # Abstract class that is responsible for authenticating requests sent to the Ingenico ePayments platform.
+  class Authenticator
+
+    # Creates a signature to authenticate a request.
+    #
+    # @param http_method     [String] 'GET', 'PUT', 'POST' or 'DELETE' indicating which HTTP method will be used with the request
+    # @param resource_uri    [URI::HTTP] URI object that includes #path and #query of the URL that will be used, #query may be *nil*
+    # @param request_headers [Array<Ingenico::Direct::SDK::RequestHeader>] all headers used by the request
+    # @return [String] the created signature
+    def create_simple_authentication_signature(http_method, resource_uri, request_headers)
+      raise NotImplementedError
+    end
+  end
+end