jeckle 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4761ead36774dc1acab1c41b0365ff229c412677a75292aa1473acd381fd06cd
-  data.tar.gz: 64f4f522c235470e25be1660a414bebf5aabe81e4b60e934b1fcbd13ed08056b
+  metadata.gz: acac117a0dc0c961029fb70e87d6c2f412fe108989fdfec04d3d911274ceb460
+  data.tar.gz: 9ed85573a4512a3915071479500fd22b1901e8b852c23c3490ed9f35c4dd9c66
 SHA512:
-  metadata.gz: 94176cba14e8fa3ad4aac3006191f34dffc050ca6739a05e991715108f8a9a8b4e6abb9e937028e3230357b6a39146f015a8484fc29a8a987e5dab8d43ae0508
-  data.tar.gz: 719608cb95326167d652fd67fa76ceac3929ba4610a1705e4ad948c769d97177f3eaa161907e7396ade56cc32368fe0b625e9be043ae6884529a15adc200b9b3
+  metadata.gz: ce75de0db73e82f2b9f832eba3df78c9b862d812c85e98e1034d50a6b6aeb83b4db5070615fdb3c8a50239bbd9f9b8d8c1d09064c87a8ea81dda832680375eec
+  data.tar.gz: ea854a9bdf95b332be7feebe9fb6215c78a2bf3b120ad8707983c86d18e0971919220af8086ec8b14828a8341d0d76230f3bebb2ed7f9f1c74f052e75569b067

data/README.md

@@ -28,28 +28,133 @@ And then execute:
 $ bundle
 ```
 
-## Usage
-
-### Configuring an API
-
-Let's say you'd like to connect your app to Dribbble.com - a community of designers sharing screenshots of their work, process, and projects.
-
-First, you would need to configure the API:
+## Quick Start
 
 ```ruby
+# 1. Configure the API
 Jeckle.configure do |config|
   config.register :dribbble do |api|
     api.base_uri = 'http://api.dribbble.com'
+    api.bearer_token = ENV['DRIBBBLE_TOKEN']
     api.middlewares do
       response :json
+      response :jeckle_raise_error
     end
   end
 end
+
+# 2. Define a resource
+class Shot < Jeckle::Resource
+  api :dribbble
+
+  attribute :id, Jeckle::Types::Integer
+  attribute :name, Jeckle::Types::String
+  attribute :url, Jeckle::Types::String
+end
+
+# 3. Use it
+shot = Shot.find(1600459)
+shots = Shot.list(name: 'avengers')
 ```
 
-### Mapping resources
+## API Configuration
 
-Following the previous example, Dribbble.com consists of pieces of web designers work called "Shots". Each shot has the attributes `id`, `name`, `url` and `image_url`. A Jeckle resource representing Dribbble's shots would be something like this:
+### Basic Auth
+
+```ruby
+Jeckle.configure do |config|
+  config.register :my_api do |api|
+    api.base_uri = 'https://api.example.com'
+    api.basic_auth = { username: 'user', password: 'pass' }
+  end
+end
+```
+
+### Bearer Token
+
+```ruby
+config.register :my_api do |api|
+  api.base_uri = 'https://api.example.com'
+  api.bearer_token = 'my-oauth-token'
+end
+```
+
+### API Key (Header)
+
+```ruby
+config.register :my_api do |api|
+  api.base_uri = 'https://api.example.com'
+  api.api_key = { value: 'secret', header: 'X-Api-Key' }
+end
+```
+
+### API Key (Query Param)
+
+```ruby
+config.register :my_api do |api|
+  api.base_uri = 'https://api.example.com'
+  api.api_key = { value: 'secret', param: 'api_key' }
+end
+```
+
+### OAuth 2.0
+
+```ruby
+config.register :my_api do |api|
+  api.base_uri = 'https://api.example.com'
+  api.oauth2 = {
+    client_id: 'id',
+    client_secret: 'secret',
+    token_url: 'https://auth.example.com/oauth/token'
+  }
+end
+```
+
+### Environment-Based Configuration
+
+```ruby
+# Reads MY_API_BASE_URI, MY_API_BEARER_TOKEN from ENV
+Jeckle::Setup.register_from_env(:my_api)
+```
+
+### Automatic Retries
+
+```ruby
+config.register :my_api do |api|
+  api.base_uri = 'https://api.example.com'
+  api.retry = { max: 3, interval: 1, retry_statuses: [429, 503] }
+end
+```
+
+### Other Options
+
+```ruby
+config.register :my_api do |api|
+  api.base_uri = 'https://api.example.com'
+  api.namespaces = { prefix: 'api', version: 'v2' }
+  api.headers = { 'Content-Type' => 'application/json' }
+  api.params = { locale: 'en' }
+  api.open_timeout = 2
+  api.read_timeout = 5
+  api.logger = Rails.logger
+
+  api.middlewares do
+    request :json
+    response :json
+    response :jeckle_raise_error
+  end
+
+  # Extend Faraday defaults
+  api.configure_connection do |conn|
+    conn.use MyCustomMiddleware
+    conn.adapter :typhoeus
+  end
+end
+```
+
+## Defining Resources
+
+Resources inherit from `Jeckle::Resource` and use `Jeckle::Types` for attribute definitions:
 
 ```ruby
 class Shot < Jeckle::Resource
