erp_integration 0.5.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ef3df17fffd25f4bb3d44b59fa8a2a2b4495a4d159cb22e06b5fdb852422d19
-  data.tar.gz: b9368f71c9adf3b70324ca550370a607e40b97a18588f3719aa541f132debe81
+  metadata.gz: 0b7edee1b77a371325210af94802cbd0d6c1df5d730bcfd8d9d326bc8a5eb2c3
+  data.tar.gz: d59ecb758fde883746da4fec059e99c53b71f7a526f81d7fa272eb139f567ff4
 SHA512:
-  metadata.gz: 208f536ae2693e7d7c0f9541b16d86341deaa8216de7511df93819e0729a71a03aaca4a9f76330707b3a08bb10f2a8b3760f313079fbb43c2bda3968e50ceb4f
-  data.tar.gz: 45d12d1855b3d3326072cf39ee1ad5cbde463ed7562bbb8d4fc7ab9c92832904b4834f66d3599a3d89a6d84e1cd854d35bea407ef865a5e8854182ac0c8b1451
+  metadata.gz: 0c34649c0ab233be00b9e9b35897faa934eb85824318528f7df4261b8f093319902d82636bd6e4cbba22d82afec604e6d4136b6f64ad7398ee2227aa5b17dca9
+  data.tar.gz: 70cac86409b77043c0d0ec4f62946d01b48bd96b4abfaaf88c3b57f9600ada205c505b072ac91836ca693621c37302e2223b65b2769e8157ff2fe0b4c734eb10

data/README.md

@@ -1,6 +1,6 @@
 # Mejuri's ERP integration
 
-TODO: Add a accurate description for the gem.
+The ERP integration gem allows connecting to multiple ERP at the same time and query the data from these ERP's. It's currently only supporting [Fulfil](https://www.fulfil.io).
 
 ## Installation
 
@@ -16,8 +16,6 @@ Or run the following command to add `ErpIntegration` to your Gemfile:
   $ bundle add erp_integration
 ```
 
-TODO: Write installation instructions here for the Github package registry.
-
 ## Usage
 
 ### Configuration
@@ -32,20 +30,15 @@ ErpIntegration.configure do |config|
 end
 ```
 
-### Querying third-party vendors
-
-After configuring the gem, one can easily query all the available ERP resources from the connected third-parties.
+### Supported Query Methods
 
-```ruby
-$ ErpIntegration::SalesOrder.where(reference: 'MT1000SKX')
-=> #<ErpIntegration::Fulfil::Collection @items=[<ErpIntegration::SalesOrder @id=100 />] />
-```
+After configuring the gem, one can easily query all the available ERP resources from the connected third-parties. In all cases, the API will return a collection of resources.
 
-By default, only the `id` will be added to the found ERP resources. However, one can use the `select` method to include more fields.
+> **NOTE**: If you need to lookup an individual resource take a look at the "Supported finder methods" section.
 
 ```ruby
-$ ErpIntegration::SalesOrder.select(:id, :reference).where(reference: 'MT1000SKX')
-=> #<ErpIntegration::Fulfil::Collection @items=[<ErpIntegration::SalesOrder @id=100 @reference=MT1000SKX />] />
+$ ErpIntegration::SalesOrder.where(reference: 'MT1000SKX')
+=> [<ErpIntegration::SalesOrder @id=100 />]
 ```
 
 There are also other type of `where` queries available:
@@ -55,50 +48,81 @@ There are also other type of `where` queries available:
 - `where_in` for inclusion queries.
 - `where_not_in` for exclusion queries.
 
-## Development
+### Supported Finder Methods
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+The __Query Methods__ allow you to lookup a list of resources. The __Finder Methods__ allow you to lookup **an individual resource** from the API.
 
-TODO: Write instructions for publishing the gem to the Github package registry.
+- `#find` looks up a resource by id and raises `ErpIntegration::ResourceNotFound` when no result is found.
+- `#find_by` looks up a resource by a given set of query methods and returns `nil` when no result is found.
+- `#find_by!` looks up a resource by a given set of query methods and raises `ErpIntegration::ResourceNotFound` when no result is found.
 
-## Contributing
+A difference between the query methods and the finder methods is the way it's executed. The finder methods are executed directly after they're called. The query methods will be lazily executed.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/mejuri-inc/erp_integration. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/mejuri-inc/erp_integration/blob/main/CODE_OF_CONDUCT.md).
+```ruby
+$ ErpIntegration::SalesOrder.find(100)
+# => #<ErpIntegration::SalesOrder @id=100 />
 
-## License
+$ ErpIntegration::SalesOrder.find_by(code: "MT100")
+# => #<ErpIntegration::SalesOrder @id=100 />
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+$ ErpIntegration::SalesOrder.find_by!(code: "MT100")
+# => #<ErpIntegration::SalesOrder @id=100 />
+```
 
