fulfil-io 0.4.7 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21d5119cc38db9e9a414775dcfc9b37d53ca5fa3ff05218c4ae81bbc912d0695
-  data.tar.gz: a4bf8e9ae17a2993c1a3644d298e39f71c78b1eddc40f6bb20d35bdb25ad1ba5
+  metadata.gz: 0c58e4104ae9106550bca7c000cbf3f576f551c9e4512cee93dc74dd0aa5604f
+  data.tar.gz: ee0644f88360b5356efa034833772a54d207ce4be7e81040219e8d66019ff301
 SHA512:
-  metadata.gz: b1fc2fe57cb22c234b12ffe3c0182030baa3be525971eaa7a2f21470e36f5ef9f6957919ba3675574c1159c79ff3b40f28b11167927ce8f852e70fed667f01b3
-  data.tar.gz: 1406056b1b4f566163829b91dd96822c1705286528581567f74d1c383146652a10e0788fd1b80bab81fa79088a32a65440c72483f70fc8c22ae073e9115f19fa
+  metadata.gz: d697a2153dcbcd379621b59bc7ef8af428c4f6ecc2445d454afc38eddb34247430279136f758fe52e538abcda923c386dbc4d7f2af00c27e9e41c26f71a4c5e2
+  data.tar.gz: e6e891f839dd472f24f1dc89ce1189cb80b9218ac09c35c4141c0dd0b575097ecb0d238d47de8e688bc69c3298da0f4e1b2478ebfed1010d139c3fb4087f0ccf

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.

data/README.md