@@ -58,101 +163,252 @@ class Shot < Jeckle::Resource
   attribute :id, Jeckle::Types::Integer
   attribute :name, Jeckle::Types::String
   attribute :url, Jeckle::Types::String
-  attribute :image_url, Jeckle::Types::String
+  attribute :score, Jeckle::Types::Float
 end
 ```
 
-### Fetching data
+Available types: `Jeckle::Types::Integer`, `String`, `Float`, `Bool`, `Array`, `Hash`, `DateTime`, `Time`, `Decimal`, `UUID`, `URI`, `SymbolizedHash`, `StringArray`, and any [dry-types](https://dry-rb.org/gems/dry-types/) type.
+
+## CRUD Operations
+
+### Find
+
+```ruby
+# GET /shots/1600459
+shot = Shot.find(1600459)
+shot.name #=> "Daryl Heckle And Jeckle Oates"
+```
+
+### List
 
-The resource class allows us to list shots through HTTP requests to the API, based on the provided information. For example, we can find a specific shot by providing its id to the `find` method:
+```ruby
+# GET /shots?name=avengers
+shots = Shot.list(name: 'avengers')
+```
+
+### Create
 
 ```ruby
-# GET http://api.dribbble.com/shots/1600459
-shot = Shot.find 1600459
+# POST /shots
+shot = Shot.create(name: 'New Shot', url: 'http://example.com')
 ```
 
-That will return a `Shot` instance, containing the shot info:
+### Update
 
 ```ruby
-shot.id
-=> 1600459
+# PATCH /shots/123
+shot = Shot.update(123, name: 'Updated Name')
+```
 
-shot.name
-=> "Daryl Heckle And Jeckle Oates"
+### Destroy
 
-shot.image_url
-=> "https://d13yacurqjgara.cloudfront.net/users/85699/screenshots/1600459/daryl_heckle_and_jeckle_oates-dribble.jpg"
+```ruby
+# DELETE /shots/123
+Shot.destroy(123) #=> true
 ```
 
-You can also look for many shots matching one or more attributes, by using the `list` method:
+### Instance-Level Operations
 
 ```ruby
-# GET http://api.dribbble.com/shots?name=avengers
-shots = Shot.list name: 'avengers'
+shot = Shot.find(123)
+updated = shot.save    # PATCH /shots/123
+fresh = shot.reload    # GET /shots/123
+shot.delete            # DELETE /shots/123
 ```
 
-### Attribute Aliasing
+## Composable Operations
 
-Sometimes you want to call the API's attributes something else, either because their names aren't very concise or because they're out of you app's convention. If that's the case, you can add an `as` option:
+By default, resources get all CRUD operations. For fine-grained control, extend individual modules:
 
 ```ruby
