api_adaptor 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d434d1287d28256b67543919c32dba816a5c6a682247108a985eee72ac7ca86c
-  data.tar.gz: e386558347941960b7c54bbd0107381202bfcf4c8318c0ac3908cf2bd3e1c99a
+  metadata.gz: a7f99a36581d23c2d20acb77209e83094d0376abfebbe485961c716ad5a2996e
+  data.tar.gz: d247399af57052605021e37293944d92da841351f958d45ea7f00153b1a075c7
 SHA512:
-  metadata.gz: 3ee873a96fa726a95caf41861a683abc276571b3a6424ae44f7ede1c0cc27e242de879b7f8f73930f10c0347d60ff6d31595ba55235a5be1a39e36208359e524
-  data.tar.gz: 0a42e0ded563c8f1b9cab2433c8f3f5ca5160da8df923deb80382ecb3736012fa0a136d53799b4681011f6723c18eceaf5fd9e3e2ee853071ca4d38a9903b1ba
+  metadata.gz: fe8f8c29cfad7facd7b38ec9d7d1ca7076fa603a881ee19cff99d937f6911857c8b5b288ba1e2d49c7c71ccfc6ad8dd5e206bc28133548711cc7b4b7242ac6d8
+  data.tar.gz: fc13ade3b00830ee758141678ed28928d8fb4111bb241b25ac2e281064056b4fb9835ccef407779e9465a2f74bd67b68133d552fa82f001d940cd7a34814687c

data/.rubocop.yml

@@ -1,5 +1,10 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.2
+  NewCops: disable
+  SuggestExtensions: false
+
+plugins:
+  - rubocop-yard
 
 Style/StringLiterals:
   Enabled: true
@@ -10,13 +15,7 @@ Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
 Layout/LineLength:
-  Max: 120
-
-Metrics:
   Enabled: false
 
-Style/Documentation:
+Metrics:
   Enabled: false
-
-Layout/LineLength:
-  Enabled: false

data/.yardopts

@@ -0,0 +1,10 @@
+--markup markdown
+--markup-provider redcarpet
+--output-dir doc
+--readme README.md
+--no-private
+--protected
+lib/**/*.rb
+-
+README.md
+CLAUDE.md

data/CHANGELOG.md

@@ -1,4 +1,45 @@
-## [Unreleased]
+## [1.0.0] - 2026-02-15
+
+### Added
+- YARD documentation for all public APIs (100% coverage)
+- YARD documentation deployment to GitHub Pages
+- CLAUDE.md development guide for AI assistants and contributors
+- rubocop-yard plugin for documentation linting
+- API Documentation section in README with links to hosted docs
+- Development section in README with testing, coverage, and documentation commands
+- Troubleshooting section in README for common issues
+- Badges in README for CI status, gem version, and documentation
+
+### Changed
+- README enhanced with wikidata_adaptor best practices
+- Default Rake task now includes YARD documentation generation
+- RuboCop now enforces documentation standards via rubocop-yard
+- GitHub Actions updated to use consistent SHA pinning across all workflows
+- All development dependencies updated to latest compatible versions
+
+### Fixed
+- Standardized GitHub Actions versions across all workflows
+- Updated ruby/setup-ruby to v1.288.0 in all workflows
+- Updated rubygems/release-gem to v1.1.2 in release workflow
+- Updated actions/configure-pages to v5.0.0 in pages workflow
+- Updated actions/upload-pages-artifact to v4.0.0 in pages workflow
+- Updated actions/deploy-pages to v4.0.5 in pages workflow
+- Fixed invalid date format in CHANGELOG (2025-31-01 → 2025-01-31)
+
+## [0.1.0] - 2025-01-31
+
+- Improvements to 307, 308 redirect behaviour
+- Greater configuration over redirect behaviour
+- Add CI/CD to Rubygems
+- Test against Ruby v4.0
+
+## [0.0.2] - 2024-14-01
+
+- Improvements to CI/CD
+  - Enable CodeQL
+  - Enable Dependabot
+  - Enable Rubocop Testing
+  - Enable unit testing against Ruby v3.2, v3.3, v3.4
 
 ## [0.0.1] - 2023-06-01
 

