client-api-builder 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee8b61c4583f46d39c0d502192fb713f502ece28b7ea98092b73572efc9ffd4
-  data.tar.gz: bc80ea2afb78cdacc5067ebb45005a4bbcc997d13e79e9c6a9cf6b7edc8d5696
+  metadata.gz: 00351abdc1f660fefd19687f75b696db8a1b9b16390ff6427706a8f5db64ee74
+  data.tar.gz: 34dac63d4090971accab88566f4c217ccdb5a1d21ba000281ad5e2ea68bd74cb
 SHA512:
-  metadata.gz: 4fd43d2172214d83d6b235096bd17f6289a07243dae96f3911b66c783d11caf1695ee541c2a0d2b547acf305616819c749bb32168ca62b5fa98880b042050925
-  data.tar.gz: e2d29d72f3c076be3b24d0941f317745ce367342cc96157f7c8d2a8592bc2dea0a733da1f4d9d5d40f46e1bf2859a01023ebb57c9ca31be4efca07e18267751e
+  metadata.gz: b34e2623702b08c9ac8156e8f0fe9da060636823492ec49bc34832e4e5bff09bb8ab4b3244cbba38bc49ec1a01a80ae30a484c8ec85fb8ae7a032131156278f5
+  data.tar.gz: 4e164e2afd778cd2a6c2adb171c0ee6afec71eef925de9b61fe9b8c1b1d94a5faf2bd8fa624f6f691c4b7268d550e2e58dc82ef0c9b40470fe687026a5cef90f

data/CHANGELOG.md

@@ -1,10 +1,32 @@
 # Changelog
 