-## Code of Conduct
+### Supported Selection Methods
 
-Everyone interacting in the ErpIntegration project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mejuri-inc/erp_integration/blob/main/CODE_OF_CONDUCT.md).
+By default, only the `id` will be added to ERP resources. However, one can use the `select` method to include more fields.
+
+```ruby
+$ ErpIntegration::SalesOrder.select(:id, :reference).find_by(reference: 'MT1000SKX')
+# => <ErpIntegration::SalesOrder @id=100 @reference=MT1000SKX />
+```
+
+## Development
 
-## Releasing
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Releasing
 
-### Prerequisites
+**Prerequisites**
 
 To be able to publish a new release, you'll need to set up a Rubygems account.
 
 > To begin, you’ll need to create an account on RubyGems.org. Visit the sign up page and supply an email address that you control, a handle (username) and a password.
 >
 > After creating the account, use your email and password when pushing the gem. (RubyGems saves the credentials in ~/.gem/credentials for you so you only need to log in once.)
-> - [Publishing to RubyGems.org](https://guides.rubygems.org/publishing/)
+>  [Publishing to RubyGems.org](https://guides.rubygems.org/publishing/)
 
-It's important to note that you'll need the right privileges to publish the gem. Ask @germansvriz to add you as a gem owner.
+It's important to note that you'll need the right privileges to publish the gem. Ask [@germansvriz](https://github.com/germansvriz) or [@stefanvermaas](https://github.com/stefanvermaas) to add you as a gem owner.
 
-### Publish a new version
+**Publish a new version**
 
-1 - Run the prerelease script
-```shell
-$ bin/prerelease 0.0.1
-```
-2 - Create Pull Request
-3 - Merge it to main
-4 - Run Release script
-```shell
-$ bin/release 0.0.1
-```
+1. Run the prerelease script
+  ```shell
+  $ bin/prerelease 0.0.1
+  ```
+
+2. Create Pull Request
+
+3. Merge it to main
+
+4. Run Release script
+  ```shell
+  $ bin/release 0.0.1
+  ```
 
 We're following [semver](https://semver.org/) for the release process of this gem. Make sure to apply the correct semver version for a new release.
 
 > **NOTE**: You don't have to add a `v` to the version you want to release. The release script will handle that for you.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mejuri-inc/erp_integration. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/mejuri-inc/erp_integration/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ErpIntegration project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mejuri-inc/erp_integration/blob/main/CODE_OF_CONDUCT.md).

data/lib/erp_integration/bill_of_material_input.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  # The `ErpIntegration::BillOfMaterialInput` exposes an uniformed API for interaction with
+  # third-party ERP vendors.
+  class BillOfMaterialInput < Resource
+    attr_accessor :attachments, :bom, :create_date, :create_uid, :id, :messages,
+                  :metadata, :private_notes, :product, :public_notes, :quantity,
+                  :rec_blurb, :rec_name, :sequence, :to_location, :unit_digits,
+                  :uom, :uom_category, :warehouse, :write_date, :write_uid
+  end
+end

data/lib/erp_integration/bill_of_material_output.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  # The `ErpIntegration::BillOfMaterialOutput` exposes an uniformed API for interaction with
+  # third-party ERP vendors.
+  class BillOfMaterialOutput < Resource
+    attr_accessor :attachments, :bom, :create_date, :create_uid, :id, :messages,
+                  :metadata, :private_notes, :product, :public_notes, :quantity,
+                  :rec_blurb, :rec_name, :sequence, :to_location, :unit_digits,
+                  :uom, :uom_category, :warehouse, :write_date, :write_uid
+  end
+end

data/lib/erp_integration/configuration.rb

@@ -27,6 +27,16 @@ module ErpIntegration
     # @return [Symbol] The configured adapter for the bill_of_material.
     attr_writer :bill_of_material_adapter
 
+    # Allows configuring an adapter for the `BillOfMaterialInput` resource. When
+    # none is configured, it will default to Fulfil.
+    # @return [Symbol] The configured adapter for the Bill of Material's input.
+    attr_writer :bill_of_material_input_adapter
+
+    # Allows configuring an adapter for the `BillOfMaterialOutput` resource. When
+    # none is configured, it will default to Fulfil.
+    # @return [Symbol] The configured adapter for the bill_of_material.
+    attr_writer :bill_of_material_output_adapter
+
     # Allows configuring an adapter for the `Product` resource. When none is
     # configured, it will default to Fulfil.
     # @return [Symbol] The configured adapter for the products.
@@ -82,6 +92,14 @@ module ErpIntegration
       @bill_of_material_adapter || :fulfil
     end
 
+    def bill_of_material_input_adapter
+      @bill_of_material_input_adapter || :fulfil
+    end
+
+    def bill_of_material_output_adapter
+      @bill_of_material_output_adapter || :fulfil
+    end
+
     def product_adapter
       @product_adapter || :fulfil
     end

data/lib/erp_integration/errors.rb

@@ -17,6 +17,12 @@ module ErpIntegration
     end
   end
 
+  class ResourceNotFound < Error
+    def initialize
+      super "[ERP Integration] Couldn't find the requested resource."
+    end
+  end
+
   class HttpError < Faraday::Error
     class BadRequest < HttpError; end
     class AuthorizationRequired < HttpError; end

data/lib/erp_integration/fulfil/api_resource.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative 'finder_methods'
+require_relative 'persistence'
 require_relative 'query_methods'
 
 module ErpIntegration
   module Fulfil
     class ApiResource
       include Enumerable
+      include FinderMethods
+      include Persistence
       include QueryMethods
 
       attr_accessor :resource_klass

data/lib/erp_integration/fulfil/finder_methods.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  module Fulfil
+    # The `FinderMethods` add various, simplistic lookup methods to find API resources.
+    # These methods should be the last method in the chain as it will invoke the HTTP
+    # request to Fulfil immediately.
+    #
+    # If you need more attributes than the default ID attribute for an ApiResource
+    # to be returned, add the `select` method before the finder method is being called
+    # in your application code.
+    #
+    # @example
+    #   $ ErpIntegration::SalesOrder.select(:id, :product).find(100)
+    #   => <ErpIntegration::SalesOrder @id=100 @product=10 />
+    module FinderMethods
+      # Looks up an individual resource based on resource's ID.
+      #
+      # @example
+      #   $ ErpIntegration::SalesOrder.find(100)
+      #   => <ErpIntegration::SalesOrder @id=100 />
+      #
+      # @param id [Integer] The ID of the API resource.
+      # @return [ApiResource] The found resource in Fulfil.
+      def find(id)
+        find_by!(id: id) || raise(ResourceNotFound)
+      end
+
+      # Looks up an individual resource based on the given attributes.
+      #
+      # @example
+      #   $ ErpIntegration::SalesOrder.find_by(product: 10)
+      #   => <ErpIntegration::SalesOrder @id=100 />
+      #
+      # @return [ApiResource|nil] The found resource in Fulfil.
+      def find_by(args)
+        where(args).first
+      end
+
+      # Looks up an individual resource based on the given attributes and raises
+      # an `ErpIntegration::ResourceNotFound` when the resource doesn't exist.
+      #
+      # @example
+      #   $ ErpIntegration::SalesOrder.find_by!(product: 10)
+      #   => ErpIntegration::ResourceNotFound
+      #
+      # @return [ApiResource|nil] The found resource in Fulfil.
+      def find_by!(args)
+        find_by(args) || raise(ResourceNotFound)
+      end
+    end
+  end
+end

data/lib/erp_integration/fulfil/persistence.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  module Fulfil
+    module Persistence
+      # Allows creating new resources in Fulfil.
+      #
+      # @example
+      #   $ ErpIntegration::Product.create(code: 'MT100eu', variant: 10)
+      #   => <ErpIntegration::Product @id=2 @code="MT100eu" @variant=10 />
+      #
+      # @param attributes [Hash] A list of attributes.
+      # @return [ErpIntegration::Resource] The newly created resource.
+      def create(attributes = {})
+        client
+          .post("model/#{model_name}", normalize_attributes(attributes))
+          .map { |new_record_id| resource_klass.new(attributes.merge(id: new_record_id)) }
+          .first
+      rescue ErpIntegration::HttpError::BadRequest => e
+        record = resource_klass.new(attributes)
+        record.errors.add(extract_error_message(e))
+        record
+      end
+
+      private
+
+      # Fulfil returns a 400 status code (e.g. Bad Request) with the error message
+      # in the body. We're using the exception to extract the error message in the
+      # body of the original response from Fulfil.
+      #
+      # @param error [ErpIntegration::HttpError::BadRequest] The exception raised by our middleware.
+      # @return [String] The error message by Fulfil.
+      def extract_error_message(error)
+        JSON.parse(error.response[:body]).fetch('message')
+      end
+
+      # Fulfil always expects an array of attributes. That way, we could also create
+      # a whole bunch of objects all at once. We don't support creating multiple records
+      # yet as it's not needed yet. However, we do need to normalize the attributes we're
+      # passing to the Fulfil API.
+      #
+      # @param attributes [Hash|Array<Hash>] The attributes for the new resource.
+      # @return [Array<Hash>] The normalized attributes.
+      def normalize_attributes(attributes)
+        attrs = attributes.is_a?(Array) ? attributes : [attributes]
+        attrs.compact
+      end
+    end
+  end
+end

data/lib/erp_integration/fulfil/resources/bill_of_material_input.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../api_resource'
+
+module ErpIntegration
+  module Fulfil
+    module Resources
+      class BillOfMaterialInput < ApiResource
+        self.model_name = 'production.bom.input'
+      end
+    end
+  end
+end

data/lib/erp_integration/fulfil/resources/bill_of_material_output.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../api_resource'
+
+module ErpIntegration
+  module Fulfil
+    module Resources
+      class BillOfMaterialOutput < ApiResource
+        self.model_name = 'production.bom.output'
+      end
+    end
+  end
+end

data/lib/erp_integration/fulfil/resources/product.rb

@@ -12,7 +12,7 @@ module ErpIntegration
         # @param sku [String] The product's SKU.
         # @return [Boolean] Whether it's a BOM or not.
         def bom?(sku)
-          select(:boms).where(code: sku).first.boms.any?
+          select(:boms).find_by!(code: sku).boms.any?
         end
         alias billing_of_materials? bom?
       end

data/lib/erp_integration/fulfil/resources/sales_order_line.rb

@@ -7,6 +7,45 @@ module ErpIntegration
     module Resources
       class SalesOrderLine < ApiResource
         self.model_name = 'sale.line'
+        # Allows cancelling the entire sales order line in Fulfil.
+        # @param id [Integer|String] The ID of the to be cancelled order line.
+        # @return [boolean] Whether the sales order line was cancelled successfully or not.
+        def cancel(id)
+          client.put("model/sale.line/#{id}/cancel")
+          true
+        rescue ErpIntegration::HttpError::BadRequest
+          false
+        # Workaround: Fulfil api does not return a json when status code is 200 (a.k.a. "Ok")
+        # and faraday is having an error when trying to parse it. Let's skip the parse error
+        # and move on.
+        rescue Faraday::ParsingError
+          true
+        end
+
+        # Updates the sales order line quantity of canceled and non canceled items
+        # @param sales_channel [Integer] Sales channel id
+        # @param channel_identifier [String]
+        # @param sku [String]
+        # @param quantity [Integer] The total quantity (canceled + not canceled)
+        #   Should be more or equal than quantity_canceled but the above criteria is suggested
+        # @param quantity_canceled [Integer] the total quantity of canceled items (including new ones)
+        # @return [boolean] Whether the sales order line was changed successfully or not.
+        def adjust_quantity(sales_channel, channel_identifier,
+                            sku, quantity, quantity_canceled)
+          options = [{
+            "channel_identifier": channel_identifier,
+            "sale_lines":
+              [{
+                "sku": sku,
+                "quantity": quantity,
+                "quantity_canceled": quantity_canceled
+              }]
+          }]
+          client.put("model/sale.channel/#{sales_channel}/create_order", options)
+          true
+        rescue ErpIntegration::HttpError::BadRequest
+          false
+        end
       end
     end
   end

data/lib/erp_integration/resource.rb

@@ -39,6 +39,12 @@ module ErpIntegration
       end
     end
 
+    # Exposes all errors related to an `ErpIntegration::Resource`.
+    # @return [ErpIntegration::Resources::Errors] Encapsulation of all error messages.
+    def errors
+      @errors ||= Resources::Errors.new
+    end
+
     class << self
       # Dynamically defines and loads the adapter for the class inheriting from
       # the `ErpIntegration::Resource`.

data/lib/erp_integration/resources/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ErpIntegration
+  module Resources
+    # The `ErpIntegration::Resources::Errors` expose a clean, simple API to manage
+    # and display error messages for any `ErpIntegration::Resource` instance.
+    class Errors
+      include Enumerable
+
+      extend Forwardable
+      def_delegators :@errors, :any?, :blank?, :clear, :count, :empty?, :uniq!, :size
+
+      def initialize
+        @errors = []
+      end
+
+      # Allows adding new error messages to the `ErpIntegration::Resource`.
+      # @param message [String] An (internal/external) error message.
+      # @return [String] The given error message.
+      def add(message)
+        raise ErpIntegration::Error, 'Use a simple string as an error message' unless message.is_a?(String)
+
+        @errors << message
+        message
+      end
+
+      def each(&block)
+        @errors.each(&block)
+      end
+    end
+  end
+end

data/lib/erp_integration/sales_order_line.rb

@@ -12,5 +12,13 @@ module ErpIntegration
                   :quantity_reserved, :quantity_shipped, :return_reason, :sale,
                   :sequence, :shipping_date, :taxes, :type, :warehouse, :write_date,
                   :write_uid
+
+    def cancel(id)
+      self.class.adapter.cancel(id)
+    end
+
+    def adjust_quantity(sales_channel, channel_identifier, sku, quantity, quantity_canceled)
+      self.class.adapter.adjust_quantity(sales_channel, channel_identifier, sku, quantity, quantity_canceled)
+    end
   end
 end

data/lib/erp_integration/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ErpIntegration
-  VERSION = '0.5.3'
+  VERSION = '0.7.0'
 end

data/lib/erp_integration.rb

@@ -21,6 +21,8 @@ require_relative 'erp_integration/fulfil/client'
 module ErpIntegration
   # Resources
   autoload :BillOfMaterial, 'erp_integration/bill_of_material'
+  autoload :BillOfMaterialInput, 'erp_integration/bill_of_material_input'
+  autoload :BillOfMaterialOutput, 'erp_integration/bill_of_material_output'
   autoload :Product, 'erp_integration/product'
   autoload :ProductionOrder, 'erp_integration/production_order'
   autoload :PurchaseOrder, 'erp_integration/purchase_order'
@@ -31,4 +33,8 @@ module ErpIntegration
   autoload :SalesOrderLine, 'erp_integration/sales_order_line'
   autoload :StockMove, 'erp_integration/stock_move'
   autoload :SupplierShipment, 'erp_integration/supplier_shipment'
+
+  module Resources
+    autoload :Errors, 'erp_integration/resources/errors'
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: erp_integration
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Stefan Vermaas
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-10-27 00:00:00.000000000 Z
+date: 2022-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -260,13 +260,19 @@ files:
 - erp_integration.gemspec
 - lib/erp_integration.rb
 - lib/erp_integration/bill_of_material.rb
+- lib/erp_integration/bill_of_material_input.rb
+- lib/erp_integration/bill_of_material_output.rb
 - lib/erp_integration/configuration.rb
 - lib/erp_integration/errors.rb
 - lib/erp_integration/fulfil/api_resource.rb
 - lib/erp_integration/fulfil/client.rb
+- lib/erp_integration/fulfil/finder_methods.rb
+- lib/erp_integration/fulfil/persistence.rb
 - lib/erp_integration/fulfil/query.rb
 - lib/erp_integration/fulfil/query_methods.rb
 - lib/erp_integration/fulfil/resources/bill_of_material.rb
+- lib/erp_integration/fulfil/resources/bill_of_material_input.rb
+- lib/erp_integration/fulfil/resources/bill_of_material_output.rb
 - lib/erp_integration/fulfil/resources/product.rb
 - lib/erp_integration/fulfil/resources/production_order.rb
 - lib/erp_integration/fulfil/resources/purchase_order.rb
@@ -284,6 +290,7 @@ files:
 - lib/erp_integration/purchase_order_line.rb
 - lib/erp_integration/purchase_request.rb
 - lib/erp_integration/resource.rb
+- lib/erp_integration/resources/errors.rb
 - lib/erp_integration/sales_order.rb
 - lib/erp_integration/sales_order_line.rb
 - lib/erp_integration/stock_move.rb