petstore_api_client 0.1.0

data/lib/petstore_api_client/clients/pet_client.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "concerns/resource_operations"
+require_relative "concerns/pagination"
+
+module PetstoreApiClient
+  module Clients
+    # Client for Pet-related API endpoints
+    # Handles creation, retrieval, updating, and deletion of pets
+    #
+    # Refactored to use ResourceOperations concern (Template Method pattern)
+    # which eliminates ~50 lines of duplication with StoreClient
+    class PetClient < Client
+      include Concerns::ResourceOperations
+      include Concerns::Pagination
+
+      # Public API methods - delegate to generic resource operations
+      alias create_pet create_resource
+      alias update_pet update_resource
+      alias get_pet get_resource
+      alias delete_pet delete_resource
+
+      # Find pets by status with optional pagination
+      #
+      # @param status [String, Array<String>] Status value(s) to filter by
+      #   Valid values: "available", "pending", "sold"
+      # @param options [Hash] Optional pagination and filter options
+      # @option options [Integer] :page Page number (default: 1)
+      # @option options [Integer] :per_page Items per page (default: 25)
+      # @option options [Integer] :offset Alternative: offset for results
+      # @option options [Integer] :limit Alternative: limit for results
+      # @return [PaginatedCollection<Pet>] Paginated collection of pets
+      #
+      # @example
+      #   # Get first page of available pets
+      #   pets = client.pets.find_by_status("available")
+      #
+      #   # Get second page with custom page size
+      #   pets = client.pets.find_by_status("available", page: 2, per_page: 50)
+      #
+      #   # Search multiple statuses
+      #   pets = client.pets.find_by_status(["available", "pending"])
+      def find_by_status(status, options = {})
+        # Validate status values
+        statuses = Array(status)
+        validate_statuses!(statuses)
+
+        # Make API request (returns all matching pets)
+        params = { status: statuses.join(",") }
+        resp = get("pet/findByStatus", params: params)
+
+        # Parse response into Pet objects
+        pets = Array(resp.body).map { |pet_data| Models::Pet.from_response(pet_data) }
+
+        # Apply client-side pagination (API doesn't support server-side pagination)
+        apply_client_side_pagination(pets, options)
+      end
+
+      # Find pets by tags with optional pagination
+      #
+      # @param tags [String, Array<String>] Tag value(s) to filter by
+      # @param options [Hash] Optional pagination options
+      # @option options [Integer] :page Page number (default: 1)
+      # @option options [Integer] :per_page Items per page (default: 25)
+      # @return [PaginatedCollection<Pet>] Paginated collection of pets
+      #
+      # @example
+      #   # Find pets with specific tag
+      #   pets = client.pets.find_by_tags("friendly")
+      #
+      #   # Find pets with multiple tags
+      #   pets = client.pets.find_by_tags(["friendly", "vaccinated"], page: 1, per_page: 10)
+      def find_by_tags(tags, options = {})
+        # Ensure tags is an array
+        tag_array = Array(tags)
+        raise ValidationError, "Tags cannot be empty" if tag_array.empty?
+
+        # Make API request
+        params = { tags: tag_array.join(",") }
+        resp = get("pet/findByTags", params: params)
+
+        # Parse response into Pet objects
+        pets = Array(resp.body).map { |pet_data| Models::Pet.from_response(pet_data) }
+
+        # Apply client-side pagination
+        apply_client_side_pagination(pets, options)
+      end
+
+      private
+
+      # Template method implementation: Define the model class
+      def model_class
+        Models::Pet
+      end
+
+      # Template method implementation: Define the resource name for API paths
+      def resource_name
+        "pet"
+      end
+
+      # Template method implementation: Human-readable name for validation errors
+      def id_field_name
+        "Pet ID"
+      end
+
+      # Validate status values against allowed values
+      def validate_statuses!(statuses)
+        # Performance optimization: use constant instead of creating new array
+        invalid = statuses.reject { |s| Models::Pet::VALID_STATUSES.include?(s.to_s) }
+
+        return if invalid.empty?
+
+        raise ValidationError,
+              "Invalid status value(s): #{invalid.join(", ")}. " \
+              "Must be one of: #{Models::Pet::VALID_STATUSES.join(", ")}"
+      end
+    end
+  end
+end