-attribute :thumbnailSize, Jeckle::Types::String, as: :thumbnail_size
+class ReadOnlyShot < Jeckle::Resource
+  api :dribbble
+  extend Jeckle::Operations::Find
+  extend Jeckle::Operations::List
+  # No Create, Update, or Delete
+end
 ```
 
-Both mapping will work:
+Available modules: `Jeckle::Operations::Find`, `List`, `Create`, `Update`, `Delete`.
+
+## Nested Resources
 
 ```ruby
-shot.thumbnailSize
-=> "50x50"
+class Comment < Jeckle::Resource
+  api :my_api
+  belongs_to :post
 
-shot.thumbnail_size
-=> "50x50"
+  attribute :id, Jeckle::Types::Integer
+  attribute :body, Jeckle::Types::String
+end
+
+Comment.find(456, post_id: 123)            # GET /posts/123/comments/456
+Comment.list(post_id: 123)                 # GET /posts/123/comments
+Comment.create(post_id: 123, body: 'Nice') # POST /posts/123/comments
 ```
 
-### Error Handling
+## Attribute Aliasing
 
-Jeckle provides a built-in Faraday middleware that automatically raises typed errors for HTTP error responses. Enable it in your API configuration:
+Map API attribute names to Ruby-friendly names:
 
 ```ruby
-Jeckle.configure do |config|
-  config.register :dribbble do |api|
-    api.base_uri = 'http://api.dribbble.com'
-    api.middlewares do
-      response :json
-      response :jeckle_raise_error
-    end
-  end
+class Shot < Jeckle::Resource
+  api :dribbble
+  attribute :thumbnailSize, Jeckle::Types::String, as: :thumbnail_size
+end
+
+shot.thumbnailSize  #=> "50x50"
+shot.thumbnail_size #=> "50x50"
+```
+
+## Error Handling
+
+Enable the error middleware to get typed exceptions:
+
+```ruby
+api.middlewares do
+  response :json
+  response :jeckle_raise_error
 end
 ```
 
-Then rescue specific errors in your code:
+Then rescue specific errors:
 
 ```ruby
 begin
-  Shot.find 999
+  Shot.find(999)
 rescue Jeckle::NotFoundError => e
   puts "Not found: #{e.message} (status: #{e.status})"
+  puts "Request ID: #{e.request_id}" if e.request_id
+rescue Jeckle::TooManyRequestsError => e
+  puts "Rate limited! Remaining: #{e.rate_limit&.remaining}"
 rescue Jeckle::ClientError => e
   puts "Client error: #{e.status}"
 rescue Jeckle::ServerError => e
   puts "Server error: #{e.status}"
-rescue Jeckle::HTTPError => e
-  puts "HTTP error: #{e.status}"
 end
 ```
 
-The error hierarchy:
+Error hierarchy:
 
-- `Jeckle::Error` — base error
-  - `Jeckle::ConnectionError` — network connectivity errors
-  - `Jeckle::TimeoutError` — request timeout errors
-  - `Jeckle::HTTPError` — HTTP errors (has `status` and `body` attributes)
-    - `Jeckle::ClientError` — 4xx errors
+- `Jeckle::Error` -- base error
+  - `Jeckle::ConnectionError` -- network errors
+  - `Jeckle::TimeoutError` -- timeout errors
+  - `Jeckle::HTTPError` -- HTTP errors (`status`, `body`, `request_id`)
+    - `Jeckle::ClientError` -- 4xx
       - `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `TooManyRequestsError` (429)
-    - `Jeckle::ServerError` — 5xx errors
+    - `Jeckle::ServerError` -- 5xx
       - `InternalServerError` (500), `ServiceUnavailableError` (503)
 
