booqable 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce7d8b0be4851e4e78229078331a2f73cbe7cb7702c1555df9dec0903be28d0e
-  data.tar.gz: c79ed318eb3a38534291ef5e4abeb6a5749c7a2684bcd1befbf43d6f7f1d0e8a
+  metadata.gz: ee065493e3d48d59edfb13552c3dd8dbce2d800ecfb9d3c8230f6f3c52345be0
+  data.tar.gz: a9fd9934fd93f8504ca1a58e2cab82e09ab1f4f9f2da9fb4a30033e3f84bfe16
 SHA512:
-  metadata.gz: 9d6dead61b0b4bfd8374c9b51aec7dccc724988b5417f9585018ee549840ee207756642b38aedbfcf4fdb4e313f9764fdc64b1d1d6e7593c057edb20d6095afc
-  data.tar.gz: c5e34b3a736ab3bdca397dfd1245d07b8dd8e246e32d4d0f24e097c41f52d47307c645a547592e60b90dc27f98e2e817193a1059f2696c0a726316c0693c1f88
+  metadata.gz: 4babbce96eead5118e72cf700490aa703fb221730a7bd601f23d229cad34f63c91b59f6a7d955e733b0ce111359eb1c8f4b5e54e3834647952c44baf6e222422
+  data.tar.gz: fe5bd8c6bc0150c6a61f45e72de5edfc35ae33335d7bc2fa514a31650a20e44ccbd4dfa8fe3df5a9d7bf22915148c4e0bc7a259c9620e316220b66f36990db7d

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [2.0.0] - 2026-07-14
+
+- **Breaking:** reading an attribute that is absent from an API payload now
+  raises `Booqable::MissingAttribute` (a `NoMethodError` subclass) instead of
+  silently returning nil.
+- Support Ruby 4.0
+- Require `cgi` and declare it as a runtime dependency. Fixes
+  `undefined method 'parse' for class CGI` when handling `invalid_grant`
+  OAuth errors in apps that don't load the full cgi library themselves
+  (e.g. Rails 8.1+, which only loads `cgi/escape`).
+
+## [1.2.1] - 2026-06-10
+
+- Require `oauth2 >= 2.0.22` to address GHSA-pp92-crg2-gfv9, where a
+  protocol-relative redirect `Location` could override the request authority and
+  leak the bearer `Authorization` header to an attacker-controlled host.
+
+
 ## [1.2.0] - 2026-05-27
 
 - Add optional `around_refresh_token` configuration. When provided, the OAuth

data/README.md

@@ -406,6 +406,33 @@ customer = client.parse_resource(payload)
 
 `deserialize_resource` is available as an alias for `parse_resource`.
 
+## Strict attribute reads
+
+Reading an attribute that is absent from the API payload raises
+`Booqable::MissingAttribute` instead of silently returning nil, so typos and
+renamed API fields fail loudly:
+
+```ruby
+customer.name       # => "John Doe"
+customer.full_name  # raises Booqable::MissingAttribute (key absent from payload)
+```
+
+An attribute that is present in the payload with a null value still returns
+nil — only absent keys raise:
+
+```ruby
+order.customer      # => nil when the payload contains "customer": null
+```
+
+`Booqable::MissingAttribute` subclasses `NoMethodError`, so generic rescues
+keep working. To probe for an attribute that may be absent, use hash-style
+access or `key?`:
+
+```ruby
+order[:customer]      # => nil when the key is absent (lenient probe)
+order.key?(:customer) # => false when the key is absent
+```
+
 ## Advanced usage
 
 ### Custom middleware

data/lib/booqable/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
+
 module Booqable
   # Client for the Booqable API
   #
@@ -40,11 +42,22 @@ module Booqable
       access_token
     ]
 
+    # Accepted aliases for configuration options, mapping the alias to its
+    # canonical {Booqable::Configurable} key.
+    OPTION_ALIASES = {
+      skip_retries: :no_retries
+    }.freeze
+
     # Initialize a new Client
     #
     # @param options [Hash] Configuration options for the client
     # @see Booqable::Configurable For a complete list of supported configuration options
     def initialize(options = {})
+      options = normalize_aliases(options)
+
+      unknown_keys = options.keys.map(&:to_sym) - Booqable::Configurable.keys
+      raise ArgumentError, unknown_options_message(unknown_keys) unless unknown_keys.empty?
+
       # Use options passed in, but fall back to module defaults
       #
       # This may look like a `.keys.each` which should be replaced with `#each_key`, but
@@ -94,5 +107,34 @@ module Booqable
 
       inspected
     end