data/lib/petstore_api_client/clients/store_client.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "concerns/resource_operations"
+
+module PetstoreApiClient
+  module Clients
+    # Store client - handles order operations
+    #
+    # Refactored to use ResourceOperations concern (Template Method pattern)
+    # which eliminates ~40 lines of duplication with PetClient
+    class StoreClient < Client
+      include Concerns::ResourceOperations
+
+      # Public API methods - delegate to generic resource operations
+      alias create_order create_resource
+      alias get_order get_resource
+      alias delete_order delete_resource
+
+      private
+
+      # Template method implementation: Define the model class
+      def model_class
+        Models::Order
+      end
+
+      # Template method implementation: Define the resource name for API paths
+      def resource_name
+        "store/order"
+      end
+
+      # Template method implementation: Human-readable name for validation errors
+      def id_field_name
+        "Order ID"
+      end
+    end
+  end
+end

data/lib/petstore_api_client/configuration.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require_relative "authentication/api_key"
+require_relative "authentication/oauth2"
+require_relative "authentication/composite"
+require_relative "authentication/none"
+
+module PetstoreApiClient
+  # Configuration management for Petstore API client
+  #
+  # Centralized configuration for all client settings including authentication,
+  # timeouts, retries, and pagination. Supports multiple authentication strategies
+  # via feature flags.
+  #
+  # @example Basic configuration
+  #   config = Configuration.new
+  #   config.api_key = "special-key"
+  #   config.timeout = 60
+  #
+  # @example Block-based configuration
+  #   config = Configuration.new
+  #   config.configure do |c|
+  #     c.auth_strategy = :oauth2
+  #     c.oauth2_client_id = "my-id"
+  #     c.oauth2_client_secret = "my-secret"
+  #   end
+  #
+  # @since 0.1.0
+  # rubocop:disable Metrics/ClassLength
+  class Configuration
+    # Default API base URL for Petstore API
+    DEFAULT_BASE_URL = "https://petstore.swagger.io/v2"
+
+    # Default number of items per page for paginated endpoints
+    DEFAULT_PAGE_SIZE = 25
+
+    # Maximum allowed page size to prevent abuse
+    MAX_PAGE_SIZE = 100
+
+    # Valid authentication strategy options
+    VALID_AUTH_STRATEGIES = %i[none api_key oauth2 both].freeze
+
+    # @!attribute [rw] base_url
+    #   @return [String] Base URL for API endpoints
+    # @!attribute [rw] timeout
+    #   @return [Integer] Request timeout in seconds
+    # @!attribute [rw] open_timeout
+    #   @return [Integer] Connection open timeout in seconds
+    # @!attribute [rw] retry_enabled
+    #   @return [Boolean] Enable automatic retry for transient failures
+    # @!attribute [rw] max_retries
+    #   @return [Integer] Maximum number of retry attempts
+    # @!attribute [rw] default_page_size
+    #   @return [Integer] Default items per page for pagination
+    # @!attribute [rw] max_page_size
+    #   @return [Integer] Maximum items per page for pagination
+    attr_accessor :base_url, :timeout, :open_timeout, :retry_enabled, :max_retries,
+                  :default_page_size, :max_page_size
+
+    # @!attribute [r] api_key
+    #   @return [String, nil] API key for authentication (read-only, use setter)
+    attr_reader :api_key
+
+    # @!attribute [rw] auth_strategy
+    #   @return [Symbol] Authentication strategy (:none, :api_key, :oauth2, :both)
+    attr_accessor :auth_strategy
+
+    # @!attribute [rw] oauth2_client_id
+    #   @return [String, nil] OAuth2 client ID
+    # @!attribute [rw] oauth2_client_secret
+    #   @return [String, nil] OAuth2 client secret
+    # @!attribute [rw] oauth2_token_url
+    #   @return [String, nil] OAuth2 token endpoint URL
+    # @!attribute [rw] oauth2_scope
+    #   @return [String, nil] OAuth2 scope (space-separated permissions)
+    attr_accessor :oauth2_client_id, :oauth2_client_secret, :oauth2_token_url, :oauth2_scope
+
+    # Initialize configuration with default values
+    #
+    # Sets sensible defaults for all configuration options:
+    # - base_url: Petstore API endpoint
+    # - timeout: 30 seconds
+    # - retry_enabled: true
+    # - auth_strategy: :api_key (backward compatible)
+    #
+    # @example
+    #   config = Configuration.new
+    #   config.base_url # => "https://petstore.swagger.io/v2"
+    #   config.timeout # => 30
+    #
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @api_key = nil
+      @timeout = 30 # seconds
+      @open_timeout = 10 # seconds
+      @retry_enabled = true # Auto-retry transient failures
+      @max_retries = 2 # Number of retries for failed requests
+      @default_page_size = DEFAULT_PAGE_SIZE # Default items per page for pagination
+      @max_page_size = MAX_PAGE_SIZE # Maximum items per page (prevents abuse)
+      @auth_strategy = :api_key # Default strategy for backward compatibility
+
+      # OAuth2 credentials
+      @oauth2_client_id = nil
+      @oauth2_client_secret = nil
+      @oauth2_token_url = nil
+      @oauth2_scope = nil
+    end
+
+    # Set API key for authentication
+    #
+    # Supports loading from environment variable using :from_env symbol.
+    #
+    # @param value [String, Symbol, nil] The API key or :from_env
+    #
+    # @example Direct setting
+    #   config.api_key = "special-key"
+    #
+    # @example From environment variable
+    #   ENV['PETSTORE_API_KEY'] = "special-key"
+    #   config.api_key = :from_env
+    #
+    def api_key=(value)
+      @api_key = if value == :from_env
+                   ENV.fetch(Authentication::ApiKey::ENV_VAR_NAME, nil)
+                 else
+                   value
+                 end
+    end
+
+    # Build authenticator instance based on auth_strategy
+    #
+    # Returns appropriate authentication strategy based on auth_strategy setting:
+    # - :none - No authentication
+    # - :api_key - API Key authentication only
+    # - :oauth2 - OAuth2 authentication only
+    # - :both - Both API Key AND OAuth2 (composite)
+    #
+    # The authenticator is memoized and reused until reset_authenticator! is called.
+    #
+    # @return [Authentication::Base] Authentication strategy instance
+    #
+    # @raise [ConfigurationError] if auth_strategy is invalid
+    #
+    # @example
+    #   config.auth_strategy = :oauth2
+    #   config.authenticator # => #<OAuth2 client_id=...>
+    #
+    def authenticator
+      @authenticator ||= build_authenticator
+    end
+
+    # Reset memoized authenticator
+    #
+    # Call this when configuration changes to rebuild the authenticator
+    # with new settings.
+    #
+    # @return [void]
+    #
+    # @example
+    #   config.auth_strategy = :api_key
+    #   config.authenticator # => ApiKey instance
+    #   config.auth_strategy = :oauth2
+    #   config.reset_authenticator!
+    #   config.authenticator # => OAuth2 instance
+    #
+    def reset_authenticator!
+      @authenticator = nil
+    end
+
+    # Configure settings via block
+    #
+    # Yields self to the block for convenient configuration.
+    # Automatically resets authenticator after configuration.
+    #
+    # @yieldparam [Configuration] self
+    # @return [Configuration] self for method chaining
+    #
+    # @example
+    #   config.configure do |c|
+    #     c.api_key = "special-key"
+    #     c.timeout = 60
+    #     c.retry_enabled = false
+    #   end
+    #
+    def configure
+      yield(self) if block_given?
+      reset_authenticator! # Rebuild authenticator when config changes
+      self
+    end
+
+    # Validate configuration settings
+    #
+    # Checks that all required configuration is valid.
+    # Currently validates:
+    # - base_url is present
+    # - authenticator is properly configured (if auth is enabled)
+    #
+    # @return [Boolean] true if valid
+    # @raise [ValidationError] if configuration is invalid
+    #
+    # @example
+    #   config = Configuration.new
+    #   config.validate! # => true
+    #
+    #   config.base_url = nil
+    #   config.validate! # raises ValidationError
+    #
+    def validate!
+      raise ValidationError, "base_url can't be nil" if base_url.nil? || base_url.empty?
+
+      # Validate authenticator if configured
+      authenticator.is_a?(Authentication::ApiKey) && authenticator.configured?
+
+      true
+    end
+
+    private
+
+    # Build authentication strategy based on auth_strategy setting
+    #
+    # @return [Authentication::Base] Authentication strategy instance
+    # @raise [ConfigurationError] if auth_strategy is invalid
+    #
+    def build_authenticator
+      case @auth_strategy
+      when :none
+        build_none_authenticator
+      when :api_key
+        build_api_key_authenticator
+      when :oauth2
+        build_oauth2_authenticator
+      when :both
+        build_composite_authenticator
+      else
+        raise ConfigurationError,
+              "Invalid auth_strategy: #{@auth_strategy.inspect}. " \
+              "Must be one of: #{VALID_AUTH_STRATEGIES.map(&:inspect).join(", ")}"
+      end
+    end
+
+    # Build None authenticator (no authentication)
+    #
+    # @return [Authentication::None]
+    #
+    def build_none_authenticator
+      Authentication::None.new
+    end
+
+    # Build API Key authenticator
+    #
+    # Returns None authenticator if api_key is not configured.
+    #
+    # @return [Authentication::ApiKey, Authentication::None]
+    #
+    def build_api_key_authenticator
+      if api_key.nil? || api_key.to_s.strip.empty?
+        Authentication::None.new
+      else
+        Authentication::ApiKey.new(api_key)
+      end
+    end
+
+    # Build OAuth2 authenticator
+    #
+    # Returns None authenticator if OAuth2 credentials are not configured.
+    #
+    # @return [Authentication::OAuth2, Authentication::None]
+    #
+    def build_oauth2_authenticator
+      if oauth2_configured?
+        Authentication::OAuth2.new(
+          client_id: @oauth2_client_id,
+          client_secret: @oauth2_client_secret,
+          token_url: @oauth2_token_url || Authentication::OAuth2::DEFAULT_TOKEN_URL,
+          scope: @oauth2_scope
+        )
+      else
+        Authentication::None.new
+      end
+    end
+
+    # Build Composite authenticator (both API Key and OAuth2)
+    #
+    # Creates a composite that applies both authentication methods simultaneously.
+    # Only includes strategies that are actually configured.
+    #
+    # @return [Authentication::Composite]
+    #
+    def build_composite_authenticator
+      strategies = []
+
+      # Add API Key if configured
+      strategies << Authentication::ApiKey.new(api_key) unless api_key.nil? || api_key.to_s.strip.empty?
+
+      # Add OAuth2 if configured
+      if oauth2_configured?
+        strategies << Authentication::OAuth2.new(
+          client_id: @oauth2_client_id,
+          client_secret: @oauth2_client_secret,
+          token_url: @oauth2_token_url || Authentication::OAuth2::DEFAULT_TOKEN_URL,
+          scope: @oauth2_scope
+        )
+      end
+
+      Authentication::Composite.new(strategies)
+    end
+
+    # Check if OAuth2 credentials are configured
+    #
+    # @return [Boolean] true if client_id and client_secret are present
+    #
+    def oauth2_configured?
+      !@oauth2_client_id.nil? && !@oauth2_client_id.to_s.strip.empty? &&
+        !@oauth2_client_secret.nil? && !@oauth2_client_secret.to_s.strip.empty?
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/petstore_api_client/connection.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require_relative "middleware/authentication"
+
+module PetstoreApiClient
+  # Connection setup for HTTP requests
+  # Tried HTTParty first but Faraday's middleware is cleaner for this use case
+  module Connection
+    private
+
+    # Creates and memoizes a Faraday connection (reuses same connection for better performance)
+    def connection
+      @connection ||= Faraday.new(url: configuration.base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+
+        # Add authentication middleware (Strategy pattern + Interceptor pattern)
+        # This uses the authentication strategy from configuration
+        conn.use Middleware::Authentication, authenticator: configuration.authenticator
+
+        # Add retry middleware for transient failures (finally got around to implementing this!)
+        setup_retry_middleware(conn) if configuration.retry_enabled
+
+        # Standard headers for JSON API
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+
+        # Timeouts to prevent hanging requests
+        conn.options.timeout = configuration.timeout
+        conn.options.open_timeout = configuration.open_timeout
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Configure retry middleware with sensible defaults
+    def setup_retry_middleware(conn)
+      conn.request :retry,
+                   max: configuration.max_retries,
+                   interval: 0.5,
+                   interval_randomness: 0.5,
+                   backoff_factor: 2,
+                   retry_statuses: [429, 500, 502, 503, 504], # Retry on these HTTP codes
+                   methods: %i[get post put delete], # Retry all methods
+                   exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
+    end
+
+    # Reset connection when config changes
+    def reset_connection!
+      @connection = nil
+    end
+  end
+end

data/lib/petstore_api_client/errors.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  # Base error class - all our exceptions inherit from this
+  class Error < StandardError
+    attr_reader :status_code, :error_type
+
+    def initialize(message = nil, status_code: nil, error_type: nil)
+      @status_code = status_code
+      @error_type = error_type
+      super(message)
+    end
+  end
+
+  # Validation errors - thrown before we even hit the API
+  class ValidationError < Error; end
+
+  # Configuration errors - thrown when configuration is invalid
+  # @since 0.2.0
+  class ConfigurationError < Error; end
+
+  # Authentication errors - thrown when authentication fails
+  # @since 0.2.0
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super(message, status_code: 401, error_type: "Authentication")
+    end
+  end
+
+  # 404 errors
+  class NotFoundError < Error
+    def initialize(message = "Resource not found")
+      super(message, status_code: 404, error_type: "NotFound")
+    end
+  end
+
+  # 405 or 400 errors for bad input
+  class InvalidInputError < Error
+    def initialize(message = "Invalid input provided")
+      super(message, status_code: 405, error_type: "InvalidInput")
+    end
+  end
+
+  # 400 errors specific to orders
+  class InvalidOrderError < Error
+    def initialize(message = "Invalid order supplied")
+      super(message, status_code: 400, error_type: "InvalidOrder")
+    end
+  end
+
+  # Network/connection issues
+  class ConnectionError < Error
+    def initialize(message = "Failed to connect to the API")
+      super(message, status_code: nil, error_type: "Connection")
+    end
+  end
+
+  # Rate limiting errors - too many requests
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil)
+      @retry_after = retry_after
+      super(message, status_code: 429, error_type: "RateLimit")
+    end
+  end
+
+  # Catch-all for other API errors
+  class ApiError < Error; end
+end