-We're all set! Now we can expand the mapping of our API, e.g to add ability to search Dribbble Designer directory by adding Designer class, or we can expand the original mapping of Shot class to include more attributes, such as tags or comments.
+## Pagination
+
+### Offset-Based (Default)
+
+```ruby
+Shot.list_each(per_page: 10).each do |shot|
+  puts shot.name
+end
+
+# Works with Enumerable methods
+Shot.list_each(per_page: 50).first(5)
+```
+
+### Cursor-Based
+
+```ruby
+config.register :stripe do |api|
+  api.base_uri = 'https://api.stripe.com/v1'
+  api.pagination :cursor, cursor_param: :starting_after, limit_param: :limit
+end
+```
+
+### Link Header (GitHub-Style)
+
+```ruby
+config.register :github do |api|
+  api.base_uri = 'https://api.github.com'
+  api.pagination :link_header, per_page_param: :per_page
+end
+```
+
+## Instance-Based Client
+
+Use `Jeckle::Client` for requests with different credentials:
+
+```ruby
+client = Jeckle::Client.new(:my_api, bearer_token: 'other-token')
+client.find(Shot, 123)
+client.list(Shot, name: 'avengers')
+client.create(Shot, name: 'New Shot')
+```
+
+## Response Inspection
+
+Access the raw HTTP response after API calls:
+
+```ruby
+shot = Shot.find(123)
+shot._response.status  #=> 200
+shot._response.headers #=> { 'X-Request-Id' => '...' }
+```
+
+## Observability
+
+### Instrumentation
+
+Enable `ActiveSupport::Notifications` events:
+
+```ruby
+api.middlewares do
+  request :jeckle_instrumentation
+end
+
+ActiveSupport::Notifications.subscribe('request.jeckle') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  puts "#{event.payload[:method]} #{event.payload[:url]} => #{event.payload[:status]}"
+end
+```
+
+### Log Redaction
+
+Redact sensitive headers in log output:
+
+```ruby
+redactor = Jeckle::Middleware::LogRedactor.new(
+  headers: %w[Authorization X-Api-Key],
+  patterns: [/password/i]
+)
+safe_headers = redactor.redact_headers(response.headers)
+```
+
+## Testing
+
+Use test mode to stub HTTP requests without real network calls:
+
+```ruby
+# In your test setup
+Jeckle.test_mode!
+
+Jeckle.stub_request(:my_api, :get, 'shots/1', body: { id: 1, name: 'Test' })
+
+shot = Shot.find(1) #=> uses stubbed response
+
+# Cleanup
+Jeckle.reset_test_stubs!
+```
+
+## Credential Providers
+
+Chain multiple credential sources (AWS SDK pattern):
+
+```ruby
+chain = Jeckle::Auth::CredentialChain.new(
+  -> { ENV['MY_API_TOKEN'] },
+  -> { File.read(File.expand_path('~/.my_api/token')).strip rescue nil },
+  -> { 'fallback-token' }
+)
+api.bearer_token = chain.resolve
+```
 
 ## Migration from 0.4.x
 
@@ -167,7 +423,7 @@ class Shot
   attribute :id, Integer
 end
 
-# After (0.6.0+)
+# After (1.0.0)
 class Shot < Jeckle::Resource
   attribute :id, Jeckle::Types::Integer
 end

data/lib/jeckle/api.rb

@@ -1,11 +1,39 @@
 # frozen_string_literal: true
 
 module Jeckle
+  # Holds configuration for a single API endpoint including base URI,
+  # authentication, headers, params, timeouts, and Faraday middlewares.
   class API
+    # @return [Logger, nil] logger for request/response logging
     attr_accessor :logger
+
+    # @!attribute [w] base_uri
+    #   @param value [String] the base URL for the API
+    # @!attribute [w] namespaces
+    #   @param value [Hash] URL path segments appended to base_uri
+    # @!attribute [w] params
+    #   @param value [Hash] default query parameters for all requests
+    # @!attribute [w] headers
+    #   @param value [Hash] default headers for all requests
+    # @!attribute [w] open_timeout
+    #   @param value [Integer] connection open timeout in seconds
+    # @!attribute [w] read_timeout
+    #   @param value [Integer] read timeout in seconds
     attr_writer :base_uri, :namespaces, :params, :headers, :open_timeout, :read_timeout
