fulfil-io 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7be62208f07b3dabac64da70cd97d7ef5d5e513a363d830206ffc6ad25ebffc5
-  data.tar.gz: ddba02ac333a132dcce3886f51b35865d58f4a999adba7f1f10a9ee3cec5e344
+  metadata.gz: 1100e113c9323c0fa742ece65d8a41923c060c382b1b97ad6c50ad20c550b5a9
+  data.tar.gz: 80535f7bea24218d958812bbd8e4ab789ce966c346e5dfa891369160fc04e536
 SHA512:
-  metadata.gz: 02e3e8e5ae922598b1971b96ba26ba2a17c6f05cc4c2ea319bc0e3d69b75fdfc9115ee860b43d4c2965e292f80470ea17d9c07819d0d30aef03610fa1611ae85
-  data.tar.gz: 000740a6f8cff338590329900671bf297acfd41c83f38c5197bac711706ac934b37e39e55ec5683575b6e9ffbfead3f73b6d766afb4b0d8a5e357aa6db9c6c4b
+  metadata.gz: b1ea6e403ab80bb108a90dff5f7ad58c39c228ed610ce497c631b5ae45a3ef5d2912100acd95ee33d7f2aa7c5609b71300c7a2322e1b2efcec688646573bf8da
+  data.tar.gz: d63d23350f0775bac73f28fdbabd0645798ed28a0466e7851ade38328a9f17e7a75982bc6bada6c1d951e4eb3ed0a4ffd872c79a6dc3c848f4308ddcfd11db16

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 0.4.9
+
+* Add client tests and stub with Webmock.
+
+## 0.4.8
+
+* Feature: Allow more params with InteractiveReport.
+
+## 0.4.7
+
+* Bugfix: Accidentally removed the model parameter from the URL.
+
+## 0.4.6
+
+* Add InteractiveReport support.
+
+## 0.4.5
+
+* Add #delete to client.
+* Set up Dependabot on GitHub.
+
 ## 0.4.4
 
 * Pin http dependency to ~> 4.4.0. 5.0+ introduces a frozen string error.

data/README.md

