petstore_api_client 0.1.0

data/lib/petstore_api_client/request.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  # HTTP request methods for the Petstore API client
+  #
+  # Provides high-level abstraction over HTTP operations using Faraday.
+  # This module implements the Dependency Inversion Principle by abstracting
+  # HTTP operations behind a clean interface.
+  #
+  # All HTTP methods return a Response object that wraps the Faraday response.
+  # Errors are automatically detected and raised as appropriate exception types.
+  #
+  # This module is included by Client and provides:
+  # - GET requests for retrieving resources
+  # - POST requests for creating resources
+  # - PUT requests for updating resources
+  # - DELETE requests for removing resources
+  #
+  # @example Making a GET request
+  #   client = Client.new
+  #   response = client.get("/pet/123")
+  #   pet = response.body
+  #
+  # @example Making a POST request with body
+  #   response = client.post("/pet", body: { name: "Fluffy", status: "available" })
+  #
+  # @see Connection
+  # @see Response
+  # @since 0.1.0
+  module Request
+    # Perform HTTP GET request
+    #
+    # Retrieves a resource from the API. Query parameters can be provided
+    # via the params hash.
+    #
+    # @param path [String] The API endpoint path (e.g., "/pet/123")
+    # @param params [Hash] Optional query parameters
+    #
+    # @return [Response] Wrapped HTTP response
+    #
+    # @raise [NotFoundError] if resource not found (404)
+    # @raise [InvalidInputError] if request is invalid (400, 405)
+    # @raise [RateLimitError] if rate limit exceeded (429)
+    # @raise [ConnectionError] if connection fails or times out
+    # @raise [ApiError] for other API errors
+    #
+    # @example Get a pet by ID
+    #   response = client.get("/pet/123")
+    #   pet = response.body
+    #
+    # @example Get pets with query parameters
+    #   response = client.get("/pet/findByStatus", params: { status: "available" })
+    #   pets = response.body
+    #
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    # Perform HTTP POST request
+    #
+    # Creates a new resource on the API. The request body should contain
+    # the resource data as a hash, which will be automatically serialized to JSON.
+    #
+    # @param path [String] The API endpoint path
+    # @param body [Hash] Request body data
+    #
+    # @return [Response] Wrapped HTTP response
+    #
+    # @raise [InvalidInputError] if request body is invalid
+    # @raise [ValidationError] if data fails validation
+    # @raise [RateLimitError] if rate limit exceeded
+    # @raise [ConnectionError] if connection fails or times out
+    # @raise [ApiError] for other API errors
+    #
+    # @example Create a new pet
+    #   response = client.post("/pet", body: {
+    #     name: "Fluffy",
+    #     status: "available",
+    #     category: { id: 1, name: "Dogs" }
+    #   })
+    #
+    def post(path, body: {})
+      request(:post, path, body: body)
+    end
+
+    # Perform HTTP PUT request
+    #
+    # Updates an existing resource on the API. The request body should contain
+    # the updated resource data as a hash.
+    #
+    # @param path [String] The API endpoint path
+    # @param body [Hash] Request body data with updates
+    #
+    # @return [Response] Wrapped HTTP response
+    #
+    # @raise [NotFoundError] if resource not found (404)
+    # @raise [InvalidInputError] if request body is invalid
+    # @raise [ValidationError] if data fails validation
+    # @raise [ConnectionError] if connection fails or times out
+    # @raise [ApiError] for other API errors
+    #
+    # @example Update an existing pet
+    #   response = client.put("/pet", body: {
+    #     id: 123,
+    #     name: "Fluffy Updated",
+    #     status: "sold"
+    #   })
+    #
+    def put(path, body: {})
+      request(:put, path, body: body)
+    end
+
+    # Perform HTTP DELETE request
+    #
+    # Deletes a resource from the API. Query parameters can be provided
+    # via the params hash if needed.
+    #
+    # @param path [String] The API endpoint path
+    # @param params [Hash] Optional query parameters
+    #
+    # @return [Response] Wrapped HTTP response
+    #
+    # @raise [NotFoundError] if resource not found (404)
+    # @raise [InvalidInputError] if request is invalid
+    # @raise [ConnectionError] if connection fails or times out
+    # @raise [ApiError] for other API errors
+    #
+    # @example Delete a pet
+    #   response = client.delete("/pet/123")
+    #
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    private
+
+    # Core request method that handles all HTTP operations
+    #
+    # This is the central method that all public HTTP methods (get, post, put, delete)
+    # delegate to. It handles:
+    # - Executing the HTTP request via Faraday
+    # - Wrapping the response in a Response object
+    # - Error detection and exception raising
+    # - Connection error handling
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters for GET/DELETE requests
+    # @param body [Hash] Request body for POST/PUT requests
+    #
+    # @return [Response] Wrapped HTTP response
+    #
+    # @raise [ConnectionError] if connection fails or times out
+    # @raise [ApiError] for unexpected errors
+    # @raise [NotFoundError, InvalidInputError, RateLimitError, etc.] for API errors
+    #
+    # @api private
+    def request(method, path, params: {}, body: {})
+      # puts "DEBUG: #{method.upcase} #{path}" if ENV['DEBUG']
+      resp = connection.public_send(method) do |req|
+        req.url path
+        req.params = params if params.any?
+        req.body = body if body.any?
+      end
+
+      wrapped_resp = Response.new(resp)
+      handle_error_response(wrapped_resp) if wrapped_resp.error?
+
+      wrapped_resp
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    rescue Faraday::TimeoutError => e
+      raise ConnectionError, "Request timeout: #{e.message}"
+    rescue Error
+      # Don't double-wrap our own errors
+      raise
+    rescue StandardError => e
+      # Catch-all for unexpected errors
+      raise ApiError, "Request failed: #{e.message}"
+    end
+
+    # Handle error responses and raise appropriate exceptions
+    #
+    # Examines the HTTP status code and error message from the API response
+    # and raises the appropriate exception type. This provides a clean
+    # abstraction where callers can rescue specific error types.
+    #
+    # Status code mapping:
+    # - 404: NotFoundError
+    # - 400: InvalidOrderError (if error_type is "InvalidOrder") or InvalidInputError
+    # - 405: InvalidInputError
+    # - 429: RateLimitError (includes retry-after header)
+    # - Other: ApiError
+    #
+    # @param response [Response] The wrapped HTTP response
+    # @return [void]
+    #
+    # @raise [NotFoundError] for 404 responses
+    # @raise [InvalidInputError] for 400/405 responses
+    # @raise [InvalidOrderError] for 400 responses with InvalidOrder error type
+    # @raise [RateLimitError] for 429 responses
+    # @raise [ApiError] for other error responses
+    #
+    # @api private
+    def handle_error_response(response)
+      case response.status
+      when 404
+        raise NotFoundError, response.error_message
+      when 400
+        # Check if it's an order-related error
+        raise InvalidOrderError, response.error_message if response.error_type == "InvalidOrder"
+
+        raise InvalidInputError, response.error_message
+      when 405
+        raise InvalidInputError, response.error_message
+      when 429
+        # Rate limiting - extract retry-after header if present
+        retry_after = response.headers["retry-after"] || response.headers["Retry-After"]
+        raise RateLimitError.new(response.error_message, retry_after: retry_after)
+      else
+        raise ApiError, response.error_message
+      end
+    end
+  end
+end

