fulfil-io 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e82498f50af6f27434982cbeb6bb3faec54a085e999f4d86293d4378afb801a
-  data.tar.gz: d2596d9afedaf2f67aa3f573c139d1c5a03b706e638fdf2407fc482f25336d6f
+  metadata.gz: df8251caaf1131da686f385b8ccfa716259b5af29859f84d1236d469cc88b5b9
+  data.tar.gz: 695fb3d9c099d2c43d44e23cfc41cd21405be94bef8d1181383526f487ed7660
 SHA512:
-  metadata.gz: 67ad033ab2a666abc04747a37e1d4859690158cfdf1c6455cdc3e3383ccfd6aa74b556def1b02e7584945120b426357ed4a85fa1f1feaa74ad118fbe6161280c
-  data.tar.gz: 1ade1a109a650b56c76fcaea49ed71d92b87d8f87e6659748ea5c739d6e6f1715ec6099835f2faefd7c515e8482054d580c17b0fcb74342c2cc214d40fabaeee
+  metadata.gz: 69dc9272022c7d312b3bfcc701cc8fa9814bb1d1a64da76c0e5e938676810a46df5f50ed25f573e05260a221faf968cabe6bbe095eee50463f2cd9c9a263bdb0
+  data.tar.gz: e5f4b528beea3306899269b647fc34c6981a7950fc664d536eca4458963eb92c01039e101a48ac692ac45e574a27a79bf9ea417103d5c31abbaabc82dac7bd0b

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+## 0.9.0
+
+* Drop legacy Ruby support and require Ruby 3.2+.
+* Update CI matrix to supported Rubies (3.2, 3.3, 3.4).
+* Migrate coverage uploads from Code Climate to Qlty.
+* Update runtime and development dependencies.
+* Auth cleanup: support explicit `api_key` while keeping backwards compatibility for `headers: { 'X-API-KEY' => ... }`.
+* Fix auth selection to ignore blank tokens and correctly fall back to API key authentication.
+* Improve HTTP error handling and rescue ordering so specific connection/response errors are raised correctly.
+
+## 0.8.1
+
+* Add logger to configuration by @cdmwebs in https://github.com/knowndecimal/fulfil/pull/49
+
+## 0.8.0
+
+* Add rubocop by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/35
+* Remove _now from testing example by @swanny85 in https://github.com/knowndecimal/fulfil/pull/32
+* Add SimpleCov for test coverage by @cdmwebs in https://github.com/knowndecimal/fulfil/pull/38
+* Add support for Fulfil sale duplication by @swanny85 in https://github.com/knowndecimal/fulfil/pull/48
+
+## 0.6.1
+
+* Fixes a typo in the examples of the readme by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/25
+* Fix requiring gemfiles manually by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/27
+
+## 0.6.0
+
+* Streamline the usage of environment variables. by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/18
+* Update http requirement from ~> 4.4.1 to >= 4.4.1, < 5.1.0 by @dependabot in https://github.com/knowndecimal/fulfil/pull/12
+* Remove extremely precise User-Agent from mocks. by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/20
+* Use GitHub Actions instead of Travis CI and Circle CI by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/21
+* Remove persistent connection and client caching by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/22
+* Add rate limit detection by @stefanvermaas in https://github.com/knowndecimal/fulfil/pull/24
+
+## 0.5.0
+
+* Better response parsing and error handling.
+* Documentation updates.
+* Add release script.
+
 ## 0.4.9
 
 * Add client tests and stub with Webmock.

data/README.md

@@ -32,7 +32,8 @@ Environment variables:
 
 - **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
+- **FULFIL_API_KEY:** required for authentication via the `X-API-KEY` request
+  header. This is used with the Personal Access Token authentication method.
 
 > **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
@@ -72,6 +73,24 @@ pp sales
 #   "rec_name"=>""}]
 ```
 
+To configure a client without using environment variables, pass them as arguments:
+
+```ruby
+client = Fulfil::Client.new(
+  subdomain: 'test',
+  api_key: '123'
+)
+```
+
+With an OAuth token:
+
+```ruby
+client = Fulfil::Client.new(
+  subdomain: 'test',
+  token: '123'
+)
+```
+
 ### Count
 
 ```ruby

data/lib/fulfil/client.rb

@@ -11,7 +11,7 @@ module Fulfil
   class Client
     class InvalidClientError < StandardError
       def message
-        'Client is not configured correctly.'
+        super || 'Client is not configured correctly.'
       end
     end
 
@@ -23,12 +23,19 @@ 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, api_key: API_KEY, headers: nil, debug: false)
       @subdomain = subdomain
-      @token = token
       @debug = debug