@@ -109,6 +109,19 @@ sale['channel'] = 4
 
 fulfil.put(model: sale_model, body: sale)
 ```
+### Interactive Reports
+
+As of v0.4.6, interactive report support exists in a basic form.
+You're able to execute reports with basic params. Responses are
+transformed to JSON structures.
+
+```ruby
+fulfil = Fulfil::Client.new
+
+report = Fulfil::Report.new(client: fulfil, report_name: 'account.tax.summary.ireport')
+
+report.execute(start_date: Date.new(2020, 12, 1), end_date: Date.new(2020, 12, 31))
+```
 
 ## Development
 
@@ -116,10 +129,48 @@ 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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Release a new version
+
+We're following semver for the release process of this gem. Make sure to apply the correct semver version for a new release.
+
+To release a new version, run the `bin/release x.x.x`. That's it.
+
+> **NOTE:** You don't have to add a v to the version you want to release. The release script will handle that for you.
+
+### Testing
+
+For non-client tests, create the test class or case.
+
+For client tests, you'll need to add a couple steps. If running against a real
+backend, you'll need to provide a couple of environment variables:
+`FULFIL_SUBDOMAIN` and `FULFIL_TOKEN`. Additionally, pass `debug: true` to the
+client instance in the test. This will output the response body. Webmock will
+probably complain that real requests aren't allowed at this point, offering you
+the stub. We don't need most of that.
+
+We will need to capture the response body as JSON and store it in the
+`test/fixtures` directory. Formatted for readability, please. You'll also need
+to make note of the path and body of the request. Once you have that, you can
+generate your stub.
+
+To stub a request, use (or create) the helper method based on the verb. For
+example, to stub a `GET` request, use `stub_fulfil_get`. Here's an example:
+
+```ruby
+def test_find_one
+  stub_fulfil_get('sale.sale/213112', 'sale_sale')
+
+  client = Fulfil::Client.new
+  response = client.find_one(model: 'sale.sale', id: 213_112)
+
+  assert_equal 213_112, response['id']
+end
+```
+
+`stub_fulfil_get` takes two arguments: the URL path (after `/api/v2/model/`)
+and the fixture file name to be returned.
 
 ## Contributing
 

data/lib/fulfil/client.rb

@@ -10,9 +10,18 @@ module Fulfil
   OAUTH_TOKEN = ENV['FULFIL_TOKEN']
 
   class Client
+    class InvalidClientError < StandardError
+      def message
+        'Client is not configured correctly.'
+      end
+    end
+
     class NotAuthorizedError < StandardError; end
+
     class UnknownHTTPError < StandardError; end
+
     class ConnectionError < StandardError; end
+
     class ResponseError < StandardError; end
 
     def initialize(subdomain: SUBDOMAIN, token: OAUTH_TOKEN, headers: { 'X-API-KEY' => API_KEY }, debug: false)
@@ -21,6 +30,16 @@ module Fulfil
       @debug = debug
       @headers = headers
       @headers.delete('X-API-KEY') if @token
+
+      raise InvalidClientError if invalid?
+    end
+
+    def invalid?
+      @subdomain.nil? || @subdomain.empty?
+    end
+
+    def valid?
+      !invalid?
     end
 
     def find(model:, ids: [], id: nil, fields: %w[id rec_name])
@@ -71,13 +90,26 @@ module Fulfil
       parse(results: results)
     end
 
-    def put(model:, id:, endpoint: nil, body: {})
+    def put(model: nil, id: nil, endpoint: nil, body: {})
       uri = URI(model_url(model: model, id: id, endpoint: endpoint))
 
       result = request(verb: :put, endpoint: uri, json: body)
       parse(result: result)
     end
 
+    def delete(model:, id:)
+      uri = URI(model_url(model: model, id: id))
+
+      result = request(verb: :delete, endpoint: uri)
+      parse(result: result)
+    end
+
+    def interactive_report(endpoint:, body: nil)
+      uri = URI("#{base_url}/model/#{endpoint}")
+      result = request(verb: :put, endpoint: uri, json: body)
+      parse(result: result)
+    end
+
     private
 
     def parse(result: nil, results: [])
@@ -96,34 +128,33 @@ module Fulfil
       results.map { |result| Fulfil::ResponseParser.parse(item: result) }
     end
 
+    def domain
+      "https://#{@subdomain}.fulfil.io"
+    end
+
     def base_url
-      "https://#{@subdomain}.fulfil.io/api/v2/model"
+      [domain, 'api', 'v2'].join('/')
     end
 
     def model_url(model:, id: nil, endpoint: nil)
-      [base_url, model, id, endpoint].compact.join('/')
+      [base_url, 'model', model, id, endpoint].compact.join('/')
     end
 
-    def request(verb: :get, endpoint:, **args)
+    def request(endpoint:, verb: :get, **args)
+      raise InvalidClientError if invalid?
+
       response = client.request(verb, endpoint, args)
+      Fulfil::ResponseHandler.new(response).verify!
 
-      if response.status.ok? || response.status.created?
-        response.parse
-      elsif response.code == 401
-        error = response.parse
-        raise NotAuthorizedError, "Not authorized: #{error['error']}: #{error['error_description']}"
-      else
-        puts response.body.to_s
-        raise Error, 'Error encountered while processing response:'
-      end
+      response.parse
     rescue HTTP::Error => e
       puts e
       raise UnknownHTTPError, 'Unhandled HTTP error encountered'
     rescue HTTP::ConnectionError => e
       puts "Couldn't connect"
       raise ConnectionError, "Can't connect to #{base_url}"
-    rescue HTTP::ResponseError => ex
-      raise ResponseError, "Can't process response: #{ex}"
+    rescue HTTP::ResponseError => e
+      raise ResponseError, "Can't process response: #{e}"
       []
     end
 

data/lib/fulfil/error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Fulfil
+  class Error < StandardError; end
+
+  # The `Fulfil::HttpError` is raised whenever an API request returns a 400+ HTTP status code.
+  # See `Fulfil::ResponseHandler` for more information.
+  class HttpError < Error
+    attr_reader :metadata
+
+    def initialize(message, metadata = {})
+      @metadata = metadata
+      super(message)
+    end
+
+    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/fulfil/interactive_report.rb

@@ -0,0 +1,40 @@
+module Fulfil
+  class InteractiveReport
+    def initialize(client:, report:)
+      @client = client
+      @report = report
+    end
+
+    def execute(**params)
+      body = {}
+
+      params.each do |key, value|
+        body[key] = if value.is_a?(Date)
+                      serialize_date(value)
+                    else
+                      value
+                    end
+      end
+
+      @client.interactive_report(
+        endpoint: report_url,
+        body: [body]
+      )
+    end
+
+    private
+
+    def report_url
+      "#{@report}/execute"
+    end
+
+    def serialize_date(date)
+      {
+        __class__: 'date',
+        year: date.year,
+        month: date.month,
+        day: date.day
+      }
+    end
+  end
+end

data/lib/fulfil/response_handler.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Fulfil
+  # The `Fulfil::ResponseHandler` is parses the HTTP response from Fulfil. If it
+  # encounters an HTTP status code that indicates an error, it will raise an internal
+  # exception that the consumer can catch.
+  #
+  # @example
+  #   Fulfil::ResponseHandler.new(@response).verify!
+  #   => true
+  #
+  #   Fulfil::ResponseHandler.new(@response).verify!
+  #   => Fulfil::Error::BadRequest
+  class ResponseHandler
+    HTTP_ERROR_CODES = {
+      400 => Fulfil::HttpError::BadRequest,
+      401 => Fulfil::HttpError::AuthorizationRequired,
+      402 => Fulfil::HttpError::PaymentRequired,
+      403 => Fulfil::HttpError::Forbidden,
+      404 => Fulfil::HttpError::NotFound,
+      405 => Fulfil::HttpError::MethodNotAllowed,
+      406 => Fulfil::HttpError::NotAccepted,
+      422 => Fulfil::HttpError::UnprocessableEntity,
+      429 => Fulfil::HttpError::TooManyRequests,
+      500 => Fulfil::HttpError::InternalServerError
+    }.freeze
+
+    def initialize(response)
+      @response = response
+      @status_code = response.code
+    end
+
+    def verify!
+      return true unless @status_code >= 400
+
+      raise HTTP_ERROR_CODES.fetch(@status_code, Fulfil::HttpError).new(
+        response_body['error_description'],
+        {
+          body: @response.body,
+          headers: @response.headers,
+          status: @response.status
+        }
+      )
+    end
+
+    private
+
+    def response_body
+      @response_body ||= @response.parse
+    end
+  end
+end

data/lib/fulfil/response_parser.rb

@@ -41,7 +41,7 @@ module Fulfil
     def self.group(key_value_tuples)
       key_value_tuples
         .group_by { |kv_tuple| kv_tuple[0][0] }
-        .map { |group_key, kv_tuples|
+        .map do |group_key, kv_tuples|
         if kv_tuples.length == 1
           [group_key, mapped_value_field(value: kv_tuples[0][1])]
         else
@@ -49,7 +49,7 @@ module Fulfil
           attrs = kv_tuples[1..-1].map { |tuple| [tuple[0][1..-1], tuple[1]] }
           [group_key, [['id', id[1]]].concat(group(attrs)).to_h]
         end
-      }
+      end
     end
 
     def self.parse(item:)
@@ -57,5 +57,4 @@ module Fulfil
       group(key_value_tuples).to_h
     end
   end
-
 end

data/lib/fulfil/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fulfil
-  VERSION = '0.4.4'
+  VERSION = "0.5.0"
 end

data/lib/fulfil.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 require 'fulfil/version'
+require 'fulfil/error'
 require 'fulfil/client'
 require 'fulfil/model'
+require 'fulfil/interactive_report'
+require 'fulfil/response_handler'
 require 'fulfil/response_parser'
 
 module Fulfil
-  class Error < StandardError; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fulfil-io
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Chris Moore
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-20 00:00:00.000000000 Z
+date: 2021-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -95,6 +95,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - chris@knowndecimal.com
@@ -111,8 +125,11 @@ files:
 - Rakefile
 - lib/fulfil.rb
 - lib/fulfil/client.rb
+- lib/fulfil/error.rb
+- lib/fulfil/interactive_report.rb
 - lib/fulfil/model.rb
 - lib/fulfil/query.rb
+- lib/fulfil/response_handler.rb
 - lib/fulfil/response_parser.rb
 - lib/fulfil/version.rb
 homepage: https://github.com/knowndecimal/fulfil
@@ -134,7 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Interact with the Fulfil.io API