-    attr_reader :basic_auth, :request_timeout
 
+    # @return [Hash, nil] basic auth credentials
+    # @return [Integer, nil] request timeout
+    # @return [String, nil] bearer token for Authorization header
+    # @return [Hash, nil] API key configuration
+    # @return [Hash, nil] retry configuration for faraday-retry
+    # @return [#paginate, #next_context, nil] pagination strategy for collections
+    # @return [Jeckle::Auth::OAuth2, nil] OAuth 2.0 configuration
+    attr_reader :basic_auth, :request_timeout, :bearer_token, :api_key, :retry_options,
+                :pagination_strategy, :oauth2
+
+    # Returns or builds a configured Faraday connection.
+    #
+    # @return [Faraday::Connection]
     def connection
       @connection ||= Faraday.new(url: base_uri, request: timeout).tap do |conn|
         conn.headers = headers
@@ -13,10 +41,28 @@ module Jeckle
         conn.response :logger, logger
 
         conn.request :authorization, :basic, basic_auth[:username], basic_auth[:password] if basic_auth
+        conn.request :authorization, :Bearer, bearer_token if bearer_token
+        conn.request :authorization, :Bearer, -> { oauth2.token } if oauth2
+        conn.request :retry, retry_options if retry_options
+
+        if api_key
+          if api_key[:header]
+            conn.headers[api_key[:header]] = api_key[:value]
+          elsif api_key[:param]
+            conn.params[api_key[:param]] = api_key[:value]
+          end
+        end
+
         conn.instance_exec(&@middlewares_block) if @middlewares_block
+        @connection_customizer&.call(conn)
       end
     end
 
+    # Set basic authentication credentials.
+    #
+    # @param credential_params [Hash] must contain :username and :password
+    # @raise [Jeckle::NoUsernameOrPasswordError] if keys are missing
+    # @return [Hash]
     def basic_auth=(credential_params)
       %i[username password].all? do |key|
         credential_params.key? key
@@ -25,28 +71,161 @@ module Jeckle
       @basic_auth = credential_params
     end
 
+    # Set bearer token authentication. Resets cached connection.
+    #
+    # @param token [String] the bearer token
+    # @return [String]
+    def bearer_token=(token)
+      @connection = nil
+      @bearer_token = token
+    end
+
+    # Configure automatic retries using faraday-retry. Resets cached connection.
+    #
+    # @param options [Hash] retry options passed to Faraday::Retry::Middleware
+    # @option options [Integer] :max (2) maximum number of retries
+    # @option options [Float] :interval (0.5) initial interval between retries in seconds
+    # @option options [Float] :interval_randomness (0.5) randomness factor for retry interval
+    # @option options [Integer] :backoff_factor (2) exponential backoff multiplier
+    # @option options [Array<Integer>] :retry_statuses ([429, 500, 502, 503]) HTTP status codes to retry
+    # @return [Hash]
+    #
+    # @example
+    #   api.retry = { max: 3, interval: 1, retry_statuses: [429, 503] }
+    def retry=(options)
+      @connection = nil
+      @retry_options = DEFAULT_RETRY_OPTIONS.merge(options)
+    end
+
+    # Default retry configuration.
+    DEFAULT_RETRY_OPTIONS = {
+      max: 2,
+      interval: 0.5,
+      interval_randomness: 0.5,
+      backoff_factor: 2,
+      retry_statuses: [429, 500, 502, 503]
+    }.freeze
+
+    # Set API key authentication. Resets cached connection.
+    #
+    # @param config [Hash] must contain :value and either :header or :param
+    # @raise [Jeckle::ArgumentError] if config is invalid
+    # @return [Hash]
+    #
+    # @example Header-based API key
+    #   api.api_key = { value: 'secret', header: 'X-Api-Key' }
+    #
+    # @example Query param-based API key
+    #   api.api_key = { value: 'secret', param: 'api_key' }
+    def api_key=(config)
+      unless config.is_a?(Hash) && config[:value] && (config[:header] || config[:param])
+        raise Jeckle::ArgumentError, 'api_key requires :value and either :header or :param'
+      end
+
+      @connection = nil
+      @api_key = config
+    end
+
+    # Returns the full base URI including namespace segments.
+    #
+    # @return [String]
     def base_uri
       [@base_uri, *namespaces.values].join '/'
     end
 
