client-api-builder 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ba2a10bca8dbdf440a037007da9858446a7c1b165575d49510e7ed37d9d53d6
-  data.tar.gz: aeb66f9fbfeeefb4d946975641dba14002706ac07117dcaca5d41d89dbf10a7d
+  metadata.gz: 212fbedc035c5b2b1b406bd024a10b1739839d540a4be74ef2b67d57ed3a29d8
+  data.tar.gz: 18160a35e27ff5432a35a266b7062adda945de69f7c5e7eb6494a25cfbb66c5d
 SHA512:
-  metadata.gz: a346879ca1a8dac4f6c849c68fb3c2553bdb298e490a0c5da6f38768d0a18f858d08c21ddbf119bff2975f5023d38592711292240437c721e111caa7023ec5bb
-  data.tar.gz: 4f0faf034b9749c59cdb2c1d79adf7109e1bcd8ed1b85a1ffa189622a793d34d0f26df0c4e3a5f674700831c28f1ded0f40c8f9765657cc457e9da10b4f374e1
+  metadata.gz: fec92f548db39eec3123b5ea613f6d390af534def8c60fb1522323dd2d2c578cb6a657b896896aad05d36f7bcb9e93dcf60fc282f1c8cefa3c477113d675d106
+  data.tar.gz: ec306c4f5d78b85da0bbf5ea97c19a1e012053af75447d40600e2c358635a681579dbb933b44c40d46e4a0159a1ffe72f427270fa2833eeb34f9ad16db93575f

data/.cursor.json

@@ -0,0 +1,29 @@
+{
+  "rules": [
+    {
+      "name": "Ruby spec file",
+      "pattern": "^lib/(.+)\\.rb$",
+      "target": "spec/${1}_spec.rb"
+    },
+    {
+      "name": "Ruby implementation file",
+      "pattern": "^spec/(.+)_spec\\.rb$", 
+      "target": "lib/${1}.rb"
+    },
+    {
+      "name": "Related client_api_builder files",
+      "pattern": "^(?:lib|spec)/client_api_builder/(.+)\\.rb$",
+      "related": [
+        "lib/client_api_builder/${1}.rb",
+        "spec/client_api_builder/${1}_spec.rb"
+      ]
+    },
+    {
+      "name": "Main library file",
+      "pattern": "^(?:lib|spec)/client_api_builder/.+\\.rb$",
+      "related": [
+        "lib/client-api-builder.rb"
+      ]
+    }
+  ]
+} 

data/.ruby-version

@@ -1 +1 @@
-3.1.0
+3.4.2

data/ARCHITECTURE.md

