client-api-builder 0.5.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ba2a10bca8dbdf440a037007da9858446a7c1b165575d49510e7ed37d9d53d6
-  data.tar.gz: aeb66f9fbfeeefb4d946975641dba14002706ac07117dcaca5d41d89dbf10a7d
+  metadata.gz: ae35befd024cba590ae2f644877243c536612ef9ce0e66c6c7c69f2481a7fc20
+  data.tar.gz: cd843e5f96ed9a63f9fb4012ab94b7ebe7b8bd443fa2cec35fe04e1bf50e0806
 SHA512:
-  metadata.gz: a346879ca1a8dac4f6c849c68fb3c2553bdb298e490a0c5da6f38768d0a18f858d08c21ddbf119bff2975f5023d38592711292240437c721e111caa7023ec5bb
-  data.tar.gz: 4f0faf034b9749c59cdb2c1d79adf7109e1bcd8ed1b85a1ffa189622a793d34d0f26df0c4e3a5f674700831c28f1ded0f40c8f9765657cc457e9da10b4f374e1
+  metadata.gz: a97833f34c6dde60bc8edbe9d38180e6f2904884ceb5b85a38e43358856e6e9c95f57e06f4356c0a10fe50d33801513e89132b452482bd689abf610a9ac53894
+  data.tar.gz: 9686a7f14ed8144f3e310cddf9abdf0681bfd237149397adba9d1376ca5d47a106530e099e165d22264bd7178b663e026a9e0658a2e95ef6a9b1fb1c3beb874e

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/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --format github
+
+  test:
+    name: Tests (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.2', '3.3', '3.4']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+      - name: Upload coverage to Codecov
+        if: matrix.ruby == '3.4'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage/coverage.xml
+          fail_ci_if_error: false
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

data/.rubocop.yml

@@ -0,0 +1,79 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'coverage/**/*'
+
+# Relaxed metrics for existing codebase
+Metrics/MethodLength:
+  Max: 100
+
+Metrics/AbcSize:
+  Max: 80
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 320
+
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+Metrics/PerceivedComplexity:
+  Max: 30
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/ParameterLists:
+  Max: 7
+
+# Style preferences
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+
+Layout/LineLength:
+  Max: 170
+  Exclude:
+    - 'spec/**/*'
+
+# File naming - allow hyphenated gem name
+Naming/FileName:
+  Exclude:
+    - 'lib/client-api-builder.rb'
+
+# Allow short parameter names for unused exception variables
+Naming/MethodParameterName:
+  AllowedNames:
+    - e
+    - _e
+    - io
+
+# Gemspec settings
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+# Style relaxations for existing code patterns
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+# Note: Previously had exclusions for Style/ClassVars, Style/PerlBackrefs, and
+# Lint/RescueException in router.rb - these have been fixed:
+# - ClassVars: Changed to thread-local storage
+# - PerlBackrefs: Changed to Regexp.last_match
+# - RescueException: Changed to StandardError

data/.ruby-version

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

data/ARCHITECTURE.md

@@ -0,0 +1,223 @@
+# 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.
+
+## File Structure
+
+```
+lib/
+├── client-api-builder.rb              # Main entry point, autoloads, error classes
+└── client_api_builder/
+    ├── router.rb                      # Core Router module with route DSL
+    ├── nested_router.rb               # NestedRouter class for hierarchical APIs
+    ├── section.rb                     # Section module for creating nested routers
+    ├── net_http_request.rb            # Net::HTTP request execution and streaming
+    ├── query_params.rb                # Custom query parameter builder
+    ├── active_support_notifications.rb # ActiveSupport instrumentation
+    └── active_support_log_subscriber.rb # ActiveSupport logging
+```
+
+## 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.
+
+**Class Methods** (defined in `ClassMethods`):
+- `base_url`: Sets the base URL for all requests
+- `header`: Adds headers to requests (supports values, symbols, or procs)
+- `route`: Defines API endpoints with dynamic method generation
+- `body_builder`: Configures request body formatting (`:to_json`, `:to_query`, `:query_params`, or custom)
+- `query_builder`: Configures query parameter formatting
+- `query_param`: Adds query parameters to all requests
+- `connection_option`: Sets Net::HTTP connection options
+- `configure_retries`: Sets retry behavior (max_retries, sleep time)
+- `namespace`: Groups routes under a common path prefix
+
+**Instance Methods**:
+- `build_headers`: Constructs request headers, evaluating procs/symbols
+- `build_connection_options`: Merges default and request-specific options
+- `build_query`: Formats query parameters using configured builder
+- `build_body`: Formats request body using configured builder
+- `build_uri`: Constructs full URI with base_url, path, and query
+- `handle_response`: Processes API responses, parses JSON by default
+- `request_wrapper`: Manages request execution with retry and instrumentation
+- `root_router`: Returns self (overridden in NestedRouter)
+
+**Instance Attributes** (via `attr_reader`):
+- `response`: The last Net::HTTP response object
+- `request_options`: Hash of method, uri, body, headers, connection_options
+- `total_request_time`: Duration of last request in seconds
+- `request_attempts`: Number of attempts for last request
+
+### 2. Route Code Generation
+
+The `route` class method dynamically generates two methods per endpoint using `generate_route_code`:
+
+```ruby
+route :get_user, '/users/:id', expected_response_code: 200
+```
+
+Generates:
+- `get_user_raw_response(id:, **options, &block)` - Makes HTTP request, sets `@response` and `@request_options`
+- `get_user(id:, **options, &block)` - Wraps raw_response with retry logic, response code validation, and response handling
+
+**Path Parameters**: Extracted from `:param` or `{param}` syntax in path
+**Body/Query Parameters**: Extracted from `body:` and `query:` options using symbol values
+
+### 3. HTTP Method Auto-Detection
+
+When `method:` is not specified in route options, `auto_detect_http_method` infers it from the method name:
+
+| Prefix Pattern | HTTP Method |
+|---------------|-------------|
+| `post`, `create`, `add`, `insert` | POST |
+| `put`, `update`, `modify`, `change` | PUT |
+| `patch` | PATCH |
+| `delete`, `remove` | DELETE |
+| (default) | GET |
+
+### 4. Nested Router (`ClientApiBuilder::NestedRouter`)
+
+Enables hierarchical API client organization:
+
+```ruby
+section :users do
+  route :list, '/'
+  route :get, '/:id'
+end
+# Usage: client.users.get(id: 123)
+```
+
+Key behaviors:
+- Includes `ClientApiBuilder::Router` module
+- Stores `root_router` reference to access shared state
+- Stores `nested_router_options` passed from section definition
+- Overrides `base_url` to fall back to root_router's base_url
+- Delegates `handle_response` to root_router
+- Overrides `get_instance_method` to access root_router's instance variables in paths
+
+### 5. Section Module (`ClientApiBuilder::Section`)
+
+Creates nested routers dynamically using `InheritanceHelper::ClassBuilder::Utils.create_class`:
+
+```ruby
+def section(name, nested_router_options={}, &block)
+  # Creates: MyClient::UsersNestedRouter < ClientApiBuilder::NestedRouter
+  # Defines: MyClient.users_router (class method)
+  # Defines: MyClient#users (instance method, memoized)
+end
+```
+
+### 6. NetHTTP::Request Module
+
+Provides HTTP request execution using Net::HTTP:
+
+**Methods**:
+- `request(method:, uri:, body:, headers:, connection_options:)` - Standard request with optional block
+- `stream(...)` - Streams response body in chunks via `read_body`
+- `stream_to_io(..., io:)` - Writes streamed chunks to an IO object
+- `stream_to_file(..., file:)` - Opens file and streams to it
+
+**Supported HTTP Methods** (via `METHOD_TO_NET_HTTP_CLASS`):
+`copy`, `delete`, `get`, `head`, `lock`, `mkcol`, `move`, `options`, `patch`, `post`, `propfind`, `proppatch`, `put`, `trace`, `unlock`
+
+### 7. QueryParams Class
+
+Standalone query parameter builder (used when ActiveSupport unavailable):
+
+- Handles nested hashes with bracket notation: `user[name]=John`
+- Handles arrays: `ids[]=1&ids[]=2`
+- Configurable separators: `name_value_separator` (default `=`), `param_separator` (default `&`)
+- Supports custom escape proc
+
+### 8. ActiveSupport Integration
+
+**ActiveSupportNotifications** (conditionally included when ActiveSupport defined):
+- Overrides `instrument_request` to use `ActiveSupport::Notifications.instrument`
+- Event name: `client_api_builder.request`
+- Payload includes `client: self`
+
+**ActiveSupportLogSubscriber**:
+- Subscribes to `client_api_builder.request` events for logging
+
+## Design Patterns
+
+### Module Inclusion Pattern
+
+```ruby
+module ClientApiBuilder
+  module Router
+    def self.included(base)
+      base.extend InheritanceHelper::Methods
+      base.extend ClassMethods
+      base.include ::ClientApiBuilder::Section
+      base.include ::ClientApiBuilder::NetHTTP::Request
+      base.include(::ClientApiBuilder::ActiveSupportNotifications) if defined?(ActiveSupport)
+      base.send(:attr_reader, :response, :request_options, :total_request_time, :request_attempts)
+    end
+  end
+end
+```
+
+### Builder Pattern
+
+Request components built separately then combined:
+```ruby
+__uri__ = build_uri(__path__, __query__, __options__)
+__body__ = build_body(__body__, __options__)
+__headers__ = build_headers(__options__)
+__connection_options__ = build_connection_options(__options__)
+```
+
+### Configuration Inheritance
+
+Uses `inheritance-helper` gem's `add_value_to_class_method` for configuration that properly inherits to subclasses:
+```ruby
+def base_url(url = nil)
+  return default_options[:base_url] unless url
+  add_value_to_class_method(:default_options, base_url: url)
+end
+```
+
+## Configuration Hierarchy
+
+1. **Default Options**: `Router.default_options` returns frozen hash with defaults
+2. **Class-level Configuration**: Set through DSL methods, stored via `add_value_to_class_method`
+3. **Instance-level**: Access class config, can override in method calls
+4. **Request-level**: `**__options__` parameter on generated methods
+
+## Error Handling
+
+- `ClientApiBuilder::Error`: Base error class
+- `ClientApiBuilder::UnexpectedResponse`: Raised when response code doesn't match expected codes
+  - Stores `response` for inspection
+- Response procs: Per-route custom response handling stored in `default_options[:response_procs]`
+- Retry on exception: `retry_request?` method (always returns true by default, override to customize)
+
+## Streaming Support
+
+Routes can specify streaming behavior:
+
+```ruby
+route :download, '/file', stream: :file    # stream_to_file, requires file: argument
+route :stream, '/events', stream: :io      # stream_to_io, requires io: argument
+route :process, '/data', stream: :block    # stream with block for each chunk
+route :download, '/file', stream: true     # alias for :file
+```
+
+## Dependencies
+
+- `inheritance-helper`: Class inheritance and configuration management
+- `json`: JSON parsing and serialization (stdlib)
+- `net/http`: HTTP request handling (stdlib)
+- `cgi`: URL encoding in QueryParams (stdlib)
+- `active_support` (optional): Enhanced query building and instrumentation
+
+## Thread Safety
+
+The library is not thread-safe. Each client instance maintains state (`@response`, `@request_options`, etc.) that would cause race conditions if shared across threads. Create separate client instances per thread.

data/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Client API Builder is a Ruby gem for creating API clients through declarative configuration. It uses Ruby's module inclusion pattern with `ClientApiBuilder::Router` as the core component.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/client_api_builder/router_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/client_api_builder/router_spec.rb:42
+
+# Run linter
+bundle exec rubocop
+
+# Build the gem
+gem build client-api-builder.gemspec
+```
+
+## Architecture
+
+### Core Components
+
+- **Router** (`lib/client_api_builder/router.rb`): Main module providing `route`, `base_url`, `header`, `body_builder`, `query_builder`, and `configure_retries` class methods. Uses `InheritanceHelper::Methods` for configuration inheritance.
+
+- **NestedRouter** (`lib/client_api_builder/nested_router.rb`): Enables hierarchical API organization. Maintains reference to `root_router` and shares configuration with parent.
+
+- **Section** (`lib/client_api_builder/section.rb`): Provides `section` class method for creating nested route groups via dynamically generated classes.
+
+- **NetHTTP::Request** (`lib/client_api_builder/net_http_request.rb`): HTTP request execution using `Net::HTTP`. Handles standard requests and streaming (`:file`, `:io`, `:block` modes).
+
+- **QueryParams** (`lib/client_api_builder/query_params.rb`): Custom query parameter builder used when ActiveSupport's `to_query` is unavailable.
+
+- **ActiveSupportNotifications/LogSubscriber**: Optional integration for logging and instrumentation when ActiveSupport is present.
+
+### Route Code Generation
+
+The `route` class method in Router uses `generate_route_code` to dynamically create two methods per route:
+1. `method_name_raw_response` - Makes the HTTP request
+2. `method_name` - Wraps the request with retry logic and response handling
+
+### HTTP Method Auto-Detection
+
+Methods are auto-detected from route names: `post/create/add/insert` → POST, `put/update/modify/change` → PUT, `patch` → PATCH, `delete/remove` → DELETE, others → GET.
+
+### Configuration Hierarchy
+
+1. `default_options` class method (base defaults)
+2. Class-level configuration via DSL methods
+3. Instance-level overrides
+4. Request-level options (`**__options__`)
+
+## Key Patterns
+
+- Module inclusion with `self.included(base)` extending ClassMethods and including InstanceMethods
+- `add_value_to_class_method` from `inheritance-helper` for configuration inheritance
+- Response procs stored per method name for custom response handling
+- `root_router` method for accessing the top-level router from nested routers
+
+## Dependencies
+
+- `inheritance-helper` (runtime): Class inheritance and method management
+- `webmock` (test): HTTP request stubbing
+- `activesupport` (optional): Enhanced query param building and instrumentation
+
+## Code Commits
+
+Format using angular formatting:
+```
+<type>(<scope>): <short summary>
+```
+- **type**: build|ci|docs|feat|fix|perf|refactor|test
+- **scope**: The feature or component of the service we're working on
+- **summary**: Summary in present tense. Not capitalized. No period at the end.
+
+## Documentation Maintenance
+
+When modifying the codebase, keep documentation in sync:
+- **ARCHITECTURE.md** - Update when adding/removing classes, changing component relationships, or altering data flow patterns
+- **README.md** - Update when adding new features, changing public APIs, or modifying usage examples
+- **Code comments** - Update inline documentation when changing method signatures or behavior

data/Gemfile

@@ -5,13 +5,11 @@ source 'http://rubygems.org'
 gem 'inheritance-helper'
 
 group :development do
-  gem 'rake'
-  gem 'rubocop'
-end
-
-group :spec do
   gem 'activesupport'
+  gem 'rake'
   gem 'rspec'
+  gem 'rubocop'
   gem 'simplecov'
+  gem 'simplecov-cobertura'
   gem 'webmock'
 end

data/Gemfile.lock

@@ -1,73 +1,105 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (7.0.2.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      json
+      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)
+      uri (>= 0.13.1)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crack (1.0.1)
+      bigdecimal
       rexml
-    diff-lcs (1.5.0)
-    docile (1.4.0)
-    hashdiff (1.0.1)
-    i18n (1.10.0)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    drb (2.2.3)
+    hashdiff (1.2.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     inheritance-helper (0.2.5)
-    minitest (5.15.0)
-    parallel (1.21.0)
-    parser (3.1.1.0)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    parallel (1.27.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
-    public_suffix (4.0.6)
+      racc
+    prism (1.9.0)
+    public_suffix (7.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.3.1)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       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.7)
       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.7)
+    rubocop (1.84.0)
+      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.49.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.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    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-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
+    simplecov-html (0.13.2)
     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.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
-  x86_64-darwin-21
+  arm64-darwin-24
+  ruby
 
 DEPENDENCIES
   activesupport
@@ -76,7 +108,8 @@ DEPENDENCIES
   rspec
   rubocop
   simplecov
+  simplecov-cobertura
   webmock
 
 BUNDLED WITH
-   2.3.3
+   2.6.2