-      @headers = headers
-      @headers.delete('X-API-KEY') if @token
+
+      normalized_api_key = api_key || headers&.[]('X-API-KEY') || headers&.[]('X-Api-Key')
+
+      if !token.to_s.empty?
+        @token = token
+      elsif !normalized_api_key.to_s.empty?
+        @api_key = normalized_api_key
+      else
+        raise InvalidClientError, 'No token or API key provided.'
+      end
 
       raise InvalidClientError if invalid?
     end
@@ -150,21 +157,16 @@ module Fulfil
     end
 
     def request(endpoint:, verb: :get, **args)
-      raise InvalidClientError if invalid?
-
       response = client.request(verb, endpoint, args)
       Fulfil::ResponseHandler.new(response).verify!
 
       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 => e
       raise ResponseError, "Can't process response: #{e}"
-      []
+    rescue HTTP::Error => e
+      raise UnknownHTTPError, 'Unhandled HTTP error encountered'
     # If configured, the client will wait whenever the `RateLimitExceeded` exception
     # is raised. Check `Fulfil::Configuration` for more details.
     rescue RateLimitExceeded => e
@@ -175,9 +177,10 @@ module Fulfil
     end
 
     def client
-      client = HTTP.use(logging: @debug ? { logger: Logger.new($stdout) } : {})
+      client = HTTP.use(logging: @debug ? { logger: config.logger } : {})
       client = client.auth("Bearer #{@token}") if @token
-      client.headers(@headers)
+      client = client.headers({ 'X-API-KEY': @api_key }) if @api_key
+      client
     end
 
     def config

data/lib/fulfil/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'logger'
+
 module Fulfil
   # The `Fulfil::Configuration` contains the available configuration options
   # for the `Fulfil` gem.
@@ -22,9 +24,21 @@ module Fulfil
     # @return [Proc, nil]
     attr_accessor :rate_limit_notification_handler
 
+    # Allows the client to configure a logger. Logs are output to $stderr by default.
+    #
+    # @example Use a logger to log the API rate limit hits
+    #  Fulfil.configure do |config|
+    #    config.logger = Logger.new($stderr)
+    #  end
+    #
+    # @return [Logger, nil]
+    #
+    attr_accessor :logger
+
     def initialize
       @retry_on_rate_limit = false
       @retry_on_rate_limit_wait = 1
+      @logger = Logger.new($stderr)
     end
 
     def retry_on_rate_limit?

data/lib/fulfil/response_handler.rb

@@ -1,16 +1,9 @@
 # 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
+  # The `Fulfil::ResponseHandler` parses the HTTP response from Fulfil. If it
+  # encounters an HTTP status code that indicates an error, it raises 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,
@@ -44,18 +37,61 @@ module Fulfil
     def verify_http_status_code!
       return true unless @status_code >= 400
 
+      payload = response_body
       raise HTTP_ERROR_CODES.fetch(@status_code, Fulfil::HttpError).new(
-        response_body['error_description'],
-        {
-          body: @response.body,
-          headers: @response.headers,
-          status: @response.status
-        }
+        response_error_message(payload),
+        response_error_metadata(payload)
       )
     end
 
+    def response_error_message(payload)
+      body = payload.is_a?(Hash) ? payload : {}
+
+      code = body['code']
+      type = body['type']
+      message = first_present(
+        body['error_description'],
+        body.dig('error', 'message'),
+        body['message'],
+        body['description'],
+        body['detail'],
+        body.dig('errors', 0, 'message')
+      )
+
+      return "Fulfil request failed (HTTP #{@status_code})" if message.nil?
+
+      message_parts = []
+      message_parts << "[#{code}]" if present?(code)
+      message_parts << "#{type}:" if present?(type)
+      message_parts << message
+      message_parts.join(' ')
+    end
+
+    def response_error_metadata(payload)
+      body = payload.is_a?(Hash) ? payload : {}
+
+      {
+        body: @response.body,
+        parsed_body: payload,
+        headers: @response.headers,
+        status: @response.status,
+        code: body['code'],
+        type: body['type'],
+        message: body['message'],
+        description: body['description']
+      }
+    end
+
     def response_body
       @response_body ||= @response.parse
     end
+
+    def present?(value)
+      !(value.nil? || value.to_s.strip.empty?)
+    end
+
+    def first_present(*values)
+      values.find { |value| present?(value) }
+    end
   end
 end

data/lib/fulfil/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fulfil
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fulfil-io
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Chris Moore
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-20 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -21,7 +21,7 @@ dependencies:
         version: 4.4.1
     - - "<"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -31,7 +31,7 @@ dependencies:
         version: 4.4.1
     - - "<"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: '6.0'
 description:
 email:
 - chris@knowndecimal.com
@@ -72,14 +72,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.12
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Interact with the Fulfil.io API