@@ -0,0 +1,148 @@
+# Client API Builder Architecture
+
+This document describes the internal architecture and design of the Client API Builder gem.
+
+## Overview
+
+Client API Builder is a Ruby gem that provides a declarative way to create API clients. It uses a modular architecture with several key components working together to provide a flexible and extensible API client framework.
+
+## Core Components
+
+### 1. Router Module (`ClientApiBuilder::Router`)
+
+The `Router` module is the core component that provides the main functionality for defining and executing API requests. It includes:
+
+- **Class Methods**: Configuration methods for setting up the API client
+  - `base_url`: Sets the base URL for all requests
+  - `header`: Adds headers to requests
+  - `route`: Defines API endpoints
+  - `body_builder`: Configures how request bodies are formatted
+  - `query_builder`: Configures how query parameters are formatted
+  - `configure_retries`: Sets retry behavior for failed requests
+
+- **Instance Methods**: Methods for executing requests and handling responses
+  - `build_headers`: Constructs request headers
+  - `build_connection_options`: Sets up connection options
+  - `build_query`: Formats query parameters
+  - `build_body`: Formats request body
+  - `handle_response`: Processes API responses
+  - `request_wrapper`: Manages request execution and retries
+
+### 2. Nested Router (`ClientApiBuilder::NestedRouter`)
+
+The `NestedRouter` class enables hierarchical API client organization by allowing routes to be grouped under namespaces. It:
+
+- Inherits from the base Router functionality
+- Maintains a reference to its root router
+- Allows for nested route definitions
+- Shares configuration with its parent router
+
+### 3. Section Module (`ClientApiBuilder::Section`)
+
+The `Section` module provides the mechanism for creating nested routers. It:
+
+- Defines the `section` class method for creating nested route groups
+- Dynamically generates methods for accessing nested routers
+- Handles the creation of nested router classes
+
+### 4. Request Handling
+
+The request handling system is built on top of Ruby's `Net::HTTP` and includes:
+
+- **Request Building**: Constructs HTTP requests with proper headers, body, and query parameters
+- **Response Processing**: Handles different response formats and status codes
+- **Error Handling**: Provides custom error classes for API-specific errors
+- **Retry Mechanism**: Implements configurable retry logic for failed requests
+
+### 5. ActiveSupport Integration
+
+The gem integrates with ActiveSupport for:
+
+- **Logging**: Provides request/response logging
+- **Notifications**: Implements instrumentation for request timing and monitoring
+- **Query Parameter Building**: Uses ActiveSupport's parameter formatting when available
+
+## Design Patterns
+
+### 1. Module Inclusion Pattern
+
+The gem uses Ruby's module inclusion pattern extensively:
+
+```ruby
+module ClientApiBuilder
+  module Router
+    def self.included(base)
+      base.extend ClassMethods
+      base.include InstanceMethods
+    end
+  end
+end
+```
+
+This pattern allows for clean separation of class and instance methods while maintaining a single namespace.
+
+### 2. Builder Pattern
+
+The request building process follows the builder pattern:
+
+```ruby
+def build_headers(options)
+  headers = {}
+  # ... build headers
+  headers
+end
+```
+
+Each component (headers, body, query) is built separately and then combined into the final request.
+
+### 3. Decorator Pattern
+
+The nested router implementation uses a decorator-like pattern:
+
+```ruby
+class NestedRouter
+  include ::ClientApiBuilder::Router
+  attr_reader :root_router
+  # ... adds additional functionality while delegating to root_router
+end
+```
+
+## Configuration Management
+
+The gem uses a hierarchical configuration system:
+
+1. **Default Options**: Defined in `Router.default_options`
+2. **Class-level Configuration**: Set through class methods
+3. **Instance-level Configuration**: Can override class-level settings
+4. **Request-level Configuration**: Specific to individual requests
+
+## Error Handling
+
+The error handling system includes:
+
+- `ClientApiBuilder::Error`: Base error class
+- `ClientApiBuilder::UnexpectedResponse`: For handling unexpected API responses
+- Custom error handling through response procs
+
+## Extensibility
+
+The architecture is designed to be extensible through:
+
+1. **Custom Body Builders**: Implement custom body formatting
+2. **Custom Query Builders**: Implement custom query parameter formatting
+3. **Response Processors**: Add custom response handling
+4. **Nested Routers**: Create custom nested router implementations
+
+## Dependencies
+
+- `inheritance-helper`: For class inheritance and method management
+- `json`: For JSON parsing and serialization
+- `net/http`: For HTTP request handling
+- `active_support` (optional): For additional functionality when available
+
+## Performance Considerations
+
+1. **Request Caching**: No built-in request caching
+2. **Connection Pooling**: Uses standard Net::HTTP connection handling
+3. **Memory Usage**: Minimal object creation during request processing
+4. **Thread Safety**: No explicit thread safety mechanisms 

data/Gemfile

@@ -7,9 +7,6 @@ gem 'inheritance-helper'
 group :development do
   gem 'rake'
   gem 'rubocop'
-end
-
-group :spec do
   gem 'activesupport'
   gem 'rspec'
   gem 'simplecov'

data/Gemfile.lock

@@ -1,67 +1,93 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (7.0.2.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+    activesupport (7.2.2.1)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
       minitest (>= 5.1)
-      tzinfo (~> 2.0)
-    addressable (2.8.0)
-      public_suffix (>= 2.0.2, < 5.0)
-    ast (2.4.2)
-    concurrent-ruby (1.1.9)
-    crack (0.4.5)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.3)
+    crack (1.0.0)
+      bigdecimal
       rexml