@@ -1,36 +1,40 @@
-# Fulfil.io Rubygem
+[![Tests](https://github.com/knowndecimal/fulfil/actions/workflows/tests.yml/badge.svg)](https://github.com/knowndecimal/fulfil/actions/workflows/tests.yml)
 
-[![CircleCI](https://circleci.com/gh/knowndecimal/fulfil.svg?style=svg&circle-token=da80ea6500af15b3a795a3913efe35742bab94c1)](https://circleci.com/gh/knowndecimal/fulfil)
+# Fulfil.io Rubygem
 
-[Fulfil.io](https://fulfil.io)
+A Ruby library for the [Fulfil.io](https://fulfil.io) API.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'fulfil-io', require: 'fulfil'
+  gem 'fulfil-io', require: 'fulfil'
 ```
 
 And then execute:
 
-    $ bundle install
+```shell
+  $ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install fulfil-io
+```shell
+  $ gem install fulfil-io
+```
 
 ## Usage
 
 Environment variables:
 
-- FULFIL_SUBDOMAIN - required to be set.
-- FULFIL_TOKEN - required for oauth bearer authentication
-- FULFIL_API_KEY - required for authentication via the X-API-KEY request header
+- **FULFIL_SUBDOMAIN:** - always required to use the gem.
+- **FULFIL_OAUTH_TOKEN:** required for oauth bearer authentication
+- **FULFIL_API_KEY:** required for authentication via the `X-API-KEY` request header
 
-**Note:** When FULFIL_TOKEN is present, the FULFIL_API_KEY will be ignored. So,
+> **Note:** When `FULFIL_OAUTH_TOKEN` is present, the `FULFIL_API_KEY` will be ignored. So,
 if oauth doesn't work, returning an Unauthorized error, to use the
-FULFIL_API_KEY, the FULFIL_TOKEN shouldn't be specified.
+`FULFIL_API_KEY`, the `FULFIL_OAUTH_TOKEN` shouldn't be specified.
 
 ```ruby
 require 'fulfil' # this is necessary only in case of running without bundler
@@ -123,16 +127,74 @@ report = Fulfil::Report.new(client: fulfil, report_name: 'account.tax.summary.ir
 report.execute(start_date: Date.new(2020, 12, 1), end_date: Date.new(2020, 12, 31))
 ```
 
+## Rate limits
+
+Fulfil's API applies rate limits to the API requests that it receives. Every request is subject to throttling under the general limits. In addition, there are resource-based rate limits and throttles.
+
+This gem exposes an API for checking your current rate limits (note: the gem only knows about the rate limit after a request to Fulfil's API has been made).
+
+Whenever you reached the rate limit, the `Fulfil::RateLimitExceeded` exception is being raised. You can use the information on the `Fulfil.rate_limit` to find out what to do next.
+
+```ruby
+$ Fulfil.rate_limit.requests_left?
+=> true
+
+# The maximum number of requests you're permitted to make per second.
+$ Fulfil.rate_limit.limit
+=> 9
+
+# The time at which the current rate limit window resets in UTC epoch seconds.
+$ Fulfil.rate_limit.resets_at
+=> #<DateTime: 2022-01-21T16:36:01-04:00 />
+```
 ## Development
 
 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_OAUTH_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

@@ -7,9 +7,14 @@ require 'fulfil/response_parser'
 module Fulfil
   SUBDOMAIN = ENV['FULFIL_SUBDOMAIN']
   API_KEY = ENV['FULFIL_API_KEY']
-  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
@@ -18,12 +23,22 @@ module Fulfil
 
     class ResponseError < StandardError; end
 
-    def initialize(subdomain: SUBDOMAIN, token: OAUTH_TOKEN, headers: { 'X-API-KEY' => API_KEY }, debug: false)
+    def initialize(subdomain: SUBDOMAIN, token: oauth_token, headers: { 'X-API-KEY' => API_KEY }, debug: false)
       @subdomain = subdomain
       @token = token
       @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])
@@ -96,6 +111,15 @@ module Fulfil
 
     private
 
+    def oauth_token
+      if ENV['FULFIL_TOKEN']
+        puts "You're using an deprecated environment variable. Please update your " \
+              'FULFIL_TOKEN to FULFIL_OAUTH_TOKEN.'
+      end
+
+      ENV['FULFIL_OAUTH_TOKEN'] || ENV['FULFIL_TOKEN']
+    end
+
     def parse(result: nil, results: [])
       if result
         parse_single(result: result)
@@ -125,19 +149,12 @@ module Fulfil
     end
 
     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 == 204
-        []
-      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'
@@ -150,12 +167,10 @@ module Fulfil
     end
 
     def client
-      return @client if defined?(@client)
-
-      @client = HTTP.persistent(base_url).use(logging: @debug ? { logger: Logger.new(STDOUT) } : {})
-      @client = @client.auth("Bearer #{@token}") if @token
-      @client = @client.headers(@headers)
-      @client
+      client = HTTP.use(logging: @debug ? { logger: Logger.new(STDOUT) } : {})
+      client = client.auth("Bearer #{@token}") if @token
+      client = client.headers(@headers)
+      client
     end
   end
 end

data/lib/fulfil/error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Fulfil
+  class Error < StandardError; end
+
+  class RateLimitExceeded < Error; 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

@@ -5,13 +5,20 @@ module Fulfil
       @report = report
     end
 
-    def execute(start_date:, end_date:)
+    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: [{
-          start_date: serialize_date(start_date),
-          end_date: serialize_date(end_date)
-        }]
+        body: [body]
       )
     end
 

data/lib/fulfil/rate_limit.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Fulfil
+  # The `Fulfil::RateLimit` allows clients to keep track of their API usage and
+  # to analyze Fulfil's response HTTP headers.
+  class RateLimit
+    attr_accessor :limit, :requests_left, :resets_at
+
+    # Analyses the rate limit based on the response headers from Fulfil.
+    # @param headers [HTTP::Headers] The HTTP response headers from Fulfil.
+    # @return [Fulfil::RateLimit]
+    def analyse!(headers)
+      rate_limit_headers = RateLimitHeaders.new(headers)
+
+      self.limit = rate_limit_headers.limit
+      self.requests_left = rate_limit_headers.requests_left
+      self.resets_at = rate_limit_headers.resets_at
+
+      raise Fulfil::RateLimitExceeded unless requests_left?
+    end
+
+    # Returns whether there are any requests left in the current rate limit window.
+    # @return [Boolean]
+    def requests_left?
+      requests_left&.positive?
+    end
+  end
+end

data/lib/fulfil/rate_limit_headers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Fulfil
+  # The `Fulfil::RateLimitHeaders` parses Fulfil HTTP rate limit headers and
+  # formats them to a more usable format.
+  class RateLimitHeaders
+    # Test suites might mock (or at least should mock) the requests to Fulfil.
+    # However, most of these test suites will not mock the response headers.
+    # To make sure those test suites don't break, we're setting some defaults for them.
+    DEFAULT_REQUEST_LIMIT = 10
+    DEFAULT_REQUESTS_LEFT = 9
+    DEFAULT_RESETS_AT = nil
+
+    attr_reader :limit, :requests_left, :resets_at
+
+    def initialize(headers = {})
+      self.limit = headers['X-RateLimit-Limit'] || DEFAULT_REQUEST_LIMIT
+      self.requests_left = headers['X-RateLimit-Remaining'] || DEFAULT_REQUESTS_LEFT
+      self.resets_at = headers['X-RateLimit-Reset'] || DEFAULT_RESETS_AT
+    end
+
+    # Sets the maximum number of requests you're permitted to make per second.
+    # @param value [String] The maximum number of requests per second.
+    # @return [Integer] The maximum number of requests per second.
+    def limit=(value)
+      @limit = value.to_i
+    end
+
+    # Sets number of requests remaining in the current rate limit window.
+    # @param value [String] The remaining number of requests for the current time window.
+    # @return [Integer] The remaining number of requests for the current time window.
+    def requests_left=(value)
+      @requests_left = value.to_i
+    end
+
+    # Sets the time at which the current rate limit window resets in UTC epoch seconds.
+    # @param value [Integer|nil] Time as an integer in UTC epoch seconds.
+    # @return [DataTime|nil] The moment the rate limit resets.
+    def resets_at=(value)
+      @resets_at =
+        if value.nil?
+          nil
+        else
+          Time.at(value.to_i).utc.to_datetime
+        end
+    end
+  end
+end

data/lib/fulfil/response_handler.rb

@@ -0,0 +1,61 @@
+# 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!
+      verify_rate_limits!
+      verify_http_status_code!
+    end
+
+    private
+
+    def verify_rate_limits!
+      Fulfil.rate_limit.analyse!(@response.headers)
+    end
+
+    def verify_http_status_code!
+      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
+
+    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.7'
+  VERSION = "0.6.0"
 end

data/lib/fulfil.rb

@@ -1,9 +1,19 @@
+# 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'
 
+# Rate limiting
+require 'fulfil/rate_limit'
+require 'fulfil/rate_limit_headers'
+
 module Fulfil
-  class Error < StandardError; end
+  def self.rate_limit
+    @rate_limit ||= RateLimit.new
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fulfil-io
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.6.0
 platform: ruby
 authors:
 - Chris Moore
@@ -9,22 +9,28 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-30 00:00:00.000000000 Z
+date: 2022-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 4.4.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 5.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 4.4.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 5.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -95,6 +101,40 @@ 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'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.6
 description:
 email:
 - chris@knowndecimal.com
@@ -111,9 +151,13 @@ 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/rate_limit.rb
+- lib/fulfil/rate_limit_headers.rb
+- lib/fulfil/response_handler.rb
 - lib/fulfil/response_parser.rb
 - lib/fulfil/version.rb
 homepage: https://github.com/knowndecimal/fulfil
@@ -128,14 +172,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Interact with the Fulfil.io API