data/lib/petstore_api_client/response.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  # HTTP response wrapper for Petstore API responses
+  #
+  # Wraps Faraday HTTP responses and provides a clean, consistent interface
+  # for accessing response data. This class implements the Single Responsibility
+  # Principle by encapsulating all response handling logic in one place.
+  #
+  # The Response object provides:
+  # - Parsed JSON body (automatically converted from JSON)
+  # - HTTP status code
+  # - Response headers
+  # - Success/error detection
+  # - Error message extraction
+  # - Access to raw Faraday response
+  #
+  # Response bodies are automatically parsed from JSON. If the API returns
+  # non-JSON content (like HTML error pages), the body is returned as a string.
+  #
+  # @example Accessing a successful response
+  #   response = client.get("/pet/123")
+  #   if response.success?
+  #     pet = response.body
+  #     puts pet["name"]
+  #   end
+  #
+  # @example Handling an error response
+  #   response = client.get("/pet/invalid")
+  #   if response.error?
+  #     puts response.error_message
+  #     puts response.error_code
+  #   end
+  #
+  # @see Request
+  # @since 0.1.0
+  class Response
+    # @!attribute [r] status
+    #   @return [Integer] HTTP status code (e.g., 200, 404, 500)
+    # @!attribute [r] body
+    #   @return [Hash, Array, String] Parsed response body
+    # @!attribute [r] headers
+    #   @return [Hash] HTTP response headers
+    # @!attribute [r] raw_response
+    #   @return [Faraday::Response] Original Faraday response object
+    attr_reader :status, :body, :headers, :raw_response
+
+    # Initialize a new Response wrapper
+    #
+    # Wraps a Faraday response object and extracts relevant data.
+    # The response body is automatically parsed from JSON to Ruby objects.
+    #
+    # @param faraday_response [Faraday::Response] The Faraday response object
+    #
+    # @example
+    #   faraday_response = connection.get("/pet/123")
+    #   response = Response.new(faraday_response)
+    #
+    def initialize(faraday_response)
+      @raw_response = faraday_response
+      @status = faraday_response.status
+      @body = parse_body(faraday_response.body)
+      @headers = faraday_response.headers
+    end
+
+    # Check if the response was successful
+    #
+    # A response is considered successful if the HTTP status code is
+    # in the 2xx range (200-299).
+    #
+    # @return [Boolean] true if status is 200-299, false otherwise
+    #
+    # @example
+    #   response = client.get("/pet/123")
+    #   if response.success?
+    #     # Handle successful response
+    #   end
+    #
+    def success?
+      (200..299).cover?(status)
+    end
+
+    # Check if response indicates an error
+    #
+    # A response is considered an error if the HTTP status code is
+    # outside the 2xx range.
+    #
+    # @return [Boolean] true if status is not 200-299, false otherwise
+    #
+    # @example
+    #   response = client.get("/pet/invalid")
+    #   if response.error?
+    #     puts response.error_message
+    #   end
+    #
+    def error?
+      !success?
+    end
+
+    # Extract error message from response body
+    #
+    # Attempts to extract a human-readable error message from the response.
+    # Handles various response formats:
+    # - JSON with "message" key
+    # - Plain text error messages
+    # - HTML error pages
+    # - Empty/nil responses
+    #
+    # @return [String, nil] Error message if response is an error, nil otherwise
+    #
+    # @example JSON error response
+    #   # API returns: { "code": 404, "type": "NotFound", "message": "Pet not found" }
+    #   response.error_message # => "Pet not found"
+    #
+    # @example HTML error response
+    #   # API returns HTML error page
+    #   response.error_message # => "Request failed with status 500"
+    #
+    def error_message
+      return nil unless error?
+
+      # Extract message from different response formats
+      case body
+      when Hash
+        body["message"] || body[:message] || "Unknown error"
+      when String
+        # Sometimes the API returns HTML instead of JSON (sigh...)
+        body.include?("<html>") ? "Request failed with status #{status}" : body
+      else
+        "Request failed with status #{status}"
+      end
+    end
+
+    # Extract error code from response body
+    #
+    # Returns the error code from the response if available.
+    # Falls back to HTTP status code if no error code is present in body.
+    #
+    # @return [Integer, nil] Error code if response is an error, nil otherwise
+    #
+    # @example
+    #   # API returns: { "code": 1, "type": "NotFound", "message": "Pet not found" }
+    #   response.error_code # => 1
+    #
+    def error_code
+      return nil unless error?
+
+      body.is_a?(Hash) ? (body["code"] || body[:code]) : status
+    end
+
+    # Extract error type from response body
+    #
+    # Returns the error type/category from the response if available.
+    # This is useful for programmatic error handling.
+    #
+    # @return [String, nil] Error type if available, nil otherwise
+    #
+    # @example
+    #   # API returns: { "code": 1, "type": "NotFound", "message": "Pet not found" }
+    #   response.error_type # => "NotFound"
+    #
+    def error_type
+      return nil unless error?
+
+      body.is_a?(Hash) ? (body["type"] || body[:type]) : nil
+    end
+
+    private
+
+    # Parse response body from JSON
+    #
+    # Handles JSON parsing and various edge cases:
+    # - Already-parsed JSON (Hash/Array)
+    # - Empty/nil responses
+    # - Non-JSON responses (returns as-is)
+    #
+    # Faraday's JSON middleware typically handles parsing, but this method
+    # provides additional safety for edge cases.
+    #
+    # @param body [Object] Raw response body
+    # @return [Hash, Array, String, Object] Parsed body
+    #
+    # @api private
+    def parse_body(body)
+      # Faraday's JSON middleware already parses the response,
+      # but we handle edge cases here
+      return body if body.is_a?(Hash) || body.is_a?(Array)
+      return {} if body.nil? || body.empty?
+
+      body
+    end
+  end
+end