+
+    private
+
+    # Rewrite any aliased option keys to their canonical configuration key.
+    #
+    # @param options [Hash] options as passed to {#initialize}
+    # @return [Hash] options with aliases replaced by their canonical keys
+    def normalize_aliases(options)
+      options.to_h do |key, value|
+        [ OPTION_ALIASES.fetch(key.to_sym, key), value ]
+      end
+    end
+
+    # Build an error message for unknown configuration options, suggesting
+    # similarly-named valid options via did_you_mean when one is close enough.
+    #
+    # @param unknown_keys [Array<Symbol>] options that aren't valid config keys
+    # @return [String]
+    def unknown_options_message(unknown_keys)
+      dictionary = Booqable::Configurable.keys + OPTION_ALIASES.keys
+      spell_checker = DidYouMean::SpellChecker.new(dictionary: dictionary)
+
+      message = "unknown configuration option(s): #{unknown_keys.join(", ")}"
+
+      suggestions = unknown_keys.flat_map { |key| spell_checker.correct(key) }.uniq
+      message += ". Did you mean: #{suggestions.join(", ")}?" unless suggestions.empty?
+
+      message
+    end
   end
 end

data/lib/booqable/error.rb

@@ -421,6 +421,50 @@ module Booqable
   # and body matches 'read-only'
   class ReadOnlyMode < ServerError; end
 
+  # Raised when reading an attribute that is absent from an API resource
+  #
+  # Sawyer normally answers reads of absent attributes with nil, which turns
+  # typos and renamed API fields (e.g. `time_zone` vs `default_timezone`)
+  # into silent data bugs. Resources created by this gem raise this error
+  # instead — see {Booqable::StrictAttributes}.
+  #
+  # Attributes that are present in the payload with a null value still
+  # return nil; only reads of keys that are absent from the payload raise.
+  #
+  # This inherits from NoMethodError (not Booqable::Error) because an absent
+  # attribute is a programming error in the caller, not an API failure:
+  #
+  # * generic `rescue NoMethodError` / `rescue StandardError` code keeps working
+  # * ActiveSupport's `resource.try(:foo)` stays a safe probe: it returns nil
+  #   without calling, since respond_to? is false for absent attributes
+  #   (the bang variant `try!(:foo)` raises)
+  # * hash-style access stays a lenient, explicit probe: `resource[:foo]`
+  #   returns nil for absent keys because Sawyer rescues NoMethodError there
+  class MissingAttribute < NoMethodError
+    # Initialize a new MissingAttribute error
+    #
+    # @param attribute_name [Symbol] Name of the absent attribute that was read
+    # @param resource [Sawyer::Resource] Resource the attribute was read from
+    def initialize(attribute_name, resource)
+      super(build_message(attribute_name, resource), attribute_name)
+    end
+
+    private
+
+    def build_message(attribute_name, resource)
+      message = +"undefined attribute `#{attribute_name}` for #{resource_description(resource)}. "
+      message << "The attribute is absent from the API payload "
+      message << "(attributes present with a null value return nil). "
+      message << "Available attributes: #{resource.attrs.keys.sort.join(", ")}"
+      message
+    end
+
+    def resource_description(resource)
+      type = resource.attrs[:type]
+      type.is_a?(String) ? "a Booqable #{type} resource" : "a Booqable resource"
+    end
+  end
+
   # Raised when Booqable configuration is invalid
   class ConfigArgumentError < ArgumentError; end
 

data/lib/booqable/http.rb

@@ -243,15 +243,17 @@ module Booqable
 
     # Get or create the Sawyer agent for API requests
     #
-    # Returns a memoized Sawyer::Agent configured with the API endpoint,
-    # serializer, and optional logging. Sawyer handles the low-level HTTP
-    # communication and response parsing.
+    # Returns a memoized Booqable::SawyerAgent configured with the API
+    # endpoint, serializer, and optional logging. Sawyer handles the
+    # low-level HTTP communication and response parsing. Resources created
+    # through this agent raise {Booqable::MissingAttribute} when an absent
+    # attribute is read (see {Booqable::StrictAttributes}).
     #
-    # @return [Sawyer::Agent] HTTP agent instance
+    # @return [Booqable::SawyerAgent] HTTP agent instance
     # @api private
     def agent
-      @agent ||= Sawyer::Agent.new(api_endpoint,
-                                   sawyer_options) do |agent|
+      @agent ||= Booqable::SawyerAgent.new(api_endpoint,
+                                           sawyer_options) do |agent|
          agent.response :logger, logger, bodies: true if logger
       end
     end

data/lib/booqable/resource_parser.rb

@@ -69,11 +69,12 @@ module Booqable
     #
     # The agent URL is a placeholder - we don't make any HTTP requests.
     # We just need the agent to create Sawyer::Resource objects that
-    # provide dot-notation attribute access.
+    # provide dot-notation attribute access. Using Booqable::SawyerAgent
+    # makes attribute reads strict (see {Booqable::StrictAttributes}).
     #
-    # @return [Sawyer::Agent]
+    # @return [Booqable::SawyerAgent]
     def sawyer_agent
