fulfil-io 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1100e113c9323c0fa742ece65d8a41923c060c382b1b97ad6c50ad20c550b5a9
-  data.tar.gz: 80535f7bea24218d958812bbd8e4ab789ce966c346e5dfa891369160fc04e536
+  metadata.gz: 0c58e4104ae9106550bca7c000cbf3f576f551c9e4512cee93dc74dd0aa5604f
+  data.tar.gz: ee0644f88360b5356efa034833772a54d207ce4be7e81040219e8d66019ff301
 SHA512:
-  metadata.gz: b1ea6e403ab80bb108a90dff5f7ad58c39c228ed610ce497c631b5ae45a3ef5d2912100acd95ee33d7f2aa7c5609b71300c7a2322e1b2efcec688646573bf8da
-  data.tar.gz: d63d23350f0775bac73f28fdbabd0645798ed28a0466e7851ade38328a9f17e7a75982bc6bada6c1d951e4eb3ed0a4ffd872c79a6dc3c848f4308ddcfd11db16
+  metadata.gz: d697a2153dcbcd379621b59bc7ef8af428c4f6ecc2445d454afc38eddb34247430279136f758fe52e538abcda923c386dbc4d7f2af00c27e9e41c26f71a4c5e2
+  data.tar.gz: e6e891f839dd472f24f1dc89ce1189cb80b9218ac09c35c4141c0dd0b575097ecb0d238d47de8e688bc69c3298da0f4e1b2478ebfed1010d139c3fb4087f0ccf

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,6 +127,26 @@ 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
@@ -145,7 +169,7 @@ 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
+`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.

data/lib/fulfil/client.rb

@@ -7,7 +7,6 @@ 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
@@ -24,7 +23,7 @@ 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
@@ -112,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)
@@ -159,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

@@ -3,6 +3,8 @@
 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

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

@@ -31,6 +31,17 @@ module Fulfil
     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(
@@ -43,8 +54,6 @@ module Fulfil
       )
     end
 
-    private
-
     def response_body
       @response_body ||= @response.parse
     end

data/lib/fulfil/version.rb

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

data/lib/fulfil.rb

@@ -8,5 +8,12 @@ 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
+  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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chris Moore
@@ -9,22 +9,28 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-26 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
@@ -109,6 +115,26 @@ dependencies:
     - - ">="
       - !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
@@ -129,6 +155,8 @@ files:
 - 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
@@ -144,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