data/lib/petstore_api_client/validators/array_presence_validator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Custom validator for required array fields
+# ActiveModel's presence validator doesn't handle empty arrays correctly
+class ArrayPresenceValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    if value.nil?
+      record.errors.add(attribute, "must be present")
+    elsif !value.is_a?(Array)
+      record.errors.add(attribute, "must be an array")
+    elsif value.empty?
+      record.errors.add(attribute, "cannot be empty")
+    end
+  end
+end

data/lib/petstore_api_client/validators/enum_validator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Custom enum validator - ActiveModel's inclusion validator doesn't quite work the way we want
+# for status enums, so rolling our own
+class EnumValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if value.nil? && options[:allow_nil]
+
+    allowed_values = options[:in] || options[:within]
+    return if allowed_values.include?(value)
+
+    record.errors.add(
+      attribute,
+      "must be one of: #{allowed_values.join(", ")}, but got '#{value}'"
+    )
+  end
+end

data/lib/petstore_api_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  VERSION = "0.1.0"
+end

data/lib/petstore_api_client.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/all"
+
+require_relative "petstore_api_client/version"
+require_relative "petstore_api_client/errors"
+require_relative "petstore_api_client/configuration"
+require_relative "petstore_api_client/response"
+require_relative "petstore_api_client/paginated_collection"
+require_relative "petstore_api_client/connection"
+require_relative "petstore_api_client/request"
+require_relative "petstore_api_client/client"
+
+# Load validators
+require_relative "petstore_api_client/validators/array_presence_validator"
+require_relative "petstore_api_client/validators/enum_validator"
+
+# Load models
+require_relative "petstore_api_client/models/category"
+require_relative "petstore_api_client/models/tag"
+require_relative "petstore_api_client/models/api_response"
+require_relative "petstore_api_client/models/pet"
+require_relative "petstore_api_client/models/order"
+
+# Load clients
+require_relative "petstore_api_client/clients/pet_client"
+require_relative "petstore_api_client/clients/store_client"
+require_relative "petstore_api_client/api_client"
+
+# Module for the Petstore API Client library
+module PetstoreApiClient
+  class << self
+    attr_writer :configuration
+
+    # Global configuration accessor
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the library globally
+    # Example:
+    #   PetstoreApiClient.configure do |config|
+    #     config.api_key = "special-key"
+    #   end
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    # Reset the global configuration
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end