-    diff-lcs (1.5.0)
-    docile (1.4.0)
-    hashdiff (1.0.1)
-    i18n (1.10.0)
+    diff-lcs (1.6.1)
+    docile (1.4.1)
+    drb (2.2.1)
+    hashdiff (1.1.2)
+    i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     inheritance-helper (0.2.5)
-    minitest (5.15.0)
-    parallel (1.21.0)
-    parser (3.1.1.0)
+    json (2.11.3)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    parallel (1.27.0)
+    parser (3.3.8.0)
       ast (~> 2.4.1)
-    public_suffix (4.0.6)
+      racc
+    prism (1.4.0)
+    public_suffix (6.0.2)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.2.1)
-    rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rake (13.2.1)
+    regexp_parser (2.10.0)
+    rexml (3.4.1)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.4)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rubocop (1.26.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.3)
+    rubocop (1.75.4)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.16.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.16.0)
-      parser (>= 3.1.1.0)
-    ruby-progressbar (1.11.0)
-    simplecov (0.21.2)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.12.3)
+    simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
-    tzinfo (2.0.4)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.1.0)
-    webmock (3.14.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    webmock (3.25.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -1,33 +1,208 @@
-# client-api-builder
+# Client API Builder
 
-Utility for creating API clients through configuration
+A Ruby gem that provides a simple and elegant way to create API clients through configuration. It allows you to define API endpoints and their behavior declaratively, making it easy to create and maintain API clients.
 
-Example:
+## Features
+
+- Declarative API client configuration
+- Support for different request body formats (JSON, query params)
+- Customizable headers
+- Nested routing support
+- ActiveSupport integration for logging and notifications
+- Error handling with detailed response information
+- Flexible parameter handling
+- Automatic HTTP method detection based on method names
+- Streaming support for handling large payloads
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'client-api-builder'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install client-api-builder
+```
+
+## Usage
+
+### Basic Usage
+
+Create an API client by including the `ClientApiBuilder::Router` module and defining your endpoints:
+
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+
+  # Set the base URL for all requests
+  base_url 'https://api.example.com'
+
+  # Set default headers
+  header 'Content-Type', 'application/json'
+  header 'Accept', 'application/json'
 
+  # Define an endpoint
+  route :get_user, '/users/:id', method: :get, expected_response_code: 200
+  route :create_user, '/users', method: :post, expected_response_code: 201, body: { name: :name, email: :email }
+end
+
+# Use the client
+client = MyApiClient.new
+user = client.get_user(id: 123)
+new_user = client.create_user(name: 'John', email: 'john@example.com')
 ```
-class LoremIpsumClient
+
+### Automatic HTTP Method Detection
+
+The Router automatically detects the HTTP method based on the method name if not explicitly specified. This makes your API client code more intuitive and reduces boilerplate. The detection rules are:
+
+- Methods starting with `post`, `create`, `add`, or `insert` → `POST`
+- Methods starting with `put`, `update`, `modify`, or `change` → `PUT`
+- Methods starting with `patch` → `PATCH`
+- Methods starting with `delete` or `remove` → `DELETE`
+- All other methods → `GET`
+
+Example:
+
+```ruby
+class MyApiClient
   include ClientApiBuilder::Router
+  
+  base_url 'https://api.example.com'
+  
+  # These will automatically use the appropriate HTTP methods
+  route :get_users, '/users'  # Uses GET
+  route :create_user, '/users', body: { name: :name }  # Uses POST
+  route :update_user, '/users/:id', body: { name: :name }  # Uses PUT
+  route :delete_user, '/users/:id'  # Uses DELETE
+  
+  # You can still explicitly specify the method if needed
+  route :custom_action, '/custom', method: :post
+end
+```
+
+### Request Body Formats
+
+By default, the client converts the body data to JSON. To use query parameters instead:
 
-  # by default it converts the body data to JSON
-  # to convert the body to query params (x=1&y=2) use the following
-  # if using active support change this to :to_query
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+  
+  # Use query parameters for the body
   body_builder :query_params
+  
+  base_url 'https://api.example.com'
+  
+  route :search, '/search', body: { q: :query, page: :page }
+end
+```
 
-  base_url 'https://www.lipsum.com'
+### Nested Routing
 
-  header 'Content-Type', 'application/x-www-form-urlencoded'
-  header 'Accept', 'application/json'
+For APIs with nested resources, you can use the `NestedRouter`:
 
-  # this creates a method called create_lorem_ipsum with 2 named arguments amont and what
-  route :create_lorem_ipsum, '/feed/json', body: {amount: :amount, what: :what, start: 'yes', generate: 'Generate Lorem Ipsum'}
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+  
+  base_url 'https://api.example.com'
+  
+  section :users do
+    route :list, '/', method: :get
+    route :get, '/:id', method: :get
+  end
 end
+
+client = MyApiClient.new
+users = client.users.list
+user = client.users.get(id: 123)
 ```
 
-How to use:
+### Error Handling
 
+The gem provides custom error classes for better error handling:
+
+```ruby
+begin
+  client.get_user(id: 123)
+rescue ClientApiBuilder::UnexpectedResponse => e
+  puts "Request failed with status #{e.response.status}"
+  puts "Response body: #{e.response.body}"
+end
 ```
-client = LoremIpsumClient.new
-payload = client.create_lorem_ipsum(amount: 10, what: 'words')
-puts payload.dig('feed', 'lipsum')
-# outputs: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at.
+
+### ActiveSupport Integration
+
+The gem integrates with ActiveSupport for logging and notifications:
+
+```ruby
+# Enable logging
+ClientApiBuilder.logger = Logger.new(STDOUT)
+
+# Subscribe to notifications
+ActiveSupport::Notifications.subscribe('request.client_api_builder') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  puts "Request took #{event.duration}ms"
+end
 ```
+
+### Streaming Support
+
+The library supports streaming responses, which is particularly useful for handling large payloads. You can stream responses directly to a file or process them in chunks:
+
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+  
+  base_url 'https://api.example.com'
+  
+  # Stream response directly to a file
+  route :download_users, '/users', stream: :file
+  
+  # Stream response in chunks for custom processing
+  route :stream_users, '/users', stream: true
+end
+
+# Use the client
+client = MyApiClient.new
+
+# Stream to file
+client.download_users('users.json')  # Saves response directly to users.json
+
+# Stream with custom processing
+client.stream_users do |chunk|
+  # Process each chunk of the response
+  puts "Received #{chunk.bytesize} bytes"
+end
+```
+
+When using `stream: :file`, the response is written directly to disk as it's received, which is memory-efficient for large responses. The file path is passed as an argument to the method.
+
+For custom streaming, you can provide a block that will be called with each chunk of the response as it's received. This allows for custom processing of large responses without loading the entire response into memory.
+
+## Configuration Options
+
+- `base_url`: Set the base URL for all requests
+- `header`: Add headers to all requests
+- `body_builder`: Configure how request bodies are formatted
+- `route`: Define API endpoints with their paths and parameters
+- `nested_route`: Define nested resource routes
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dougyouch/client-api-builder.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/client-api-builder.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name        = 'client-api-builder'
-  s.version     = '0.5.5'
+  s.version     = '0.5.6'
   s.licenses    = ['MIT']
   s.summary     = 'Utility for creating API clients through configuration'
   s.description = 'Create API clients through configuration with complete transparency'

data/lib/client_api_builder/router.rb

@@ -147,6 +147,8 @@ module ClientApiBuilder
           :post
         when /^(?:put|update|modify|change)/i
           :put
+        when /^(?:patch)/i
+          :patch
         when /^(?:delete|remove)/i
           :delete
         else

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors:
 - Doug Youch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-20 00:00:00.000000000 Z
+date: 2025-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inheritance-helper
@@ -30,9 +30,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".cursor.json"
 - ".gitignore"
 - ".ruby-gemset"
 - ".ruby-version"
+- ARCHITECTURE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE