erp_integration 0.2.0

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/reek

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'reek' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('reek', 'reek')

data/bin/release

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+VERSION=$1
+
+# Build the new gem and publish it to Rubygems.
+gem build erp_integration.gemspec
+gem push "erp_integration-$VERSION.gem" --host https://rubygems.org
+rm "erp_integration-$VERSION.gem"

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/erp_integration.gemspec

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'lib/erp_integration/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'erp_integration'
+  spec.version       = ErpIntegration::VERSION
+  spec.authors       = ['Stefan Vermaas']
+  spec.email         = ['stefan@knowndecimal.com']
+
+  spec.summary       = 'Connects Mejuri with third-party ERP vendors'
+  spec.license       = 'MIT'
+  spec.homepage      = 'https://www.github.com/mejuri-inc/erp-integration'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.7')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://www.github.com/mejuri-inc/erp-integration'
+  spec.metadata['changelog_uri'] = 'https://www.github.com/mejuri-inc/erp-integration/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # ActiveSupport is used for extended support of String inflections.
+  spec.add_dependency 'activesupport', '>= 0.12'
+
+  # Faraday is a HTTP/REST API client library to interact with third-party API vendors
+  spec.add_dependency 'faraday', '>= 0.17.3', '< 1.8.0'
+  spec.add_dependency 'faraday_middleware', '~> 0.14.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'byebug', '~> 11.0'
+  spec.add_development_dependency 'flay', '~> 2.12', '>= 2.12.1'
+  spec.add_development_dependency 'github_changelog_generator', '~> 1.15.2'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'reek', '< 6.0'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rubocop', '< 0.82.0'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.5'
+  spec.add_development_dependency 'rubocop-rspec', '< 1.39.0'
+  spec.add_development_dependency 'webmock', '~> 3.14.0'
+
+  # The `parallel` gem is a dev dependency for Rubocop. However, the versions
+  # for parallel after 1.19.2 don't work with ruby 2.3.x. As ruby 2.3.x is
+  # required for Mejuri, we're manually locking it to stay on `1.19.2`.
+  spec.add_development_dependency 'parallel', '1.19.2'
+end

data/lib/erp_integration/clients/fulfil_client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'faraday_middleware'
+
+module ErpIntegration
+  module Clients
+    # The `FulfilClient` is a simple HTTP client configured to be used for API
+    # requests to the Fulfil endpoints.
+    class FulfilClient
+      attr_reader :api_key, :merchant_id
+      attr_writer :connection, :faraday_adapter
+
+      def initialize(api_key:, merchant_id:)
+        @api_key = api_key
+        @merchant_id = merchant_id
+      end
+
+      # Generates the url prefix for the Faraday connection client.
+      # @return [String] The base url for the Fulfil HTTP client
+      def base_url
+        "https://#{merchant_id}.fulfil.io/"
+      end
+
+      # Sets the default adapter for the Faraday Connection.
+      # @return [Symbol] The default Faraday adapter
+      def faraday_adapter
+        @faraday_adapter ||= Faraday.default_adapter
+      end
+
+      # Sets up the Faraday connection to talk to the Fulfil API.
+      # @return [Faraday::Connection] The configured Faraday connection
+      def connection
+        @connection ||= Faraday.new(url: base_url) do |faraday|
+          faraday.headers = default_headers
+
+          faraday.request :json # Encode request bodies as JSON
+          faraday.request :retry # Retry transient failures
+
+          faraday.response :follow_redirects
+          faraday.response :json # Decode response bodies as JSON
+
+          # Custom error handling for the error response
+          faraday.use ErpIntegration::Middleware::ErrorHandling
+
+          # Adapter definition should be last in order to make the json parsers be loaded correctly
+          faraday.adapter faraday_adapter
+        end
+      end
+
+      %i[delete get patch put post].each do |action_name|
+        define_method(action_name) do |path, options = {}|
+          connection.public_send(action_name, "api/#{version}/#{path}", options).body
+        end
+      end
+
+      # Sets the default version for the Fulfil API endpoints.
+      # @return [String] The Fulfil API version to be used
+      def version
+        @version ||= 'v2'
+      end
+
+      private
+
+      def default_headers
+        {
+          'Accept': 'application/json',
+          'Content-Type': 'application/json',
+          'X-API-KEY': api_key
+        }
+      end
+    end
+  end
+end

data/lib/erp_integration/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  # Use the `Configuration` class to configure the ERP Integration gem. Use
+  # an initializer in your project configure the ERP Integration gem.
+  #
+  # @example
+  #   ```ruby
+  #     # config/initializers/erp_integration.rb
+  #     ErpIntegration.configure do |config|
+  #       config.fulfil_api_key = "..."
+  #     end
+  #   ```
+  class Configuration
+    # The `fulfil_api_key` is used by the `FulfilClient` to authorize the
+    # requests to the Fulfil API endpoints.
+    # @return [String] The API key for Fulfil.
+    attr_accessor :fulfil_api_key
+
+    # The `fulfil_merchant_id` is used by the `FulfilClient` to connect to
+    # the right Fulfil API endpoints.
+    # @return [String] The merchant ID for Fulfil.
+    attr_accessor :fulfil_merchant_id
+
+    # Allows configuring an adapter for the `Order` resource. When none is
+    # configured, it will default to Fulfil.
+    # @return [Symbol] The configured adapter for the orders
+    attr_writer :order_adapter
+
+    def initialize(**options)
+      options.each_pair do |key, value|
+        public_send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+
+    def order_adapter
+      @order_adapter || :fulfil
+    end
+  end
+
+  # Returns ERP Integration's configuration.
+  # @return [ErpIntegration::Configuration] ERP Integration's configuration
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Allows setting a new configuration for the ERP Integration gem.
+  # @return [ErpIntegration::Configuration] ERP Integration's new configuration
+  def self.config=(configuration)
+    raise BadConfiguration unless configuration.is_a?(Configuration)
+
+    @config = configuration
+  end
+
+  # Allows modifying ERP Integration's configuration.
+  #
+  # @example
+  #   ErpIntegration.configure do |config|
+  #     config.some_api_key = "..."
+  #   end
+  #
+  def self.configure
+    yield(config)
+  end
+end

data/lib/erp_integration/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  # The `ErpIntegration::Error` is the default error class for any exception raised
+  # on purpose by this gem.
+  class Error < StandardError; end
+
+  # The `ErpIntegration::BadConfiguration` is raised whenever the newly provided
+  # configuration is not a valid configuration object.
+  class BadConfiguration < Error
+    def initialize
+      super(
+        '[ERP Integration] The provided configuration object is not a ' \
+          'ErpIntegration::Configuration instance. Please provide a '  \
+          'ErpIntegration::Configuration instance when overriding the configuration directly.'
+      )
+    end
+  end
+
+  class HttpError < Faraday::Error
+    class BadRequest < HttpError; end
+    class AuthorizationRequired < HttpError; end
+    class PaymentRequired < HttpError; end
+    class Forbidden < HttpError; end
+    class NotFound < HttpError; end
+    class MethodNotAllowed < HttpError; end
+    class NotAccepted < HttpError; end
+    class UnprocessableEntity < HttpError; end
+    class TooManyRequests < HttpError; end
+    class InternalServerError < HttpError; end
+  end
+end

data/lib/erp_integration/middleware/error_handling.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  module Middleware
+    # The `ErrorHandling` middleware allows to raise our own exceptions that
+    # are easier to catch for the host application (e.g. `mejuri-web`).
+    class ErrorHandling < Faraday::Response::Middleware
+      HTTP_ERROR_CODES = {
+        400 => ErpIntegration::HttpError::BadRequest,
+        401 => ErpIntegration::HttpError::AuthorizationRequired,
+        402 => ErpIntegration::HttpError::PaymentRequired,
+        403 => ErpIntegration::HttpError::Forbidden,
+        404 => ErpIntegration::HttpError::NotFound,
+        405 => ErpIntegration::HttpError::MethodNotAllowed,
+        406 => ErpIntegration::HttpError::NotAccepted,
+        422 => ErpIntegration::HttpError::UnprocessableEntity,
+        429 => ErpIntegration::HttpError::TooManyRequests,
+        500 => ErpIntegration::HttpError::InternalServerError
+      }.freeze
+
+      def on_complete(response)
+        key = response[:status].to_i
+        raise HTTP_ERROR_CODES[key], response_values(response) if HTTP_ERROR_CODES.key?(key)
+      end
+
+      def response_values(response)
+        { status: response.status, headers: response.response_headers, body: response.body }
+      end
+    end
+  end
+end

data/lib/erp_integration/order.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  # The `Order` class exposes available ERP Order operations
+  # assigning them to the proper adapter
+  class Order < Resource
+    attr_accessor :id, :number
+
+    # Allows cancelling the entire sales order.
+    # @param id [Integer|String] The ID of the to be cancelled order.
+    # @return [boolean] Whether the sales order was cancelled successfully or not.
+    def self.cancel(id)
+      adapter.new.cancel(id)
+    end
+  end
+end

