easy_talk 3.1.0 → 3.3.0

data/lib/easy_talk/configuration.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
+# typed: true
+
+require_relative 'naming_strategies'
 
 module EasyTalk
   class Configuration
+    extend T::Sig
+
     # JSON Schema draft version URIs
     SCHEMA_VERSIONS = {
       draft202012: 'https://json-schema.org/draft/2020-12/schema',
@@ -12,31 +17,71 @@ module EasyTalk
     }.freeze
 
     attr_accessor :default_additional_properties, :nilable_is_optional, :auto_validations, :schema_version, :schema_id,
-                  :use_refs
+                  :use_refs, :validation_adapter, :default_error_format, :error_type_base_uri, :include_error_codes,
+                  :base_schema_uri, :auto_generate_ids, :prefer_external_refs
+    attr_reader :property_naming_strategy
 
+    sig { void }
     def initialize
       @default_additional_properties = false
       @nilable_is_optional = false
       @auto_validations = true
+      @validation_adapter = :active_model
       @schema_version = :none
       @schema_id = nil
       @use_refs = false
+      @default_error_format = :flat
+      @error_type_base_uri = 'about:blank'
+      @include_error_codes = true
+      @base_schema_uri = nil
+      @auto_generate_ids = false
+      @prefer_external_refs = false
+      self.property_naming_strategy = :identity
     end
 
     # Returns the URI for the configured schema version, or nil if :none
+    sig { returns(T.nilable(String)) }
     def schema_uri
       return nil if @schema_version == :none
 
       SCHEMA_VERSIONS[@schema_version] || @schema_version.to_s
     end
+
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).void }
+    def property_naming_strategy=(strategy)
+      @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
+    end
+
+    # Register a custom type with its corresponding schema builder.
+    #
+    # This convenience method delegates to Builders::Registry.register
+    # and allows type registration within a configuration block.
+    #
+    # @param type_key [Class, String, Symbol] The type to register
+    # @param builder_class [Class] The builder class that generates JSON Schema
+    # @param collection [Boolean] Whether this is a collection type builder
+    # @return [void]
+    #
+    # @example
+    #   EasyTalk.configure do |config|
+    #     config.register_type Money, MoneySchemaBuilder
+    #   end
+    sig { params(type_key: T.any(T::Class[T.anything], String, Symbol), builder_class: T.untyped, collection: T::Boolean).void }
+    def register_type(type_key, builder_class, collection: false)
+      EasyTalk::Builders::Registry.register(type_key, builder_class, collection: collection)
+    end
   end
 
   class << self
+    extend T::Sig
+
+    sig { returns(Configuration) }
     def configuration
       @configuration ||= Configuration.new
     end
 
-    def configure
+    sig { params(block: T.proc.params(config: Configuration).void).void }
+    def configure(&block)
       yield(configuration)
     end
   end