+## [0.7.1](https://github.com/dougyouch/client-api-builder/compare/v0.7.0...v0.7.1) (2026-10-03)
+
+
+### Bug Fixes
+
+* **router:** detect destroy_ routes as DELETE ([85604c4](https://github.com/dougyouch/client-api-builder/commit/85604c4d974c8483e292e700eb51a2c78e312b54))
+* **router:** url-encode path values ([76d6fb4](https://github.com/dougyouch/client-api-builder/commit/76d6fb4fa246b342e263322d06262cba6760c278))
+
+### Upgrade Notes
+
+* Path values are now percent-encoded by `escape_path`, including `/`. A value like `'a/b'` that previously expanded into two path segments is now sent as one segment (`a%2Fb`). To keep `/` as a separator, override `escape_path` in your client, e.g. `value.to_s.split('/').map { |part| ERB::Util.url_encode(part) }.join('/')`.
+
 ## [0.7.0](https://github.com/dougyouch/client-api-builder/compare/v0.6.1...v0.7.0) (2026-10-03)
 
 
-### Build System
+### ⚠ BREAKING CHANGES
+
+* client-api-builder now requires Ruby 3.2 or newer (previously 3.0). Ruby 3.0 and 3.1 are end-of-life. ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
+
+### Packaging
+
+* ship only `lib/`, `README.md`, `LICENSE` and `CHANGELOG.md` in the gem instead of every tracked file ([ca141a1](https://github.com/dougyouch/client-api-builder/commit/ca141a1))
+* refresh the gem summary and description ([ca141a1](https://github.com/dougyouch/client-api-builder/commit/ca141a1))
+* add `ClientApiBuilder::VERSION` ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
 
-* **release:** release 0.7.0 ([fff1354](https://github.com/dougyouch/client-api-builder/commit/fff13543d5d8189e2bb7a84eda7e8ca3181f3469))
+### Build
 
-## Changelog
+* automate versioning, changelog and RubyGems publishing with release-please ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
+* replace Codecov with a GitHub-hosted coverage badge ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
+* adopt the dynamic-active-model RuboCop config with rubocop-rspec ([f36ed6f](https://github.com/dougyouch/client-api-builder/commit/f36ed6f))

data/README.md

@@ -1,8 +1,9 @@
 # Client API Builder
 
-[![Gem Version](https://badge.fury.io/rb/client-api-builder.svg)](https://badge.fury.io/rb/client-api-builder)
+[![Gem Version](https://img.shields.io/gem/v/client-api-builder)](https://rubygems.org/gems/client-api-builder)
 [![CI](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml)
 [![Coverage](https://raw.githubusercontent.com/dougyouch/client-api-builder/badges/coverage.svg)](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml)
+[![Branch Coverage](https://raw.githubusercontent.com/dougyouch/client-api-builder/badges/branches.svg)](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml)
 
 A Ruby gem for building robust, secure API clients through declarative configuration. Define your API endpoints and their behavior with minimal boilerplate while benefiting from built-in security features, automatic retries, and comprehensive error handling.
 
@@ -93,25 +94,54 @@ route :method_name, '/path/:param', options
 
 | Option | Description |
 |--------|-------------|
-| `method:` | HTTP method (`:get`, `:post`, `:put`, `:patch`, `:delete`). Auto-detected if omitted. |
+| `method:` | HTTP method. Auto-detected from the route name if omitted. Any of `:get`, `:post`, `:put`, `:patch`, `:delete`, `:head`, `:options`, `:trace`, `:copy`, `:lock`, `:unlock`, `:mkcol`, `:move`, `:propfind`, `:proppatch`. |
 | `query:` | Hash defining query parameters. Use symbols for dynamic values. |
-| `body:` | Hash defining request body. Use symbols for dynamic values. |
-| `expected_response_code:` | Single expected HTTP status code |
+| `body:` | Request body: a Hash or Array (symbols become arguments) or a literal String. |
+| `no_body:` | `true` to send no body, even for POST/PUT/PATCH. |
+| `has_body:` | `true` to add a `body:` argument to any method, e.g. a GET with a body. |
+| `expected_response_code:` | Single expected HTTP status code. Without one, any 2xx response is accepted. |
 | `expected_response_codes:` | Array of expected HTTP status codes |
 | `stream:` | Enable streaming (`:file`, `:io`, `:block`, or `true`) |
 | `return:` | Return type (`:response`, `:body`, or parsed JSON by default) |
 
+POST, PUT and PATCH routes without a `body:` option take the request body as a `body:` argument:
+
+```ruby
+route :create_user, '/users'
+
+client.create_user(body: { name: 'Ann' })
+```
+
+### Per-Request Options
+
+Every generated method also accepts options that apply to that call only:
+
+```ruby
+client.get_user(
+  id: 1,
+  headers: { 'X-Trace-Id' => 'abc' },   # merged over the class headers
+  query: { expand: 'teams' },           # merged over the route's query params
+  body: { name: 'Ann' },                # replaces the route's body
+  connection_options: { read_timeout: 5 },
+  retries: 3,                           # attempts for this call
+  sleep: 0.5,                           # seconds between attempts
+  return: :body                         # :body or :response instead of parsed JSON
+)
+```
+
 ### Automatic HTTP Method Detection
 
-The Router automatically detects HTTP methods based on route names:
+The Router detects the HTTP method from how the route name starts:
 
-| Prefix | HTTP Method |
-|--------|-------------|
-| `get_`, `find_`, `fetch_`, `list_`, `search_` | GET |
-| `post_`, `create_`, `add_`, `insert_` | POST |
-| `put_`, `update_`, `modify_`, `change_` | PUT |
-| `patch_` | PATCH |
-| `delete_`, `remove_`, `destroy_` | DELETE |
+| Name starts with | HTTP Method |
+|------------------|-------------|
+| `post`, `create`, `add`, `insert` | POST |
+| `put`, `update`, `modify`, `change` | PUT |
+| `patch` | PATCH |
+| `delete`, `remove`, `destroy` | DELETE |
+| anything else | GET |
+
+The match is on the start of the name only, so `address_lookup` is a POST. Pass `method:` when the name doesn't say it.
 
 ```ruby
 class MyApiClient
@@ -132,11 +162,31 @@ end
 
 Parameters can be defined in three ways:
 
-**1. Path Parameters** (using `:param` or `{param}` syntax):
+**1. Path Parameters** (using `:param` syntax):
 
 ```ruby
 route :get_user, '/users/:id'
-route :get_post, '/users/{user_id}/posts/{post_id}'
+# client.get_user(id: 1)
+```
+
+`{name}` is filled from the client's own `name` method rather than an argument, which suits values like account IDs that are set once:
+
+```ruby
+attr_accessor :account_id
+
+route :get_invoices, '/accounts/{account_id}/invoices'
+# client.get_invoices
+```
+
+The same `'{name}'` form works as a value inside `query:` and `body:`.
+
+Path values, from arguments and `{name}` alike, are percent-encoded so each stays a single segment: `get_file(name: 'a/b c')` requests `/files/a%2Fb%20c`. Only RFC 3986 unreserved characters (`A-Z a-z 0-9 - . _ ~`) are left as is. To change this, override `escape_path`:
+
+```ruby
+# Allow '/' in values, e.g. for nested object keys
+def escape_path(value)
+  value.to_s.split('/').map { |part| ERB::Util.url_encode(part) }.join('/')
+end
 ```
 
 **2. Query Parameters:**
@@ -193,7 +243,7 @@ class MyApiClient
   # Default: JSON (using to_json)
   body_builder :to_json
 
-  # URL-encoded form data (using to_query)
+  # URL-encoded form data (using to_query, requires ActiveSupport)
   body_builder :to_query
 
   # Custom query params builder (no ActiveSupport dependency)
@@ -213,6 +263,8 @@ class MyApiClient
 end
 ```
 
+String bodies are sent as is. Query strings are built the same way with `query_builder`, which accepts `:to_query`, `:query_params`, a method name or a block. It defaults to `:to_query` when ActiveSupport is loaded and to `:query_params` otherwise.
+
 ### Nested Routing (Sections)
 
 Organize complex APIs with nested routes:
@@ -222,12 +274,17 @@ class MyApiClient
   include ClientApiBuilder::Router
 
   base_url 'https://api.example.com'
-  header 'Authorization', :auth_token
+  header 'Authorization', :authorization
 
   attr_accessor :auth_token
 
+  def authorization
+    "Bearer #{auth_token}"
+  end
+
   section :users do
     base_url 'https://api.example.com/v2'  # Override base URL
+    header 'Authorization', :authorization
 
     route :list, '/users'
     route :get, '/users/:id'
@@ -235,6 +292,8 @@ class MyApiClient
   end
 
   section :posts do
+    header 'Authorization', :authorization
+
     route :list, '/posts'
     route :get, '/posts/:id'
   end
@@ -249,6 +308,8 @@ 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, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
+
 ### Connection Options
 
 Configure connection settings:
@@ -268,6 +329,8 @@ class MyApiClient
 end
 ```
 
+Any `Net::HTTP.start` option can be set this way. Your options are applied over the secure HTTPS defaults, so setting `verify_mode` yourself replaces `VERIFY_PEER`.
+
 ### Retry Configuration
 
 Configure automatic retries for transient failures:
@@ -278,12 +341,14 @@ class MyApiClient
 
   base_url 'https://api.example.com'
 
-  # Retry up to 3 times with 0.5 second delay between attempts
+  # Make up to 3 attempts in total, waiting 0.5 seconds between them
   configure_retries 3, 0.5
 end
 ```
 
-By default, retries are performed only for network-related errors:
+The first argument is the total number of attempts, not extra retries. The default is 1, so requests are not retried unless you configure it. `retries:` and `sleep:` can also be passed per request.
+
+Only these network errors are retried by default:
 - `Net::OpenTimeout`, `Net::ReadTimeout`
 - `Errno::ECONNRESET`, `Errno::ECONNREFUSED`, `Errno::ETIMEDOUT`
 - `SocketError`, `EOFError`
@@ -345,6 +410,8 @@ client.process_stream do |response, chunk|
 end
 ```
 
+Streaming routes return the `Net::HTTPResponse`. Files are written in `wb` mode by default; pass `connection_options: { file_mode: 'ab' }` to append.
+
 ### Response Handling
 
 Customize how responses are processed:
@@ -370,11 +437,16 @@ class MyApiClient
     data
   end
 end
+
+# A block passed to the call replaces the route's block
+client.get_user(id: 1) { |data| data['name'] }
 ```
 
+Blocks run on the client, so they can call its methods and set its state. Empty response bodies return `nil`.
+
 ### Error Handling
 
-The gem provides detailed error information:
+`ClientApiBuilder::UnexpectedResponse` is raised when the status code isn't expected (any non-2xx by default, or anything outside `expected_response_code(s)`) and when a response body isn't valid JSON. It carries the response:
 
 ```ruby
 begin
@@ -412,12 +484,9 @@ puts client.request_attempts     # Number of attempts (including retries)
 
 ### ActiveSupport Integration
 
-When ActiveSupport is available, the gem provides instrumentation and logging:
+When ActiveSupport is loaded before your client class includes `ClientApiBuilder::Router`, every request is instrumented as a `client_api_builder.request` event:
 
 ```ruby
-# Set up logging
-ClientApiBuilder.logger = Logger.new(STDOUT)
-
 # Subscribe to request events
 ActiveSupport::Notifications.subscribe('client_api_builder.request') do |*args|
   event = ActiveSupport::Notifications::Event.new(*args)
@@ -433,9 +502,15 @@ subscriber = ClientApiBuilder::ActiveSupportLogSubscriber.new(Rails.logger)
 subscriber.subscribe!
 ```
 
+Separately, `ClientApiBuilder.logger` receives every exception raised during a request attempt, including ones that are retried:
+
+```ruby
+ClientApiBuilder.logger = Logger.new($stdout)
+```
+
 #### Production Logging
 
-For production environments, it's important to log requests without exposing sensitive credentials that may be present in query parameters. The following example strips query parameters from logged URLs:
+The built-in log subscriber already leaves out query strings, which may hold credentials. To customize the format, subscribe directly:
 
 ```ruby
 ActiveSupport::Notifications.subscribe('client_api_builder.request') do |_, start_time, end_time, _, payload|
@@ -461,7 +536,7 @@ Client API Builder includes several security features enabled by default:
 
 ### SSL/TLS Verification
 
-All HTTPS connections verify SSL certificates by default using `OpenSSL::SSL::VERIFY_PEER`. Default timeouts are also configured to prevent hanging connections.
+HTTPS connections verify SSL certificates using `OpenSSL::SSL::VERIFY_PEER` and default to a 30 second open timeout and 60 second read timeout. Plain HTTP connections use Net::HTTP's own defaults.
 
 ### SSRF Protection
 
@@ -478,9 +553,13 @@ class MyApiClient
 end
 ```
 
+### Path Value Encoding
+
+Values inserted into a route's path are percent-encoded, so input such as `../admin` or `a/b?x=1` can't add path segments or a query string to the request.
+
 ### Path Traversal Protection
 
-File streaming operations validate paths to prevent directory traversal attacks:
+File streaming rejects any path containing `..` or a null byte:
 
 ```ruby
 # These will raise ArgumentError
@@ -522,12 +601,12 @@ end
 | Method | Description |
 |--------|-------------|
 | `base_url(url)` | Set the base URL for all requests |
-| `header(name, value)` | Add a header to all requests |
+| `header(name, value = nil, &block)` | Add a header to all requests (value, method name symbol, or block) |
 | `body_builder(builder)` | Configure request body serialization |
 | `query_builder(builder)` | Configure query string serialization |
-| `query_param(name, value)` | Add a query parameter to all requests |
+| `query_param(name, value = nil, &block)` | Add a query parameter to all requests (value, method name symbol, or block) |
 | `connection_option(name, value)` | Set Net::HTTP connection options |
-| `configure_retries(max, sleep)` | Configure retry behavior |
+| `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 |
 | `namespace(path, &block)` | Add path prefix to routes in block |
@@ -541,11 +620,27 @@ end
 | `total_request_time` | Duration of last request in seconds |
 | `request_attempts` | Number of attempts for last request |
 | `root_router` | Returns the root router (for nested routers) |
+| `base_url` | Base URL used for requests |
+
+### Overridable Hooks
+
+Define these in your client to change default behavior:
+
+| Method | Default |
+|--------|---------|
+| `retry_request?(exception, options)` | `true` for the network errors listed under Retry Configuration |
+| `escape_path(value)` | Percent-encodes path values (`ERB::Util.url_encode`) |
+| `parse_response(response, options)` | Parses the body as JSON, `nil` when empty |
+| `handle_response(response, options, &block)` | Applies `return:`, parsing and the response block |
+| `expected_response_code!(response, codes, options)` | Raises `UnexpectedResponse` for unexpected codes |
+| `get_retry_request_max_retries(options)` | `retries:` option, then `configure_retries`, then 1 |
+| `get_retry_request_sleep_time(exception, options)` | `sleep:` option, then `configure_retries`, then 0.05 |
 
 ## Requirements
 
 - Ruby 3.2+
 - `inheritance-helper` gem (>= 0.2.5)
+- `activesupport` (optional) for `to_query` builders and instrumentation
 
 ## Contributing
 
@@ -554,7 +649,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/dougyo
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/my-feature`)
 3. Write tests for your changes
-4. Ensure all tests pass (`bundle exec rspec`)
+4. Ensure all tests pass with full line and branch coverage (`CI=true bundle exec rspec`)
 5. Ensure code style compliance (`bundle exec rubocop`)
 6. Commit your changes using [conventional commits](https://www.conventionalcommits.org/) (`git commit -am 'feat(router): add my feature'`); release notes and version bumps are generated from them
 7. Push to the branch (`git push origin feature/my-feature`)

data/lib/client_api_builder/nested_router.rb

@@ -17,7 +17,7 @@ module ClientApiBuilder
     end
 
     def self.get_instance_method(var)
-      "\#{root_router.#{var}}"
+      "\#{escape_path(root_router.#{var})}"
     end
 
     def base_url

data/lib/client_api_builder/router.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'erb'
 require 'inheritance-helper'
 require 'json'
 
@@ -177,7 +178,7 @@ module ClientApiBuilder
           :put
         when /^(?:patch)/i
           :patch
-        when /^(?:delete|remove)/i
+        when /^(?:delete|remove|destroy)/i
           :delete
         else
           :get
@@ -552,8 +553,11 @@ module ClientApiBuilder
       self
     end
 
+    # Percent-encodes everything but RFC 3986 unreserved characters (A-Z a-z 0-9 - . _ ~),
+    # so a value inserted into the path, including any '/', stays one segment.
+    # Override to change how path values are encoded.
     def escape_path(path)
-      path
+      ERB::Util.url_encode(path.to_s)
     end
 
     def instrument_request

data/lib/client_api_builder/version.rb

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

metadata

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