data/lib/petstore_api_client/middleware/authentication.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Middleware
+    # Faraday middleware for authentication
+    # Applies authentication strategy to each request
+    #
+    # This middleware follows the Interceptor pattern - it intercepts
+    # outgoing requests and adds authentication headers before they're sent
+    #
+    # This is the same pattern used by industry-standard gems:
+    # - Octokit (GitHub API)
+    # - Slack-ruby-client
+    # - Stripe Ruby
+    #
+    # @example
+    #   # In Faraday connection setup
+    #   conn.use PetstoreApiClient::Middleware::Authentication,
+    #            authenticator: ApiKey.new("special-key")
+    class Authentication < Faraday::Middleware
+      # Initialize middleware with authentication strategy
+      #
+      # @param app [#call] The next middleware in the stack
+      # @param options [Hash] Middleware options
+      # @option options [Authentication::Base] :authenticator The auth strategy
+      def initialize(app, options = {})
+        super(app)
+        @authenticator = options[:authenticator]
+      end
+
+      # Process request - apply authentication before sending
+      #
+      # @param env [Faraday::Env] The request environment
+      # @return [Faraday::Response] The response from the next middleware
+      def call(env)
+        # Apply authentication if configured
+        @authenticator&.apply(env) if @authenticator&.configured?
+
+        # Continue to next middleware
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/petstore_api_client/models/api_response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Models
+    # ApiResponse model for structured error responses
+    # Not used much since we raise exceptions instead of returning error objects
+    class ApiResponse < Base
+      attribute :code, :integer
+      attribute :type, :string
+      attribute :message, :string
+
+      def to_h
+        {
+          code: code,
+          type: type,
+          message: message
+        }.compact
+      end
+
+      def self.from_response(data)
+        return nil if data.nil?
+
+        new(
+          code: data["code"] || data[:code],
+          type: data["type"] || data[:type],
+          message: data["message"] || data[:message]
+        )
+      end
+    end
+  end
+end