erp_integration 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 346594300ff75a2d7f21a9e226287fe43b8b4765105d80d73840e4ff8fd9c355
-  data.tar.gz: 67b680a54fec9cb91866b6d9658dc7eeb4a63168f76826a7bba421148c0a77a5
+  metadata.gz: 0b7edee1b77a371325210af94802cbd0d6c1df5d730bcfd8d9d326bc8a5eb2c3
+  data.tar.gz: d59ecb758fde883746da4fec059e99c53b71f7a526f81d7fa272eb139f567ff4
 SHA512:
-  metadata.gz: 5e36d2c2d1b0c5f231cef0477a5154fe4a101f262d9171f20cbb3fc051df8feff4655dcd9f5265634f241056a35a8562ca2caa580488b49d6c4c865fa4456aa1
-  data.tar.gz: b6dcd7aa6843c5e8686a2489ea88ba80c3a2ba543b941d00f652ef0621b0a6feaebc93c4ae9dcbab78f199e139fa7900060b46c7b812a96cffa0022821f3f36f
+  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/fulfil/api_resource.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'finder_methods'
+require_relative 'persistence'
 require_relative 'query_methods'
 
 module ErpIntegration
@@ -8,6 +9,7 @@ module ErpIntegration
     class ApiResource
       include Enumerable
       include FinderMethods
+      include Persistence
       include QueryMethods
 
       attr_accessor :resource_klass

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/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.6.0'
+  VERSION = '0.7.0'
 end

data/lib/erp_integration.rb

@@ -33,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.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Stefan Vermaas
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-13 00:00:00.000000000 Z
+date: 2022-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -224,7 +224,7 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 1.19.2
-description:
+description: 
 email:
 - stefan@knowndecimal.com
 executables: []
@@ -267,6 +267,7 @@ files:
 - 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
@@ -289,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
@@ -302,7 +304,7 @@ metadata:
   homepage_uri: https://www.github.com/mejuri-inc/erp-integration
   source_code_uri: https://www.github.com/mejuri-inc/erp-integration
   changelog_uri: https://www.github.com/mejuri-inc/erp-integration/blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -318,7 +320,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.22
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Connects Mejuri with third-party ERP vendors
 test_files: []