data/lib/erp_integration/orders/fulfil_order.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  module Orders
+    # The `FulfilOrder` handles all interaction with sales orders in Fulfil.
+    class FulfilOrder
+      extend Forwardable
+      def_delegator 'ErpIntegration', :config
+
+      # Allows cancelling the entire sales order in Fulfil.
+      # @param id [Integer|String] The ID of the to be cancelled order.
+      # @return [boolean] Whether the sales order was cancelled successfully or not.
+      def cancel(id)
+        client.put("model/sale.sale/#{id}/cancel")
+        true
+
+      # Fulfil will return an 400 (a.k.a. "Bad Request") status code when a sales order couldn't
+      # be cancelled. If a sales order isn't cancellable by design, no exception should be raised.
+      #
+      # See the Fulfil's documentation for more information:
+      # https://developers.fulfil.io/rest_api/model/sale.sale/#cancel-a-sales-order
+      rescue ErpIntegration::HttpError::BadRequest
+        false
+      end
+
+      private
+
+      def client
+        @client ||= Clients::FulfilClient.new(
+          api_key: config.fulfil_api_key,
+          merchant_id: config.fulfil_merchant_id
+        )
+      end
+    end
+  end
+end

data/lib/erp_integration/resource.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  # The `ErpIntegration::Resource` is a generic, re-usable model for third-party sources.
+  #
+  # For the `ErpIntegration::Resource`, we're using the adapter pattern.
+  # Meaning; the `ErpIntegration::Resource` is a facade that delegates the
+  # actual work to an adapter.
+  #
+  # Every class that inherits from the `ErpIntegration::Resource`, will be able
+  # to configure a designated adapter. This allows configuring an adapter
+  # per resource to maximize the flexibility.
+  #
+  # @example
+  #   ErpIntegration.configure do |config|
+  #     config.order_adapter = :fulfil
+  #   end
+  #
+  #   $ ErpIntegration::Order.adapter
+  #   => #<ErpIntegration::Orders::FulfilOrder />
+  #
+  # To add a new resource, follow these steps:
+  #   1. Add a new `attr_writer` in the `ErpIntegration::Configuration` class.
+  #   2. Add a new method to the `ErpIntegration::Configuration` that sets up the
+  #      default adapter.
+  #   3. Create a new generic resource model in the `lib/erp_integration` folder.
+  #   4. Create a new pluralized folder name in the `lib/erp_integration` folder
+  #      (e.g. `orders` for the `Order` resource).
+  #   5. Create a new adapter class prefixed with the adapter's name
+  #      (e.g. `FulfilOrder` for the `Order` resource in the `lib/erp_integration/orders` folder).
+  class Resource
+    attr_accessor :raw_api_response
+
+    def initialize(attributes = {})
+      @raw_api_response = attributes
+
+      attributes.each_pair do |name, value|
+        public_send(:"#{name}=", value) if respond_to?(:"#{name}=")
+      end
+    end
+
+    class << self
+      # Dynamically defines and loads the adapter for the class inheriting from
+      # the `ErpIntegration::Resource`.
+      # @return [Class] The adapter class for the resource.
+      def adapter
+        return @adapter if defined?(@adapter)
+
+        require_relative File.join(File.dirname(__FILE__), '..', "#{adapter_path}.rb")
+        @adapter = adapter_klass.constantize
+      end
+
+      # Dynamically exposes the adapter class to the resource.
+      # @return [String] the adapter class as a string
+      def adapter_klass
+        "ErpIntegration::#{adapter_path.classify}"
+      end
+
+      # Retrieves the adapter type for the resource from the global configuration.
+      # @return [String] the adapter type for the resource
+      def adapter_type
+        ErpIntegration.config.send("#{resource_name}_adapter").to_s
+      end
+
+      # Provides a relative path to the adapter for the resource.
+      # @return [String] the path to the adapter
+      def adapter_path
+        "#{resource_name.pluralize}/#{adapter_type}_#{resource_name}"
+      end
+
+      # Derives the name of the resource from the class name.
+      # @return [String] the resource name
+      def resource_name
+        name.split('::').last.underscore
+      end
+    end
+  end
+end

data/lib/erp_integration/version.rb

@@ -0,0 +1,3 @@
+module ErpIntegration
+  VERSION = "0.2.0".freeze
+end

data/lib/erp_integration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+require 'faraday'
+require 'json'
+
+require_relative 'erp_integration/version'
+require_relative 'erp_integration/errors'
+require_relative 'erp_integration/configuration'
+
+# Middleware
+require_relative 'erp_integration/middleware/error_handling'
+
+# Resources
+require_relative 'erp_integration/resource'
+require_relative 'erp_integration/order'
+
+# HTTP clients
+require_relative 'erp_integration/clients/fulfil_client'
+
+# The `ErpIntegration` integrates Mejuri with third-party ERP vendors.
+module ErpIntegration
+end