fulfil-io 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c465ec839e9c594b602b0e70f3058214630c38e6b8544ed456a16e5c518aeac
-  data.tar.gz: 22d0df9435f0f5432bf16193b40f25cd6f681c796c163f5aac6c6439e940c8c5
+  metadata.gz: df8251caaf1131da686f385b8ccfa716259b5af29859f84d1236d469cc88b5b9
+  data.tar.gz: 695fb3d9c099d2c43d44e23cfc41cd21405be94bef8d1181383526f487ed7660
 SHA512:
-  metadata.gz: dfa7f4dde51c08ff6f4b33520817db32a374b99dc41543926256277cb70ead338cd24987c1cefde9100a53492c848e6c87ce7e19308be7d2e5188b9b26060f9e
-  data.tar.gz: 4462c5a7b4526802270e1eb80941077faa956b6822e5fe034b84cbdb72021f50d610e461b22419ea4b8d3aa9d1c90be529ab3ad36fbb9b91308de084b4853414
+  metadata.gz: 69dc9272022c7d312b3bfcc701cc8fa9814bb1d1a64da76c0e5e938676810a46df5f50ed25f573e05260a221faf968cabe6bbe095eee50463f2cd9c9a263bdb0
+  data.tar.gz: e5f4b528beea3306899269b647fc34c6981a7950fc664d536eca4458963eb92c01039e101a48ac692ac45e574a27a79bf9ea417103d5c31abbaabc82dac7bd0b

data/CHANGELOG.md

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

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
@@ -177,7 +179,8 @@ module Fulfil
     def client
       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/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.1'
+  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.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Chris Moore
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-10 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.7
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Interact with the Fulfil.io API