client-api-builder 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aac435317feb174db101e201b00464222bfc2df0f10601ac88e7897c3694be27
-  data.tar.gz: '08ad14efc0bff6c1f6e7fd4864e26c6f41853d72808fdc84b0e4781a0cfd229f'
+  metadata.gz: 3e2d55d531b568e6f1cb0bb718ee236ca44eac7951c133ca6f2d294460968a80
+  data.tar.gz: d617dc3983f1cde402095e2be735c804f9a657969007a1f601779fe90f01c110
 SHA512:
-  metadata.gz: e28726cc8c9670553371ba62a3c2ea4d30a4edb5db413936b91810ab1b592b2b84e6dd0fd3bcac8ad47fa2fb2c1b5d57a6c0443cace95210b9cf203a5e783d43
-  data.tar.gz: ed7628816de37ff4e8f4a27f67520f277abac439cb6183eca0c98ce5a072a1bd8c0413a3db5bda145d75208b4272c598b89514ad80f6692a6cb300c255330b64
+  metadata.gz: 288273782ec2072f360e56b3653a80510684fd05772560db6544b438cc558c56a58d8de179cf87636a80dc396789aed431c63aee4681e90ad9bbc11325b294ba
+  data.tar.gz: 5a8622d04ae326e393c1b104a79ff8ed30f1f22420b6b3a7f4b1f30aa39b4e29e7929b625d8ff665276dd6ad45e2ee96e327afceb082b9a6c1d7eb227dde2229

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.0](https://github.com/dougyouch/client-api-builder/compare/v0.7.2...v0.8.0) (2026-10-03)
+
+
+### Features
+
+* **section:** let sections inherit root client headers, query params and connection options ([8849d98](https://github.com/dougyouch/client-api-builder/commit/8849d9875c86633639bf33c5e9b1eb486f67e921))
+
 ## [0.7.2](https://github.com/dougyouch/client-api-builder/compare/v0.7.1...v0.7.2) (2026-10-03)
 
 

data/README.md

@@ -296,9 +296,9 @@ class MyApiClient
     "Bearer #{auth_token}"
   end
 
-  section :users do
+  # Use the root client's headers (Authorization) beneath the section's own
+  section :users, inherit: :headers do
     base_url 'https://api.example.com/v2'  # Override base URL
-    header 'Authorization', :authorization
 
     route :list, '/users'
     route :get, '/users/:id'
@@ -306,7 +306,7 @@ class MyApiClient
   end
 
   section :posts do
-    header 'Authorization', :authorization
+    header 'Authorization', :authorization  # or declare what it needs itself
 
     route :list, '/posts'
     route :get, '/posts/:id'
@@ -322,7 +322,17 @@ user = client.users.get(id: 123)
 posts = client.posts.list
 ```
 
-A section is its own router class. It uses the parent's `base_url` unless it sets one, but headers, query params, connection options, retries and builders are not inherited, so declare the ones it needs inside the section. Symbol and block values given to `header` and `query_param`, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
+A section is its own router class. It uses the parent's `base_url` unless it sets one, but by default nothing else is inherited: declare the headers, query params and connection options it needs inside the section, or opt into the root client's with `inherit:`:
+
+```ruby
+section :users, inherit: %i[headers query_params connection_options] do
+  # or, inside the block: inherit_from_root :headers
+end
+```
+
+Inherited settings are the root client's class-level ones, read on every request (so ones declared after the section, or in a subclass of the client, apply too). The section's own settings override them, and per-request options override both; a per-request `nil` header still drops an inherited one. Retries and body/query builders are always the section's own. Any other options passed to `section` are available to it as `nested_router_options`.
+
+Symbol and block values given to `header` and `query_param`, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
 
 ### Connection Options
 
@@ -643,7 +653,7 @@ end
 | `connection_option(name, value)` | Set Net::HTTP connection options |
 | `configure_retries(max_attempts, sleep = 0.05)` | Configure retry behavior |
 | `route(name, path, options)` | Define an API endpoint |
-| `section(name, options, &block)` | Define nested routes |
+| `section(name, options, &block)` | Define nested routes; `inherit:` opts into the root client's `:headers`, `:query_params` and/or `:connection_options` |
 | `namespace(path, &block)` | Add path prefix to routes in block |
 
 ### Instance Methods

data/lib/client_api_builder/nested_router.rb

@@ -8,6 +8,9 @@ module ClientApiBuilder
   class NestedRouter
     include ::ClientApiBuilder::Router
 
+    # Root client settings a section can opt into with inherit: or inherit_from_root
+    INHERITABLE_SETTINGS = %i[headers query_params connection_options].freeze
+
     attr_reader :root_router,
                 :nested_router_options
 
@@ -20,6 +23,39 @@ module ClientApiBuilder
       "\#{escape_path(root_router.#{var})}"
     end
 
+    # The root client settings this section uses beneath its own; none by default
+    def self.inherited_root_settings
+      [].freeze
+    end
+
+    # Opts this section into the root client's class-level headers, query params and/or
+    # connection options. They are read per request and the section's own values take precedence.
+    def self.inherit_from_root(*settings)
+      settings = normalize_inherited_settings(settings)
+      redefine_class_method(:inherited_root_settings, (inherited_root_settings | settings).freeze)
+    end
+
+    def self.normalize_inherited_settings(settings)
+      settings = settings.flatten.map(&:to_sym)
+      unknown = settings - INHERITABLE_SETTINGS
+      return settings if unknown.empty?
+
+      raise ArgumentError, "Unknown inherit setting(s): #{unknown.map(&:inspect).join(', ')}. " \
+                           "Allowed: #{INHERITABLE_SETTINGS.map(&:inspect).join(', ')}"
+    end
+
+    def configured_headers
+      inherits_from_root?(:headers) ? root_router.configured_headers.merge(super) : super
+    end
+
+    def configured_query_params
+      inherits_from_root?(:query_params) ? root_router.configured_query_params.merge(super) : super
+    end
+
+    def configured_connection_options
+      inherits_from_root?(:connection_options) ? root_router.configured_connection_options.merge(super) : super
+    end
+
     def base_url
       self.class.base_url || root_router.base_url
     end
@@ -27,5 +63,11 @@ module ClientApiBuilder
     def handle_response(response, options, &)
       root_router.handle_response(response, options, &)
     end
+
+    private
+
+    def inherits_from_root?(setting)
+      self.class.inherited_root_settings.include?(setting)
+    end
   end
 end

data/lib/client_api_builder/router.rb

@@ -484,29 +484,41 @@ module ClientApiBuilder
     # Class-level headers may be method names or blocks; per-request headers are used as given.
     # Values are converted to strings, as Net::HTTP requires; nil values are left out of the request.
     def build_headers(options)
-      headers = self.class.default_headers.transform_values { |value| resolve_config_value(value) }
+      headers = configured_headers
       headers.merge!(options[:headers]) if options[:headers]
       headers.transform_values { |value| value&.to_s }
     end
 
+    # Class-level headers with symbols and blocks resolved; sections may add the root client's
+    def configured_headers
+      self.class.default_headers.transform_values { |value| resolve_config_value(value) }
+    end
+
     def build_connection_options(options)
-      if options[:connection_options]
-        self.class.default_connection_options.merge(options[:connection_options])
-      else
-        self.class.default_connection_options
-      end
+      connection_options = configured_connection_options
+      options[:connection_options] ? connection_options.merge(options[:connection_options]) : connection_options
+    end
+
+    # Class-level connection options; sections may add the root client's
+    def configured_connection_options
+      self.class.default_connection_options
     end
 
     # Class-level query params may be method names or blocks; values from route arguments
     # and per-request options are sent as given.
     def build_query(query, options)
-      query_params = self.class.default_query_params.transform_values { |value| resolve_config_value(value) }
+      query_params = configured_query_params
       query_params.merge!(query) if query
       query_params.merge!(options[:query]) if options[:query]
 
       query_params.empty? ? nil : self.class.build_query(self, query_params)
     end
 
+    # Class-level query params with symbols and blocks resolved; sections may add the root client's
+    def configured_query_params
+      self.class.default_query_params.transform_values { |value| resolve_config_value(value) }
+    end
+
     # Resolves a class-level header or query_param value: a Symbol calls that method and a
     # Proc is evaluated, both on the root router; anything else is used as is.
     def resolve_config_value(value)

data/lib/client_api_builder/section.rb

@@ -12,17 +12,23 @@ module ClientApiBuilder
 
       # Defines <name>_router (the section's NestedRouter class) and <name> (its router for a
       # client instance) with closures, so anonymous client classes and any option values work.
-      def section(name, nested_router_options = {}, &)
+      # inherit: opts the section into root client settings (see NestedRouter.inherit_from_root);
+      # the remaining options are passed to the section as nested_router_options.
+      def section(name, nested_router_options = {}, &block)
         raise ArgumentError, "Invalid section name: #{name.inspect}" unless name.to_s.match?(SECTION_NAME)
 
+        nested_router_options = nested_router_options.dup
+        inherit = ::ClientApiBuilder::NestedRouter.normalize_inherited_settings(Array(nested_router_options.delete(:inherit)))
+
         kls = InheritanceHelper::ClassBuilder::Utils.create_class(
           self,
           name,
           ::ClientApiBuilder::NestedRouter,
           nil,
-          'NestedRouter',
-          &
+          'NestedRouter'
         )
+        kls.inherit_from_root(inherit)
+        kls.class_eval(&block) if block
 
         define_singleton_method(:"#{name}_router") { kls }
         define_section_accessor(name, nested_router_options)

data/lib/client_api_builder/version.rb

@@ -2,5 +2,5 @@
 
 module ClientApiBuilder
   # Gem version, bumped by release-please
-  VERSION = '0.7.2'
+  VERSION = '0.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Doug Youch