-      @sawyer_agent ||= Sawyer::Agent.new("https://example.com") do |http|
+      @sawyer_agent ||= Booqable::SawyerAgent.new("https://example.com") do |http|
         http.headers[:content_type] = "application/json"
       end
     end

data/lib/booqable/strict_attributes.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Booqable
+  # Sawyer::Agent used for every resource this gem creates
+  #
+  # Behaves exactly like Sawyer::Agent. It exists as a marker so that
+  # {Booqable::StrictAttributes} can tell resources created by this gem
+  # apart from resources created by other Sawyer-based gems
+  # loaded in the same process.
+  class SawyerAgent < Sawyer::Agent
+  end
+
+  # Strict attribute reads for resources created by this gem
+  #
+  # Sawyer::Resource#method_missing silently answers reads of absent
+  # attributes with nil. That turns typos and renamed API fields
+  # (e.g. `time_zone` vs `default_timezone`) into silent data bugs.
+  # For resources created by a {Booqable::SawyerAgent}, this module raises
+  # {Booqable::MissingAttribute} instead — both for plain reads
+  # (`resource.foo`) and predicate reads (`resource.foo?`).
+  #
+  # Attributes that ARE present in the payload with a null value still
+  # return nil — only reads of keys that are absent from the payload raise.
+  #
+  # Everything else about Sawyer::Resource is unchanged: attribute writes
+  # (`resource.foo = 1`) still define new attributes, hash-style access
+  # (`resource[:foo]`) stays a lenient probe returning nil for absent keys,
+  # and `to_h`/`to_attrs`, `key?`, `dig`, `fetch`, enumeration, marshaling,
+  # and respond_to? semantics all behave as before. Resources created by
+  # other gems' Sawyer agents are unaffected.
+  module StrictAttributes
+    # Matches plain attribute reads (`foo`) and predicate reads (`foo?`).
+    # Setters (`foo=`) stay permitted since Sawyer allows adding attributes.
+    ATTRIBUTE_READ_PATTERN = /\A([a-z0-9_]+)(\?)?\z/i
+
+    # Raise {Booqable::MissingAttribute} for reads of absent attributes
+    # on strict resources; defer to Sawyer's behavior for everything else.
+    def method_missing(method, *)
+      attr_name = booqable_missing_attribute_read(method)
+      raise Booqable::MissingAttribute.new(attr_name, self) if attr_name
+
+      super
+    end
+
+    private
+
+    # Returns the attribute name when +method+ is a read of an attribute
+    # that is absent from the payload of a strict resource, nil otherwise
+    #
+    # @param method [Symbol] the method name passed to #method_missing
+    # @return [Symbol, nil]
+    def booqable_missing_attribute_read(method)
+      # _agent/_fields are Sawyer::Resource's public attr_readers — the bare `agent`/`fields`
+      # spellings are SPECIAL_METHODS resolved inside method_missing, so calling those from
+      # this hook (which method_missing invokes) would recurse infinitely.
+      return nil unless _agent.is_a?(Booqable::SawyerAgent)
+
+      match = ATTRIBUTE_READ_PATTERN.match(method.to_s)
+      return nil unless match
+
+      attr_name = match[1].to_sym
+      return nil if _fields.include?(attr_name)
+      return nil if match[2].nil? && Sawyer::Resource::SPECIAL_METHODS.include?(match[1])
+
+      attr_name
+    end
+  end
+end
+
+Sawyer::Resource.prepend(Booqable::StrictAttributes)

data/lib/booqable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Booqable
-  VERSION = "1.2.0"
+  VERSION = "2.0.0"
 end

data/lib/booqable.rb

@@ -6,11 +6,13 @@ require "faraday/retry"
 require "json"
 require "sawyer"
 require "sawyer/link_parsers/simple"
+require "cgi"
 
 # Internal
 require_relative "booqable/version"
 require_relative "booqable/rate_limit"
 require_relative "booqable/error"
+require_relative "booqable/strict_attributes"
 require_relative "booqable/oauth_client"
 require_relative "booqable/middleware/base"
 require_relative "booqable/middleware/raise_error"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: booqable
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Hrvoje Šimić
@@ -86,6 +86,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.22
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -93,6 +96,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.22
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +113,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 description: Ruby toolkit for the Booqable API. Provides a simple interface to interact
   with all Booqable API endpoints including orders, customers, products, and more.
 email:
@@ -141,6 +161,7 @@ files:
 - lib/booqable/resource_proxy.rb
 - lib/booqable/resources.json
 - lib/booqable/resources.rb
+- lib/booqable/strict_attributes.rb
 - lib/booqable/version.rb
 - sig/booqable.rbs
 homepage: https://github.com/booqable/booqable.rb
@@ -166,7 +187,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Official Booqable API client for Ruby.
 test_files: []