api_adaptor 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec2d6e2bc7c54d07e88bee9945a772f952076ba24b3f1fdf176e951bae3f8dad
-  data.tar.gz: c0d9d319cd02061d462eaba8bdc8cfd5a8dda94df5973e7ba8ef78fc3dada248
+  metadata.gz: a7f99a36581d23c2d20acb77209e83094d0376abfebbe485961c716ad5a2996e
+  data.tar.gz: d247399af57052605021e37293944d92da841351f958d45ea7f00153b1a075c7
 SHA512:
-  metadata.gz: 7ac1bd16754ce9ae420ad5ba9d3fc9d92ad280f896afcb5312688b880b228c179ca75a8edb6a16811064f6c3d71805045aae22312137b325b067a0339c801acf
-  data.tar.gz: 9dd42bfacca8f947ac4977c3f1a4970db143118dd101c851b61ecae8a4462cde109f4157e542020e57f147f01cc83973c11de3a8e9d0093dd7991241b1669485
+  metadata.gz: fe8f8c29cfad7facd7b38ec9d7d1ca7076fa603a881ee19cff99d937f6911857c8b5b288ba1e2d49c7c71ccfc6ad8dd5e206bc28133548711cc7b4b7242ac6d8
+  data.tar.gz: fc13ade3b00830ee758141678ed28928d8fb4111bb241b25ac2e281064056b4fb9835ccef407779e9465a2f74bd67b68133d552fa82f001d940cd7a34814687c

data/.rubocop.yml

@@ -3,6 +3,9 @@ AllCops:
   NewCops: disable
   SuggestExtensions: false
 
+plugins:
+  - rubocop-yard
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
@@ -16,6 +19,3 @@ Layout/LineLength:
 
 Metrics:
   Enabled: false
-
-Style/Documentation:
-  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,32 @@
-## [0.1.0] - 2025-31-01
+## [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

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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api_adaptor (0.1.0)
+    api_adaptor (1.0.0)
       addressable (~> 2.8)
       base64 (~> 0.3)
       bigdecimal (>= 3.3, < 5.0)
@@ -27,7 +27,7 @@ GEM
     http-accept (1.7.0)
     http-cookie (1.0.5)
       domain_name (~> 0.5)
-    json (2.18.0)
+    json (2.18.1)
     language_server-protocol (3.17.0.5)
     link_header (0.0.8)
     lint_roller (1.1.0)
@@ -45,6 +45,7 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     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)
@@ -65,7 +66,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.84.0)
+    rubocop (1.84.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -79,6 +80,10 @@ GEM
     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)
     simplecov (0.22.0)
       docile (~> 1.1)
@@ -94,6 +99,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.38)
 
 PLATFORMS
   x86_64-linux
@@ -101,11 +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

data/README.md

@@ -1,5 +1,9 @@
 # ApiAdaptor
 
+[![CI](https://github.com/huwd/api_adaptor/actions/workflows/quality-checks.yml/badge.svg)](https://github.com/huwd/api_adaptor/actions/workflows/quality-checks.yml)
+[![Gem Version](https://badge.fury.io/rb/api_adaptor.svg)](https://badge.fury.io/rb/api_adaptor)
+[![Documentation](https://img.shields.io/badge/docs-YARD-blue.svg)](https://huwd.github.io/api_adaptor/)
+
 A basic adaptor to send HTTP requests and parse the responses.
 Intended to bootstrap the quick writing of Adaptors for specific APIs, without having to write the same old JSON request and processing time and time again.
 
@@ -17,6 +21,17 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install api_adaptor
 ```
 
+## API Documentation
+
+Full API documentation is available at [https://huwd.github.io/api_adaptor/](https://huwd.github.io/api_adaptor/)
+
+Generate documentation locally:
+
+```bash
+bundle exec yard         # Generate docs to doc/
+bundle exec yard server  # Preview at http://localhost:8808
+```
+
 ## Releasing
 
 Publishing is handled by GitHub Actions when you push a version tag.
@@ -196,6 +211,76 @@ User agent would read
 test_app/1.0.0 (contact@example.com)
 ```
 
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+### Running Tests
+
+```bash
+bundle exec rspec        # Run tests only
+bundle exec rubocop      # Run linter only
+bundle exec rake         # Run tests, linter, and build docs
+```
+
+### Code Coverage
+
+SimpleCov tracks test coverage. View the report at `coverage/index.html` after running tests.
+
+Current coverage: 92.3% line, 81.65% branch
+
+### Documentation
+
+Generate YARD documentation:
+
+```bash
+bundle exec yard         # Generate docs to doc/
+bundle exec yard server  # Preview at http://localhost:8808
+bundle exec yard stats   # View documentation coverage
+```
+
+### Quality Standards
+
+- **Tests:** RSpec with WebMock for HTTP mocking
+- **Linting:** RuboCop with rubocop-yard for documentation
+- **Coverage:** SimpleCov (minimum 80% line, 75% branch)
+- **Documentation:** YARD for all public APIs
+
+## Troubleshooting
+
+### Redirects Not Following
+
+By default, only GET/HEAD requests follow redirects. For POST/PUT/PATCH/DELETE:
+
+```ruby
+client = MyApi.new("https://example.com", follow_non_get_redirects: true)
+```
+
+### Timeout Errors
+
+Default timeout is 4 seconds. Configure longer timeouts:
+
+```ruby
+client = MyApi.new("https://example.com", timeout: 10)
+```
+
+### Cross-Origin Redirect Security
+
+By default, auth headers are stripped on cross-origin redirects. To allow (use with caution):
+
+```ruby
+client = MyApi.new(
+  "https://example.com",
+  forward_auth_on_cross_origin_redirects: true  # Security risk!
+)
+```
+
+Or disable cross-origin redirects entirely:
+
+```ruby
+client = MyApi.new("https://example.com", allow_cross_origin_redirects: false)
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/huwd/api_adaptor>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/huwd/api_adaptor/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -9,4 +9,10 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+require "yard"
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.stats_options = ["--list-undoc"]
+end
+
+task default: %i[spec rubocop yard]