data/CLAUDE.md

@@ -0,0 +1,423 @@
+# CLAUDE.md - Developer Guide for api_adaptor
+
+This guide is for AI assistants and human contributors working on api_adaptor. It provides context about the project's architecture, conventions, and development workflow.
+
+## Overview
+
+**api_adaptor** is a Ruby gem that provides a basic HTTP client adaptor for JSON APIs. It handles common patterns like request/response parsing, redirects, error handling, and pagination, allowing developers to quickly build API clients without repetitive boilerplate.
+
+### Key Features
+
+- JSON request/response handling with automatic parsing
+- Configurable redirect handling (cross-origin, non-GET requests)
+- Bearer token and basic authentication support
+- Pagination support via `ListResponse`
+- Cache-Control header parsing
+- Comprehensive exception hierarchy for HTTP errors
+- Thread-safe connection pooling via rest-client
+
+### Architecture
+
+- **JSONClient**: Core HTTP client with redirect handling and authentication
+- **Base**: Abstract base class for building API-specific clients
+- **Response/ListResponse**: Wrapper classes for parsed responses
+- **Headers**: Manages request headers including User-Agent
+- **Variables**: Environment variable configuration for app metadata
+- **Exceptions**: HTTP error hierarchy
+
+## Commands
+
+### Development
+
+```bash
+bundle install              # Install dependencies
+bundle exec rspec           # Run tests
+bundle exec rubocop         # Run linter
+bundle exec rake            # Run tests + linter + generate docs (default)
+```
+
+### Documentation
+
+```bash
+bundle exec yard            # Generate YARD documentation to doc/
+bundle exec yard server     # Preview docs at http://localhost:8808
+bundle exec yard stats      # View documentation coverage
+```
+
+### Coverage
+
+```bash
+bundle exec rspec           # Generates coverage report
+open coverage/index.html    # View coverage report
+```
+
+### Release
+
+```bash
+# Manual release (not recommended - use GitHub Actions)
+bundle exec rake release    # Build gem, create git tag, push to RubyGems
+
+# Automated release (recommended)
+git tag v1.0.0              # Create version tag
+git push origin v1.0.0      # Push tag to trigger release workflow
+```
+
+## Project Structure
+
+### Core Files
+
+```
+lib/
+├── api_adaptor.rb                  # Main entry point, loads all components
+├── api_adaptor/
+│   ├── version.rb                  # VERSION constant
+│   ├── json_client.rb              # HTTP client with JSON parsing
+│   ├── base.rb                     # Base class for API clients
+│   ├── response.rb                 # Response wrapper with cache control
+│   ├── list_response.rb            # Paginated response wrapper
+│   ├── exceptions.rb               # HTTP exception hierarchy
+│   ├── headers.rb                  # Header management
+│   └── variables.rb                # Environment variable config
+```
+
+### Configuration
+
+- `api_adaptor.gemspec` - Gem specification and dependencies
+- `Rakefile` - Rake tasks (test, lint, docs)
+- `.rubocop.yml` - RuboCop linting configuration
+- `.yardopts` - YARD documentation configuration
+- `.rspec` - RSpec test configuration
+
+### Tests
+
+```
+spec/
+├── spec_helper.rb                  # Test configuration with SimpleCov
+├── api_adaptor/
+│   ├── base_spec.rb                # Base class tests
+│   ├── exceptions_spec.rb          # Exception handling tests
+│   ├── headers_spec.rb             # Header tests
+│   ├── json_client_spec.rb         # Core client tests
+│   ├── list_response_spec.rb       # Pagination tests
+│   ├── response_spec.rb            # Response wrapper tests
+│   └── variables_spec.rb           # Environment variable tests
+└── fixtures/                       # Test fixtures including foo.json
+```
+
+### CI/CD
+
+```
+.github/workflows/
+├── ci.yml                          # Main CI (RSpec tests)
+├── quality-checks.yml              # RuboCop linting
+├── release.yml                     # Automated gem release
+├── pages.yml                       # Deploy fixtures to GitHub Pages
+├── docs.yml                        # Deploy YARD docs to GitHub Pages
+└── codeql.yml                      # Security scanning
+```
+
+## Testing Conventions
+
+### Test Structure
+
+- Use RSpec with descriptive contexts
+- Mock HTTP requests with WebMock
+- Use Timecop for time-sensitive tests
+- Aim for ≥80% line coverage, ≥75% branch coverage
+
+### Test Patterns
+
+```ruby
+# Good: Descriptive context and it blocks
+describe JSONClient do
+  describe "#get_json" do
+    context "when request succeeds" do
+      it "returns parsed JSON response" do
+        # ...
+      end
+    end
+
+    context "when request fails" do
+      it "raises appropriate exception" do
+        # ...
+      end
+    end
+  end
+end
+
+# Good: Use WebMock for HTTP mocking
+stub_request(:get, "https://example.com/api")
+  .to_return(status: 200, body: '{"key": "value"}')
+
+# Good: Use Timecop for time tests
+Timecop.freeze(Time.utc(2024, 1, 1, 12, 0, 0)) do
+  # ...
+end
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec                   # Run all tests
+bundle exec rspec spec/api_adaptor/json_client_spec.rb  # Run specific file
+bundle exec rspec spec/api_adaptor/json_client_spec.rb:42  # Run specific line
+```
+
+## Environment Variables
+
+The gem reads app metadata from environment variables for User-Agent headers:
+
+- `APP_NAME` - Application name (default: "Ruby ApiAdaptor App")
+- `APP_VERSION` - Application version (default: "Version not stated")
+- `APP_CONTACT` - Contact email/URL for API providers
+
+### Example .env
+
+```bash
+APP_NAME=MyApiClient
+APP_VERSION=2.1.0
+APP_CONTACT=dev@example.com
+```
+
+These are accessed via `ApiAdaptor::Variables` methods.
+
+## Git Standards
+
+Never commit to main branch,
+Always create a new branch with a sensible descriptive name and expect a Pull Request process.
+
+You'll need to provide a good PR description that sums up any collected change.
+
+## Commit Standards
+
+Follows [GDS Git conventions](https://gds-way.digital.cabinet-office.gov.uk/standards/source-code/working-with-git.html#commits), informed by [chris.beams.io/posts/git-commit](https://chris.beams.io/posts/git-commit), [thoughtbot](https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message), [mislav.net](https://mislav.net/2014/02/hidden-documentation/), and [Joel Chippindale's "Telling Stories Through Your Commits"](https://blog.mocoso.co.uk/posts/talks/telling-stories-through-your-commits/).
+
+### Formatting
+
+- **[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)** — subject line format: `<type>[optional scope]: <description>`
+- **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
+- **Scope** — optional parenthetical context, e.g. `feat(labels):` or `fix(integration):`
+- **Breaking changes** — indicated with `!` before the colon, e.g. `feat!:`, or a `BREAKING CHANGE:` footer
+- **Subject line** — max 50 characters, no trailing period, imperative mood ("Add feature" not "Added feature")
+- **Body** — separated from subject by a blank line, wrapped at 72 characters
+- **Links supplement, not replace** — issue/PR links may go stale, so the message must stand on its own
+
+### Content
+
+- **Answer three questions**: Why is this change necessary? How does it address the issue? What side effects does it have?
+- **Explain the "why"** — the code shows _how_; the commit message must capture _why_. Rationale and context are hard to reconstruct later
+- **Note alternatives considered** — if you chose approach A over B, say so and why
+
+### Structure
+
+- **Atomic commits** — each commit is a self-contained, logical unit of work; avoid needing "and" in your subject line
+- **Tell a story** — commits should be logically ordered so the history reads as a coherent narrative, not a jumbled log
+- **Clean up before sharing** — revise commit history on feature branches before opening a PR
+
+## Development Workflow
+
+### TDD Approach (Recommended)
+
+1. **Write failing test** - Define expected behavior
+2. **Implement feature** - Write minimal code to pass test
+3. **Refactor** - Improve code while keeping tests green
+4. **Document** - Add YARD comments to public APIs
+5. **Lint** - Run `bundle exec rubocop` and fix issues
+6. **Commit** - Use conventional commit message
+
+### Feature Development Cycle
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/add-retry-logic
+
+# 2. Write test
+# Edit spec/api_adaptor/json_client_spec.rb
+
+# 3. Run test (should fail)
+bundle exec rspec spec/api_adaptor/json_client_spec.rb
+
+# 4. Implement feature
+# Edit lib/api_adaptor/json_client.rb
+
+# 5. Run test (should pass)
+bundle exec rspec spec/api_adaptor/json_client_spec.rb
+
+# 6. Run full test suite
+bundle exec rake
+
+# 7. Commit
+git add .
+git commit -m "feat(client): add retry logic for transient failures"
+
+# 8. Push and create PR
+git push origin feature/add-retry-logic
+gh pr create
+```
+
+### Code Review Checklist
+
+- [ ] Tests pass (`bundle exec rspec`)
+- [ ] Linter passes (`bundle exec rubocop`)
+- [ ] Coverage maintained (≥80% line, ≥75% branch)
+- [ ] YARD documentation added for public APIs
+- [ ] CHANGELOG.md updated (if applicable)
+- [ ] Conventional commit message used
+
+## Release Process
+
+### Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking API changes (1.0.0 → 2.0.0)
+- **MINOR**: New features, backward-compatible (1.0.0 → 1.1.0)
+- **PATCH**: Bug fixes, backward-compatible (1.0.0 → 1.0.1)
+
+### Release Checklist
+
+1. **Update version** - Edit `lib/api_adaptor/version.rb`
+2. **Update CHANGELOG** - Add entry with date in `CHANGELOG.md`
+3. **Run full test suite** - `bundle exec rake` (includes tests, lint, docs)
+4. **Commit changes** - `chore(release): prepare v1.0.0`
+5. **Create git tag** - `git tag v1.0.0`
+6. **Push tag** - `git push origin v1.0.0`
+7. **GitHub Actions triggers** - Release workflow builds and publishes gem to RubyGems
+8. **Verify release** - Check https://rubygems.org/gems/api_adaptor
+
+### Automated Release
+
+The `.github/workflows/release.yml` workflow handles:
+
+- Building the gem
+- Running tests
+- Publishing to RubyGems (using `RUBYGEMS_API_KEY` secret)
+- Creating GitHub release
+
+## Documentation Standards
+
+### YARD Comments
+
+All public APIs must have YARD documentation:
+
+```ruby
+# Initializes a new JSON client
+#
+# @param options [Hash] Configuration options
+# @option options [String] :bearer_token Bearer token for authentication
+# @option options [Hash] :basic_auth Basic auth credentials (:user, :password)
+# @option options [Integer] :timeout Request timeout in seconds (default: 4)
+# @option options [Integer] :max_redirects Maximum redirects to follow (default: 3)
+# @option options [Boolean] :allow_cross_origin_redirects Allow cross-origin redirects (default: true)
+# @option options [Logger] :logger Custom logger instance
+#
+# @return [JSONClient] A new instance of JSONClient
+#
+# @example Basic usage
+#   client = JSONClient.new(bearer_token: "abc123")
+#
+# @example With custom timeout
+#   client = JSONClient.new(timeout: 10)
+def initialize(options = {})
+  # ...
+end
+```
+
+### Documentation Commands
+
+```bash
+bundle exec yard stats --list-undoc  # Find undocumented methods
+bundle exec yard server              # Preview docs locally
+```
+
+## Code Quality Standards
+
+### Coverage Targets
+
+- **Line Coverage**: ≥80% (current: 92.3%)
+- **Branch Coverage**: ≥75% (current: 81.65%)
+
+### RuboCop Configuration
+
+- Follows standard Ruby style guide
+- Custom cops enabled: `rubocop-yard` for documentation enforcement
+- Configuration in `.rubocop.yml`
+
+### Security
+
+- Input validation at API boundaries
+- Safe redirect handling with cross-origin protection
+- No credential logging
+- CodeQL security scanning enabled
+
+## Common Tasks
+
+### Adding a New Exception
+
+1. Define exception in `lib/api_adaptor/exceptions.rb`
+2. Add YARD documentation
+3. Add test in `spec/api_adaptor/exceptions_spec.rb`
+4. Update `json_client.rb` to raise exception where appropriate
+
+### Adding a New Configuration Option
+
+1. Add parameter to `JSONClient#initialize`
+2. Document with YARD `@option` tag
+3. Add instance variable and accessor
+4. Add tests for new behavior
+5. Update README with example
+
+### Debugging HTTP Requests
+
+```ruby
+# Enable request/response logging
+client = JSONClient.new(logger: Logger.new($stdout))
+```
+
+## Troubleshooting
+
+### Tests Failing
+
+```bash
+# Run specific test
+bundle exec rspec spec/api_adaptor/json_client_spec.rb:42
+
+# Run with verbose output
+bundle exec rspec --format documentation
+
+# Check coverage
+open coverage/index.html
+```
+
+### RuboCop Errors
+
+```bash
+# Auto-fix safe violations
+bundle exec rubocop --auto-correct
+
+# Fix all violations (less safe)
+bundle exec rubocop --auto-correct-all
+```
+
+### YARD Documentation Issues
+
+```bash
+# Check for undocumented methods
+bundle exec yard stats --list-undoc
+
+# Validate YARD syntax
+bundle exec yard --no-output
+```
+
+## Additional Resources
+
+- **RubyGems**: https://rubygems.org/gems/api_adaptor
+- **GitHub**: https://github.com/huwd/api_adaptor
+- **YARD Docs**: https://huwd.github.io/api_adaptor/
+- **Issues**: https://github.com/huwd/api_adaptor/issues
+
+## Contact
+
+- **Maintainer**: Huw Diprose
+- **Email**: mail@huwdiprose.co.uk
+- **License**: MIT

data/Gemfile.lock

@@ -1,80 +1,105 @@
 PATH
   remote: .
   specs:
-    api_adaptor (0.0.2)
+    api_adaptor (1.0.0)
       addressable (~> 2.8)
+      base64 (~> 0.3)
+      bigdecimal (>= 3.3, < 5.0)
       link_header (~> 0.0.8)
+      logger (>= 1.6, < 2.0)
       rest-client (~> 2.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
-    ast (2.4.2)
-    crack (0.4.5)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    crack (1.0.1)
+      bigdecimal
       rexml
-    diff-lcs (1.5.0)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
     domain_name (0.6.20240107)
-    hashdiff (1.1.0)
+    hashdiff (1.2.1)
     http-accept (1.7.0)
     http-cookie (1.0.5)
       domain_name (~> 0.5)
-    json (2.7.1)
-    language_server-protocol (3.17.0.3)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
     link_header (0.0.8)
+    lint_roller (1.1.0)
+    logger (1.7.0)
     mime-types (3.5.2)
       mime-types-data (~> 3.2015)
     mime-types-data (3.2023.1205)
     netrc (0.11.0)
-    parallel (1.24.0)
-    parser (3.3.0.3)
+    parallel (1.27.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
       racc
-    public_suffix (5.0.4)
-    racc (1.7.3)
+    prism (1.9.0)
+    public_suffix (7.0.2)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.1.0)
-    regexp_parser (2.9.0)
+    rake (13.3.1)
+    redcarpet (3.6.1)
+    regexp_parser (2.11.3)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
-    rexml (3.2.6)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.2)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.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.12.0)
-    rspec-mocks (3.12.6)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.1)
-    rubocop (1.59.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.84.2)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.2.2.4)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.30.0)
-      parser (>= 3.2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-yard (1.1.0)
+      lint_roller
+      rubocop (~> 1.72)
+      yard
     ruby-progressbar (1.13.0)
-    timecop (0.9.8)
-    unicode-display_width (2.5.0)
-    webmock (3.19.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    timecop (0.9.10)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.38)
 
 PLATFORMS
   x86_64-linux
@@ -82,10 +107,14 @@ PLATFORMS
 DEPENDENCIES
   api_adaptor!
   rake (~> 13.0)
+  redcarpet (~> 3.6)
   rspec (~> 3.0)
   rubocop (~> 1.21)
+  rubocop-yard
+  simplecov (~> 0.22)
   timecop (~> 0.9)
   webmock (~> 3.18)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.4.13