+    # @return [Hash] default query parameters
     def params
       @params || {}
     end
 
+    # @return [Hash] default headers
     def headers
       @headers || {}
     end
 
+    # @return [Hash] URL namespace segments
     def namespaces
       @namespaces || {}
     end
 
+    # Set OAuth 2.0 client credentials authentication. Resets cached connection.
+    # The token is fetched lazily on the first request.
+    #
+    # @param config [Hash] OAuth 2.0 configuration
+    # @option config [String] :client_id OAuth client ID
+    # @option config [String] :client_secret OAuth client secret
+    # @option config [String] :token_url token endpoint URL
+    # @option config [String] :scope (nil) requested scope
+    # @return [Jeckle::Auth::OAuth2]
+    #
+    # @example
+    #   api.oauth2 = {
+    #     client_id: 'id', client_secret: 'secret',
+    #     token_url: 'https://auth.example.com/oauth/token'
+    #   }
+    def oauth2=(config)
+      @connection = nil
+      @oauth2 = Jeckle::Auth::OAuth2.new(**config)
+    end
+
+    # Configure the pagination strategy for this API.
+    #
+    # @param strategy [Symbol, #paginate] :offset, :cursor, :link_header, or a strategy instance
+    # @param options [Hash] options passed to the built-in strategy constructor
+    # @return [#paginate, #next_context]
+    #
+    # @example Cursor-based pagination (Stripe-style)
+    #   api.pagination :cursor, cursor_param: :starting_after, limit_param: :limit
+    #
+    # @example Link header pagination (GitHub-style)
+    #   api.pagination :link_header
+    #
+    # @example Custom strategy instance
+    #   api.pagination MyCustomStrategy.new
+    def pagination(strategy, **options)
+      @pagination_strategy = case strategy
+                             when :offset then Jeckle::Pagination::Offset.new(**options)
+                             when :cursor then Jeckle::Pagination::Cursor.new(**options)
+                             when :link_header then Jeckle::Pagination::LinkHeader.new(**options)
+                             else strategy
+                             end
+    end
+
+    # Configure Faraday middlewares for this API.
+    #
+    # @yield block evaluated in the context of the Faraday connection builder
+    # @raise [Jeckle::ArgumentError] if no block is given
+    #
+    # @example
+    #   api.middlewares do
+    #     request :json
+    #     response :json
+    #     response :jeckle_raise_error
+    #   end
     def middlewares(&block)
       raise Jeckle::ArgumentError, 'A block is required when configuring API middlewares' unless block_given?
 
       @middlewares_block = block
     end
 
+    # Customize the Faraday connection after Jeckle's defaults are applied.
+    # The block receives the Faraday connection and can add middleware,
+    # override the adapter, etc.
+    #
+    # @yield [Faraday::Connection] the connection after default setup
+    #
+    # @example
+    #   api.configure_connection do |conn|
+    #     conn.use MyCustomMiddleware
+    #     conn.adapter :typhoeus
+    #   end
+    def configure_connection(&block)
+      @connection_customizer = block
+    end
+
+    # Returns timeout configuration hash for Faraday.
+    #
+    # @return [Hash]
     def timeout
       {}.tap do |t|
         t[:open_timeout] = @open_timeout if @open_timeout