data/lib/easy_talk/error_formatter/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Abstract base class for error formatters.
+    #
+    # Provides common functionality for transforming ActiveModel::Errors
+    # into standardized formats. Subclasses implement the `format` method
+    # to produce specific output formats.
+    #
+    # @abstract Subclass and implement {#format} to create a formatter.
+    #
+    # @example Creating a custom formatter
+    #   class CustomFormatter < EasyTalk::ErrorFormatter::Base
+    #     def format
+    #       error_entries.map do |entry|
+    #         { custom_field: entry[:attribute], custom_message: entry[:message] }
+    #       end
+    #     end
+    #   end
+    #
+    class Base
+      attr_reader :errors, :options
+
+      # Initialize a new formatter.
+      #
+      # @param errors [ActiveModel::Errors] The errors object to format
+      # @param options [Hash] Formatting options
+      # @option options [Boolean] :include_codes Whether to include error codes
+      def initialize(errors, options = {})
+        @errors = errors
+        @options = options
+      end
+
+      # Format the errors into the target format.
+      #
+      # @abstract
+      # @return [Hash, Array] The formatted errors
+      # @raise [NotImplementedError] if the subclass does not implement this method
+      def format
+        raise NotImplementedError, "#{self.class} must implement #format"
+      end
+
+      protected
+
+      # Check if error codes should be included in the output.
+      #
+      # @return [Boolean]
+      def include_codes?
+        @options.fetch(:include_codes, EasyTalk.configuration.include_error_codes)
+      end
+
+      # Build a normalized list of error entries from ActiveModel::Errors.
+      #
+      # Each entry contains:
+      # - :attribute - The attribute name (may include dots for nested)
+      # - :message - The error message
+      # - :full_message - The full error message with attribute name
+      # - :type - The error type from errors.details (e.g., :blank, :too_short)
+      # - :detail_options - Additional options from the error detail
+      #
+      # @return [Array<Hash>] The normalized error entries
+      def error_entries
+        @error_entries ||= build_error_entries
+      end
+
+      private
+
+      def build_error_entries
+        # Group details by attribute for matching
+        details_by_attr = {}
+        errors.details.each do |attr, detail_list|
+          details_by_attr[attr] = detail_list.dup
+        end
+
+        errors.map do |error|
+          attr = error.attribute
+          detail = find_and_consume_detail(details_by_attr, attr)
+
+          {
+            attribute: attr,
+            message: error.message,
+            full_message: error.full_message,
+            type: detail[:error],
+            detail_options: detail.except(:error)
+          }
+        end
+      end
+
+      # Find and consume a detail entry for an attribute.
+      # This handles the case where an attribute has multiple errors.
+      def find_and_consume_detail(details_by_attr, attribute)
+        detail_list = details_by_attr[attribute]
+        return {} if detail_list.nil? || detail_list.empty?
+
+        detail_list.shift || {}
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/error_code_mapper.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Maps ActiveModel validation error types to semantic error codes.
+    #
+    # ActiveModel's `errors.details` provides the validation type (e.g., :blank, :too_short).
+    # This class maps those types to standardized semantic codes for API responses.
+    #
+    # @example
+    #   ErrorCodeMapper.map(:blank)        # => "blank"
+    #   ErrorCodeMapper.map(:too_short)    # => "too_short"
+    #   ErrorCodeMapper.map(:invalid)      # => "invalid_format"
+    #
+    class ErrorCodeMapper
+      # Mapping of ActiveModel error types to semantic codes
+      VALIDATION_TO_CODE = {
+        # Presence validations
+        blank: 'blank',
+        present: 'present',
+        empty: 'empty',
+
+        # Format validations
+        invalid: 'invalid_format',
+
+        # Length validations
+        too_short: 'too_short',
+        too_long: 'too_long',
+        wrong_length: 'wrong_length',
+
+        # Numericality validations
+        not_a_number: 'not_a_number',
+        not_an_integer: 'not_an_integer',
+        greater_than: 'too_small',
+        greater_than_or_equal_to: 'too_small',
+        less_than: 'too_large',
+        less_than_or_equal_to: 'too_large',
+        equal_to: 'not_equal',
+        other_than: 'equal',
+        odd: 'not_odd',
+        even: 'not_even',
+
+        # Inclusion/exclusion validations
+        inclusion: 'not_included',
+        exclusion: 'excluded',
+
+        # Other validations
+        taken: 'taken',
+        confirmation: 'confirmation',
+        accepted: 'not_accepted'
+      }.freeze
+
+      class << self
+        # Map an ActiveModel error type to a semantic code.
+        #
+        # @param error_type [Symbol, String] The ActiveModel error type
+        # @return [String] The semantic error code
+        def map(error_type)
+          VALIDATION_TO_CODE[error_type.to_sym] || error_type.to_s
+        end
+
+        # Extract the error code from an ActiveModel error detail hash.
+        #
+        # @param detail [Hash] The error detail from errors.details
+        # @return [String] The semantic error code
+        #
+        # @example
+        #   ErrorCodeMapper.code_from_detail({ error: :blank })
+        #   # => "blank"
+        #
+        #   ErrorCodeMapper.code_from_detail({ error: :too_short, count: 2 })
+        #   # => "too_short"
+        def code_from_detail(detail)
+          error_key = detail[:error]
+          return 'unknown' unless error_key
+
+          map(error_key)
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/flat.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors as a simple flat array.
+    #
+    # This is the simplest format, providing an array of error objects
+    # with field name, message, and optional error code.
+    #
+    # @example Output
+    #   [
+    #     { "field" => "name", "message" => "can't be blank", "code" => "blank" },
+    #     { "field" => "email.address", "message" => "is invalid", "code" => "invalid_format" }
+    #   ]
+    #
+    class Flat < Base
+      # Format the errors as a flat array.
+      #
+      # @return [Array<Hash>] Array of error objects
+      def format
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      private
+
+      def build_error_object(entry)
+        error = {
+          'field' => PathConverter.to_flat(entry[:attribute]),
+          'message' => entry[:message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/json_pointer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors using JSON Pointer (RFC 6901) paths.
+    #
+    # Converts attribute paths to JSON Pointer format pointing to the
+    # property location in the JSON Schema.
+    #
+    # @example Output
+    #   [
+    #     { "pointer" => "/properties/name", "message" => "can't be blank", "code" => "blank" },
+    #     { "pointer" => "/properties/email/properties/address", "message" => "is invalid", "code" => "invalid_format" }
+    #   ]
+    #
+    class JsonPointer < Base
+      # Format the errors as an array with JSON Pointer paths.
+      #
+      # @return [Array<Hash>] Array of error objects with pointer paths
+      def format
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      private
+
+      def build_error_object(entry)
+        error = {
+          'pointer' => PathConverter.to_json_pointer(entry[:attribute]),
+          'message' => entry[:message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/jsonapi.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors according to the JSON:API specification.
+    #
+    # JSON:API defines a standard error format with specific fields for
+    # status, source, title, detail, and optional code.
+    #
+    # @see https://jsonapi.org/format/#error-objects
+    #
+    # @example Output
+    #   {
+    #     "errors" => [
+    #       {
+    #         "status" => "422",
+    #         "code" => "blank",
+    #         "source" => { "pointer" => "/data/attributes/name" },
+    #         "title" => "Invalid Attribute",
+    #         "detail" => "Name can't be blank"
+    #       }
+    #     ]
+    #   }
+    #
+    class Jsonapi < Base
+      # Default values for JSON:API error fields
+      DEFAULT_STATUS = '422'
+      DEFAULT_TITLE = 'Invalid Attribute'
+
+      # Format the errors as a JSON:API error response.
+      #
+      # @return [Hash] The JSON:API error object with "errors" array
+      def format
+        {
+          'errors' => build_errors_array
+        }
+      end
+
+      private
+
+      def build_errors_array
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      def build_error_object(entry)
+        error = {
+          'status' => options.fetch(:status, DEFAULT_STATUS).to_s,
+          'source' => {
+            'pointer' => PathConverter.to_jsonapi_pointer(
+              entry[:attribute],
+              prefix: options.fetch(:source_prefix, '/data/attributes')
+            )
+          },
+          'title' => options.fetch(:title, DEFAULT_TITLE),
+          'detail' => entry[:full_message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/path_converter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Converts attribute paths between different formats.
+    #
+    # EasyTalk uses dot notation for nested model errors (e.g., "email.address").
+    # This class converts those paths to different standard formats:
+    # - JSON Pointer (RFC 6901): /properties/email/properties/address
+    # - JSON:API: /data/attributes/email/address
+    # - Flat: email.address (unchanged)
+    #
+    # @example
+    #   PathConverter.to_json_pointer("email.address")
+    #   # => "/properties/email/properties/address"
+    #
+    #   PathConverter.to_jsonapi_pointer("email.address")
+    #   # => "/data/attributes/email/address"
+    #
+    class PathConverter
+      class << self
+        # Convert an attribute path to JSON Schema pointer format.
+        #
+        # @param attribute [Symbol, String] The attribute path (e.g., "email.address")
+        # @return [String] The JSON Pointer path (e.g., "/properties/email/properties/address")
+        def to_json_pointer(attribute)
+          parts = attribute.to_s.split('.')
+          return "/properties/#{parts.first}" if parts.length == 1
+
+          parts.map { |part| "/properties/#{part}" }.join
+        end
+
+        # Convert an attribute path to JSON:API pointer format.
+        #
+        # @param attribute [Symbol, String] The attribute path
+        # @param prefix [String] The path prefix (default: "/data/attributes")
+        # @return [String] The JSON:API pointer path
+        def to_jsonapi_pointer(attribute, prefix: '/data/attributes')
+          parts = attribute.to_s.split('.')
+          "#{prefix}/#{parts.join('/')}"
+        end
+
+        # Return the attribute path as-is (flat format).
+        #
+        # @param attribute [Symbol, String] The attribute path
+        # @return [String] The attribute as a string
+        def to_flat(attribute)
+          attribute.to_s
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/rfc7807.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors according to RFC 7807 (Problem Details for HTTP APIs).
+    #
+    # RFC 7807 defines a standard format for describing errors in HTTP APIs.
+    # This formatter produces a Problem Details object with validation errors
+    # in an extended "errors" array.
+    #
+    # @see https://tools.ietf.org/html/rfc7807
+    #
+    # @example Output
+    #   {
+    #     "type" => "https://example.com/validation-error",
+    #     "title" => "Validation Failed",
+    #     "status" => 422,
+    #     "detail" => "The request contains invalid parameters",
+    #     "errors" => [
+    #       { "pointer" => "/properties/name", "detail" => "can't be blank", "code" => "blank" }
+    #     ]
+    #   }
+    #
+    class Rfc7807 < Base
+      # Default values for RFC 7807 fields
+      DEFAULT_TITLE = 'Validation Failed'
+      DEFAULT_STATUS = 422
+      DEFAULT_DETAIL = 'The request contains invalid parameters'
+
+      # Format the errors as an RFC 7807 Problem Details object.
+      #
+      # @return [Hash] The Problem Details object
+      def format
+        {
+          'type' => error_type_uri,
+          'title' => options.fetch(:title, DEFAULT_TITLE),
+          'status' => options.fetch(:status, DEFAULT_STATUS),
+          'detail' => options.fetch(:detail, DEFAULT_DETAIL),
+          'errors' => build_errors_array
+        }
+      end
+
+      private
+
+      def error_type_uri
+        base_uri = options.fetch(:type_base_uri, EasyTalk.configuration.error_type_base_uri)
+        type_suffix = options.fetch(:type, 'validation-error')
+        return type_suffix if base_uri.nil? || base_uri == 'about:blank'
+
+        "#{base_uri.chomp('/')}/#{type_suffix}"
+      end
+
+      def build_errors_array
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      def build_error_object(entry)
+        error = {
+          'pointer' => PathConverter.to_json_pointer(entry[:attribute]),
+          'detail' => entry[:message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'error_formatter/error_code_mapper'
+require_relative 'error_formatter/path_converter'
+require_relative 'error_formatter/base'
+require_relative 'error_formatter/flat'
+require_relative 'error_formatter/json_pointer'
+require_relative 'error_formatter/rfc7807'
+require_relative 'error_formatter/jsonapi'
+
+module EasyTalk
+  # Module for formatting ActiveModel validation errors into standardized formats.
+  #
+  # Provides multiple output formats for API responses:
+  # - `:flat` - Simple flat array of field/message/code objects
+  # - `:json_pointer` - Array with JSON Pointer (RFC 6901) paths
+  # - `:rfc7807` - RFC 7807 Problem Details format
+  # - `:jsonapi` - JSON:API specification error format
+  #
+  # @example Using via model instance methods
+  #   user = User.new(name: '')
+  #   user.valid?
+  #
+  #   user.validation_errors                    # Uses default format from config
+  #   user.validation_errors_flat               # Flat format
+  #   user.validation_errors_json_pointer       # JSON Pointer format
+  #   user.validation_errors_rfc7807            # RFC 7807 format
+  #   user.validation_errors_jsonapi            # JSON:API format
+  #
+  # @example Using the format method directly
+  #   EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: 'Custom Title')
+  #
+  module ErrorFormatter
+    # Map of format symbols to formatter classes
+    FORMATTERS = {
+      flat: Flat,
+      json_pointer: JsonPointer,
+      rfc7807: Rfc7807,
+      jsonapi: Jsonapi
+    }.freeze
+
+    class << self
+      # Format validation errors using the specified format.
+      #
+      # @param errors [ActiveModel::Errors] The errors object to format
+      # @param format [Symbol] The output format (:flat, :json_pointer, :rfc7807, :jsonapi)
+      # @param options [Hash] Format-specific options
+      # @return [Hash, Array] The formatted errors
+      # @raise [ArgumentError] If the format is not recognized
+      #
+      # @example
+      #   EasyTalk::ErrorFormatter.format(user.errors, format: :flat)
+      #   EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: 'Validation Error')
+      def format(errors, format: nil, **options)
+        format ||= EasyTalk.configuration.default_error_format
+        formatter_class = FORMATTERS[format.to_sym]
+
+        raise ArgumentError, "Unknown error format: #{format}. Valid formats: #{FORMATTERS.keys.join(', ')}" unless formatter_class
+
+        formatter_class.new(errors, options).format
+      end
+    end
+
+    # Instance methods mixed into EasyTalk::Model classes.
+    #
+    # Provides convenient methods for formatting validation errors
+    # on model instances.
+    module InstanceMethods
+      # Format validation errors using the default or specified format.
+      #
+      # @param format [Symbol] The output format (optional, uses config default)
+      # @param options [Hash] Format-specific options
+      # @return [Hash, Array] The formatted errors
+      #
+      # @example
+      #   user.validation_errors
+      #   user.validation_errors(format: :rfc7807, title: 'User Error')
+      def validation_errors(format: nil, **)
+        ErrorFormatter.format(errors, format: format, **)
+      end
+
+      # Format validation errors as a flat array.
+      #
+      # @param options [Hash] Format options
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Array<Hash>] Array of error objects
+      #
+      # @example
+      #   user.validation_errors_flat
+      #   # => [{ "field" => "name", "message" => "can't be blank", "code" => "blank" }]
+      def validation_errors_flat(**)
+        ErrorFormatter.format(errors, format: :flat, **)
+      end
+
+      # Format validation errors with JSON Pointer paths.
+      #
+      # @param options [Hash] Format options
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Array<Hash>] Array of error objects with pointer paths
+      #
+      # @example
+      #   user.validation_errors_json_pointer
+      #   # => [{ "pointer" => "/properties/name", "message" => "can't be blank", "code" => "blank" }]
+      def validation_errors_json_pointer(**)
+        ErrorFormatter.format(errors, format: :json_pointer, **)
+      end
+
+      # Format validation errors as RFC 7807 Problem Details.
+      #
+      # @param options [Hash] Format options
+      # @option options [String] :title The problem title
+      # @option options [Integer] :status The HTTP status code
+      # @option options [String] :detail The problem detail message
+      # @option options [String] :type_base_uri Base URI for error type
+      # @option options [String] :type The error type suffix
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Hash] The Problem Details object
+      #
+      # @example
+      #   user.validation_errors_rfc7807
+      #   user.validation_errors_rfc7807(title: 'User Validation Failed', status: 400)
+      def validation_errors_rfc7807(**)
+        ErrorFormatter.format(errors, format: :rfc7807, **)
+      end
+
+      # Format validation errors according to JSON:API specification.
+      #
+      # @param options [Hash] Format options
+      # @option options [String] :status The HTTP status code (as string)
+      # @option options [String] :title The error title
+      # @option options [String] :source_prefix The source pointer prefix
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Hash] The JSON:API error object
+      #
+      # @example
+      #   user.validation_errors_jsonapi
+      #   user.validation_errors_jsonapi(title: 'Validation Error', source_prefix: '/data')
+      def validation_errors_jsonapi(**)
+        ErrorFormatter.format(errors, format: :jsonapi, **)
+      end
+    end
+  end
+end

data/lib/easy_talk/errors.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   class Error < StandardError; end
   class ConstraintError < Error; end
   class UnknownOptionError < Error; end
+  class UnknownTypeError < Error; end
+  class InvalidInstructionsError < Error; end
   class InvalidPropertyNameError < Error; end
 end