domain_extractor 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08132eca3d279a11cf379a83f5288cbf1de6dfe50f62dce4592091c7dfd0195f'
-  data.tar.gz: 22bb6ffd2c8b71271eb0c0a7a26faecfd1faad1b834b26ddbdea921712c8ebed
+  metadata.gz: bb9ff9b765f3037fb6a2f0af330ecf415c76dde8b59aea7c362e353460d20049
+  data.tar.gz: 3349872d55a4a6252a1886b69eacc33743af7b6a8d74be1fb142842884cb41e7
 SHA512:
-  metadata.gz: a93a94135442996433fb0bee204e78a9d07fb1da7628cad8bdc7c5e4fd8477c7dd28e63a9e3ed4e6b4784027f35fe9c8402c16c5ea4be639dc90f5ae78dd6c7a
-  data.tar.gz: fcc7cd325ceda6d08a598cca43af970ea1867125722958ebe2f652042c02b322888ac7071b5f99fcce076b81444c4ff4b98a41625c00e9d8ccfd3dd143ce0675
+  metadata.gz: 54d64c3c9b3cf04ac2405c86f563cea1d22d0e37491caee3de5e0a6ab569686ce57b4a0efa9b23729bb6efe5a2eda25b5421c1a0188dd241348f4dd2f0663540
+  data.tar.gz: ee15d47829741ac24ebcc13621a62e83f421f6dd2572f0abafeaca2fbac12da02b72bec9350aeb2f375da71de13518a82856dc5af049fb813952509ed9b5e94f

data/CHANGELOG.md

@@ -5,24 +5,210 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.5] - 2025-11-09
+## [0.2.7] - 2025-11-09
 
-### Added Rails Integration - Custom ActiveModel Validator
+### Added - URL Formatting API
 
-Added a comprehensive custom ActiveModel validator for declarative URL and domain validation in Rails applications. The validator integrates seamlessly with Rails 6, 7, and 8.
+Added a comprehensive `format` method for programmatic URL normalization and transformation. The formatter provides precise control over URL structure, protocol, and formatting while maintaining the same validation modes as the Rails validator.
 
 #### Features
 
+**Core Method:**
+- `DomainExtractor.format(url, **options)` - Format and normalize URLs based on specified options
+- Returns formatted URL string or `nil` for invalid input
+- Strips paths and query parameters from URLs
+- Supports all validation modes from the Rails validator
+
+**Validation Modes:**
+- `:standard` (default) - Preserves full host as-is while normalizing protocol/slashes
+- `:root_domain` - Strips all subdomains, returns only root domain
+- `:root_or_custom_subdomain` - Preserves custom subdomains but removes 'www'
+
+**Formatting Options:**
+- `use_protocol` (default: `true`) - Include/exclude protocol in output
+- `use_https` (default: `true`) - Use HTTPS vs HTTP (only when `use_protocol` is true)
+- `use_trailing_slash` (default: `false`) - Add/remove trailing slash from output
+
+#### Usage Examples
+
+**Basic Formatting:**
+```ruby
+# Remove trailing slash (default)
+DomainExtractor.format('https://example.com/')
+# => 'https://example.com'
+
+# Strip paths and query parameters
+DomainExtractor.format('https://example.com/path?query=value')
+# => 'https://example.com'
+
+# Normalize to HTTPS
+DomainExtractor.format('http://example.com')
+# => 'https://example.com'
+```
+
+**Validation Modes:**
+```ruby
+# Root domain only (strips subdomains)
+DomainExtractor.format('https://shop.example.com', validation: :root_domain)
+# => 'https://example.com'
+
+# Strip www but keep custom subdomains
+DomainExtractor.format('https://www.example.com', validation: :root_or_custom_subdomain)
+# => 'https://example.com'
+```
+
+**Protocol Control:**
+```ruby
+# Without protocol
+DomainExtractor.format('https://example.com', use_protocol: false)
+# => 'example.com'
+
+# Force HTTP instead of HTTPS
+DomainExtractor.format('https://example.com', use_https: false)
+# => 'http://example.com'
+```
+
+**Trailing Slash Control:**
+```ruby
+# Add trailing slash
+DomainExtractor.format('https://example.com', use_trailing_slash: true)
+# => 'https://example.com/'
+```
+
+**Combined Options:**
+```ruby
+# Root domain, no protocol, with trailing slash
+DomainExtractor.format('https://shop.example.com/path',
+                       validation: :root_domain,
+                       use_protocol: false,
+                       use_trailing_slash: true)
+# => 'example.com/'
+```
+
+#### Real-World Use Cases
+
+**Canonical URL Generation:**
+```ruby
+def canonical_url(url)
+  DomainExtractor.format(url,
+                         validation: :root_or_custom_subdomain,
+                         use_https: true,
+                         use_trailing_slash: false)
+end
+
+canonical_url('http://www.example.com/')   # => 'https://example.com'
+```
+
+**Domain Normalization for Allowlists:**
+```ruby
+def normalize_domain(url)
+  DomainExtractor.format(url, validation: :root_domain, use_protocol: false)
+end
+
+normalize_domain('https://shop.example.com/path')  # => 'example.com'
+```
+
+**Multi-Tenant URL Standardization:**
+```ruby
+class Tenant < ApplicationRecord
+  before_validation :normalize_custom_domain
+
+  private
+
+  def normalize_custom_domain
+    return if custom_domain.blank?
+
+    self.custom_domain = DomainExtractor.format(
+      custom_domain,
+      validation: :root_or_custom_subdomain,
+      use_https: true,
+      use_trailing_slash: false
+    )
+  end
+end
+```
+
+#### Implementation Details
+
+- **Performance**: Leverages existing DomainExtractor parsing engine with minimal overhead
+- **Nil-safe**: Returns `nil` for invalid URLs instead of raising exceptions
+- **Consistent API**: Uses same option names and validation modes as Rails validator
+- **Path/Query Stripping**: Automatically removes paths and query parameters
+- **Multi-part TLD Support**: Correctly handles complex TLDs like `.co.uk`, `.com.au`
+
+#### Code Quality
+
+- **49 comprehensive test cases** covering all formatting modes and options
+- **RuboCop clean** with zero offenses
+- **100% test coverage** maintained across entire gem (200 total tests)
+- **Well-documented** with extensive README section and real-world examples
+
+#### Documentation
+
+- Added comprehensive **URL Formatting** section to README.md
+- Includes examples for all validation modes and options
+- Real-world use cases: canonical URLs, domain normalization, multi-tenant standardization
+- Clear API reference with all available options
+
+## [0.2.6] - 2025-11-09
+
+### Fixed - Rails Validator Registration
+
+**CRITICAL FIX**: Moved `DomainValidator` class to the **top-level namespace** (from `DomainExtractor::DomainValidator`) to ensure Rails can properly autoload and find the validator.
+
+#### The Problem
+
+Version 0.2.5 defined the validator as `DomainExtractor::DomainValidator`, which caused Rails to fail with:
+
+```
+ArgumentError: Unknown validator: 'DomainValidator'
+NameError: uninitialized constant Website::DomainValidator
+```
+
+This occurred because when using `validates :url, domain: { ... }`, Rails searches for `DomainValidator` in:
+
+1. The model's namespace (e.g., `Website::DomainValidator`)
+2. The top-level namespace (`::DomainValidator`)
+3. ActiveModel::Validations namespace
+
+It does **not** search module namespaces like `DomainExtractor::`.
+
+#### The Solution
+
+- Moved `DomainValidator` to top-level namespace where Rails can find it
+- Added `DomainExtractor::DomainValidator` as an alias for backward compatibility
+- All functionality remains identical; only the class location changed
+
+#### Verification
+
+- All 151 tests pass including 35 validator-specific tests
+- RuboCop clean with zero offenses
+- Verified in production Rails 8 application
+- Confirmed working with `validates :url, domain: { validation: :root_or_custom_subdomain }`
+
+## [0.2.5] - 2025-11-09 [YANKED]
+
+**This version was yanked due to validator registration issue. Use 0.2.6 instead.**
+
+### Added Rails Integration - Custom ActiveModel Validator (BROKEN)
+
+Added a comprehensive custom ActiveModel validator for declarative URL and domain validation in Rails applications. However, the validator was incorrectly namespaced and did not work in Rails applications.
+
+#### Features (Broken in 0.2.5)
+
 **Validation Modes:**
+
 - `:standard` - Validates any parseable URL (default mode)
 - `:root_domain` - Only allows root domains without subdomains (e.g., `example.com` ✅, `shop.example.com` ❌)
 - `:root_or_custom_subdomain` - Allows root or custom subdomains but excludes `www` subdomain (e.g., `example.com` ✅, `shop.example.com` ✅, `www.example.com` ❌)
 
 **Protocol Options:**
+
 - `use_protocol` (default: `true`) - Controls whether protocol (http/https) is required in the URL
 - `use_https` (default: `true`) - Controls whether HTTPS is required (only relevant when `use_protocol` is true)
 
 **Usage Examples:**
+
 ```ruby
 # Standard validation - any valid URL
 validates :url, domain: { validation: :standard }
@@ -77,6 +263,7 @@ validates :domain, domain: {
 #### Use Cases
 
 Perfect for Rails applications requiring:
+
 - Multi-tenant custom domain validation
 - Secure URL validation (HTTPS enforcement)
 - Subdomain-based architecture validation

data/README.md

@@ -13,6 +13,8 @@ Use **DomainExtractor** whenever you need a dependable tld parser for tricky mul
 ✅ **Accurate Multi-part TLD Parser** - Handles complex multi-part TLDs (co.uk, com.au, gov.br) using the [Public Suffix List](https://publicsuffix.org/)
 ✅ **Nested Subdomain Extraction** - Correctly parses multi-level subdomains (api.staging.example.com)
 ✅ **Smart URL Normalization** - Automatically handles URLs with or without schemes
+✅ **Powerful URL Formatting** - Transform and standardize URLs with flexible options
+✅ **Rails Integration** - Custom ActiveModel validator for declarative URL validation
 ✅ **Query Parameter Parsing** - Parse query strings into structured hashes
 ✅ **Batch Processing** - Parse multiple URLs efficiently
 ✅ **IP Address Detection** - Identifies and handles IPv4 and IPv6 addresses
@@ -355,6 +357,241 @@ DomainExtractor.parse_query_params(query_string)
 # Returns: Hash of query parameters
 ```
 
+```ruby
+DomainExtractor.format(url_string, **options)
+
+# => Formats a URL according to the specified options.
+
+# Returns: Formatted URL string or nil if invalid
+# Options:
+#   :validation (:standard, :root_domain, :root_or_custom_subdomain)
+#   :use_protocol (true/false)
+#   :use_https (true/false)
+#   :use_trailing_slash (true/false)
+```
+
+## URL Formatting
+
+DomainExtractor provides powerful URL formatting capabilities to normalize, transform, and standardize URLs according to your application's requirements.
+
+### Basic Formatting
+
+```ruby
+# Remove trailing slash (default)
+DomainExtractor.format('https://example.com/')
+# => 'https://example.com'
+
+# Strip paths and query parameters
+DomainExtractor.format('https://example.com/path?query=value')
+# => 'https://example.com'
+
+# Normalize to HTTPS
+DomainExtractor.format('http://example.com')
+# => 'https://example.com'
+```
+
+### Validation Modes
+
+#### Standard Mode (Default)
+
+Preserves the full host as-is while normalizing protocol and trailing slashes.
+
+```ruby
+DomainExtractor.format('https://shop.example.com')
+# => 'https://shop.example.com'
+
+DomainExtractor.format('https://www.example.com/')
+# => 'https://www.example.com'
+
+DomainExtractor.format('https://api.staging.example.com')
+# => 'https://api.staging.example.com'
+```
+
+#### Root Domain Mode
+
+Strips all subdomains and returns only the root domain.
+
+```ruby
+DomainExtractor.format('https://shop.example.com', validation: :root_domain)
+# => 'https://example.com'
+
+DomainExtractor.format('https://www.example.com/', validation: :root_domain)
+# => 'https://example.com'
+
+DomainExtractor.format('https://api.staging.example.com', validation: :root_domain)
+# => 'https://example.com'
+
+# Works with multi-part TLDs
+DomainExtractor.format('https://shop.example.co.uk', validation: :root_domain)
+# => 'https://example.co.uk'
+```
+
+#### Root or Custom Subdomain Mode
+
+Preserves custom subdomains but specifically removes the 'www' subdomain.
+
+```ruby
+DomainExtractor.format('https://example.com', validation: :root_or_custom_subdomain)
+# => 'https://example.com'
+
+DomainExtractor.format('https://shop.example.com', validation: :root_or_custom_subdomain)
+# => 'https://shop.example.com'
+
+# Strips www subdomain
+DomainExtractor.format('https://www.example.com', validation: :root_or_custom_subdomain)
+# => 'https://example.com'
+
+DomainExtractor.format('https://api.example.com', validation: :root_or_custom_subdomain)
+# => 'https://api.example.com'
+```
+
+### Protocol Options
+
+#### Without Protocol
+
+Remove the protocol entirely from the output.
+
+```ruby
+DomainExtractor.format('https://example.com', use_protocol: false)
+# => 'example.com'
+
+DomainExtractor.format('https://shop.example.com', use_protocol: false)
+# => 'shop.example.com'
+
+# Combine with root_domain
+DomainExtractor.format('https://shop.example.com',
+                       validation: :root_domain,
+                       use_protocol: false)
+# => 'example.com'
+```
+
+#### HTTP vs HTTPS
+
+Control which protocol to use in the output.
+
+```ruby
+# Default: use HTTPS
+DomainExtractor.format('http://example.com')
+# => 'https://example.com'
+
+# Allow HTTP
+DomainExtractor.format('https://example.com', use_https: false)
+# => 'http://example.com'
+
+DomainExtractor.format('http://example.com', use_https: false)
+# => 'http://example.com'
+```
+
+### Trailing Slash Options
+
+```ruby
+# Remove trailing slash (default)
+DomainExtractor.format('https://example.com/')
+# => 'https://example.com'
+
+# Add trailing slash
+DomainExtractor.format('https://example.com', use_trailing_slash: true)
+# => 'https://example.com/'
+
+DomainExtractor.format('https://example.com/', use_trailing_slash: true)
+# => 'https://example.com/'
+
+# Works with other options
+DomainExtractor.format('https://shop.example.com',
+                       validation: :root_domain,
+                       use_trailing_slash: true)
+# => 'https://example.com/'
+```
+
+### Combined Options
+
+Mix and match options for precise URL formatting:
+
+```ruby
+# Root domain, no protocol, with trailing slash
+DomainExtractor.format('https://shop.example.com/path',
+                       validation: :root_domain,
+                       use_protocol: false,
+                       use_trailing_slash: true)
+# => 'example.com/'
+
+# Strip www, use HTTP, with trailing slash
+DomainExtractor.format('https://www.example.com',
+                       validation: :root_or_custom_subdomain,
+                       use_https: false,
+                       use_trailing_slash: true)
+# => 'http://example.com/'
+
+# Standard mode, no protocol, with trailing slash
+DomainExtractor.format('https://api.example.com',
+                       use_protocol: false,
+                       use_trailing_slash: true)
+# => 'api.example.com/'
+```
+
+### Real-World Use Cases
+
+#### Canonical URL Generation
+
+```ruby
+def canonical_url(url)
+  DomainExtractor.format(url,
+                         validation: :root_or_custom_subdomain,
+                         use_https: true,
+                         use_trailing_slash: false)
+end
+
+canonical_url('http://www.example.com/')      # => 'https://example.com'
+canonical_url('https://shop.example.com/')    # => 'https://shop.example.com'
+```
+
+#### Domain Normalization for Allowlists
+
+```ruby
+def normalize_domain_for_allowlist(url)
+  DomainExtractor.format(url,
+                         validation: :root_domain,
+                         use_protocol: false)
+end
+
+normalize_domain_for_allowlist('https://shop.example.com/path')  # => 'example.com'
+normalize_domain_for_allowlist('http://www.example.com')         # => 'example.com'
+```
+
+#### Multi-Tenant URL Standardization
+
+```ruby
+class Tenant < ApplicationRecord
+  before_validation :normalize_custom_domain
+
+  private
+
+  def normalize_custom_domain
+    return if custom_domain.blank?
+
+    self.custom_domain = DomainExtractor.format(
+      custom_domain,
+      validation: :root_or_custom_subdomain,
+      use_https: true,
+      use_trailing_slash: false
+    )
+  end
+end
+```
+
+#### API Endpoint Formatting
+
+```ruby
+def format_api_endpoint(url)
+  DomainExtractor.format(url,
+                         validation: :standard,
+                         use_https: true,
+                         use_trailing_slash: true)
+end
+
+format_api_endpoint('http://api.example.com')  # => 'https://api.example.com/'
+```
+
 ## Rails Integration
 
 DomainExtractor provides a custom ActiveModel validator for Rails applications, enabling declarative URL/domain validation with multiple modes and options.

data/lib/domain_extractor/domain_validator.rb

@@ -16,151 +16,160 @@ rescue LoadError
   end
 end
 
-module DomainExtractor
-  # DomainValidator is a custom ActiveModel validator for URL/domain validation.
-  #
-  # Validation modes:
-  # - :standard - Validates any valid URL using DomainExtractor.valid?
-  # - :root_domain - Only allows root domains (no subdomains) like https://mysite.com
-  # - :root_or_custom_subdomain - Allows root or custom subdomains, but excludes 'www'
-  #
-  # Optional flags:
-  # - use_protocol (default: true) - Whether protocol (http/https) is required
-  # - use_https (default: true) - Whether https is required (only if use_protocol is true)
-  #
-  # @example Standard validation
-  #   validates :url, domain: { validation: :standard }
-  #
-  # @example Root domain only, no protocol required
-  #   validates :url, domain: { validation: :root_domain, use_protocol: false }
-  #
-  # @example Root or custom subdomain with https required
-  #   validates :url, domain: { validation: :root_or_custom_subdomain, use_https: true }
-  class DomainValidator < ActiveModel::EachValidator
-    VALIDATION_MODES = %i[standard root_domain root_or_custom_subdomain].freeze
-    WWW_SUBDOMAIN = 'www'
-
-    def validate_each(record, attribute, value)
-      return if blank?(value)
-
-      validation_mode = extract_validation_mode
-      use_protocol = options.fetch(:use_protocol, true)
-      use_https = options.fetch(:use_https, true)
-
-      normalized_url = normalize_url(value, use_protocol, use_https)
-
-      return unless protocol_valid?(record, attribute, normalized_url, use_protocol, use_https)
-
-      parsed = parse_and_validate_url(record, attribute, normalized_url)
-      return unless parsed
+# DomainValidator is a custom ActiveModel validator for URL/domain validation.
+#
+# This validator is defined at the top level so Rails can find it when using:
+#   validates :url, domain: { validation: :standard }
+#
+# Validation modes:
+# - :standard - Validates any valid URL using DomainExtractor.valid?
+# - :root_domain - Only allows root domains (no subdomains) like https://mysite.com
+# - :root_or_custom_subdomain - Allows root or custom subdomains but excludes 'www'
+#
+# Optional flags:
+# - use_protocol (default: true) - Whether protocol (http/https) is required
+# - use_https (default: true) - Whether https is required (only if use_protocol is true)
+#
+# @example Standard validation
+#   validates :url, domain: { validation: :standard }
+#
+# @example Root domain only, no protocol required
+#   validates :url, domain: { validation: :root_domain, use_protocol: false }
+#
+# @example Root or custom subdomain with https required
+#   validates :url, domain: { validation: :root_or_custom_subdomain, use_https: true }
+class DomainValidator < ActiveModel::EachValidator
+  VALIDATION_MODES = %i[standard root_domain root_or_custom_subdomain].freeze
+  WWW_SUBDOMAIN = 'www'
+
+  def validate_each(record, attribute, value)
+    return if blank?(value)
+
+    validation_mode = extract_validation_mode
+    use_protocol = options.fetch(:use_protocol, true)
+    use_https = options.fetch(:use_https, true)
+
+    normalized_url = normalize_url(value, use_protocol, use_https)
+
+    return unless protocol_valid?(record, attribute, normalized_url, use_protocol, use_https)
+
+    parsed = parse_and_validate_url(record, attribute, normalized_url)
+    return unless parsed
+
+    apply_validation_mode(record, attribute, parsed, validation_mode)
+  end
 
-      apply_validation_mode(record, attribute, parsed, validation_mode)
-    end
+  private
 
-    private
+  # Extract and validate the validation mode option
+  def extract_validation_mode
+    validation_mode = options.fetch(:validation, :standard)
+    return validation_mode if VALIDATION_MODES.include?(validation_mode)
 
-    # Extract and validate the validation mode option
-    def extract_validation_mode
-      validation_mode = options.fetch(:validation, :standard)
-      return validation_mode if VALIDATION_MODES.include?(validation_mode)
+    raise ArgumentError, "Invalid validation mode: #{validation_mode}. " \
+                         "Must be one of: #{VALIDATION_MODES.join(', ')}"
+  end
 
-      raise ArgumentError, "Invalid validation mode: #{validation_mode}. " \
-                           "Must be one of: #{VALIDATION_MODES.join(', ')}"
-    end
+  # Check protocol requirements
+  def protocol_valid?(record, attribute, url, use_protocol, use_https)
+    return true unless use_protocol
+    return true if valid_protocol?(url, use_https)
 
-    # Check protocol requirements
-    def protocol_valid?(record, attribute, url, use_protocol, use_https)
-      return true unless use_protocol
-      return true if valid_protocol?(url, use_https)
+    protocol = use_https ? 'https://' : 'http:// or https://'
+    record.errors.add(attribute, "must use #{protocol}")
+    false
+  end
 
-      protocol = use_https ? 'https://' : 'http:// or https://'
-      record.errors.add(attribute, "must use #{protocol}")
-      false
-    end
+  # Parse URL and validate it's valid
+  def parse_and_validate_url(record, attribute, url)
+    parsed = DomainExtractor.parse(url)
+    return parsed if parsed.valid?
 
-    # Parse URL and validate it's valid
-    def parse_and_validate_url(record, attribute, url)
-      parsed = DomainExtractor.parse(url)
-      return parsed if parsed.valid?
+    record.errors.add(attribute, 'is not a valid URL')
+    nil
+  end
 
-      record.errors.add(attribute, 'is not a valid URL')
+  # Apply the validation mode rules
+  def apply_validation_mode(record, attribute, parsed, validation_mode)
+    case validation_mode
+    when :standard
+      # Already validated - any valid URL passes
       nil
+    when :root_domain
+      validate_root_domain(record, attribute, parsed)
+    when :root_or_custom_subdomain
+      validate_root_or_custom_subdomain(record, attribute, parsed)
     end
+  end
 
-    # Apply the validation mode rules
-    def apply_validation_mode(record, attribute, parsed, validation_mode)
-      case validation_mode
-      when :standard
-        # Already validated - any valid URL passes
-        nil
-      when :root_domain
-        validate_root_domain(record, attribute, parsed)
-      when :root_or_custom_subdomain
-        validate_root_or_custom_subdomain(record, attribute, parsed)
-      end
-    end
-
-    # Check if value is blank (nil, empty string, or whitespace-only)
-    def blank?(value)
-      value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
-        (value.is_a?(String) && value.strip.empty?)
-    end
-
-    # Normalize URL for validation based on protocol requirements
-    def normalize_url(url, use_protocol, use_https)
-      return url if blank?(url)
+  # Check if value is blank (nil, empty string, or whitespace-only)
+  def blank?(value)
+    value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+      (value.is_a?(String) && value.strip.empty?)
+  end
 
-      url = url.strip
+  # Normalize URL for validation based on protocol requirements
+  def normalize_url(url, use_protocol, use_https)
+    return url if blank?(url)
 
-      # If protocol is not required, strip any existing protocol
-      url = url.gsub(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://}, '') unless use_protocol
+    url = url.strip
 
-      # Add protocol if needed for parsing
-      unless url.match?(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://})
-        scheme = use_https ? 'https://' : 'http://'
-        url = scheme + url
-      end
+    # If protocol is not required, strip any existing protocol
+    url = url.gsub(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://}, '') unless use_protocol
 
-      url
+    # Add protocol if needed for parsing
+    unless url.match?(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://})
+      scheme = use_https ? 'https://' : 'http://'
+      url = scheme + url
     end
 
-    # Check if URL has valid protocol
-    def valid_protocol?(url, use_https)
-      return true unless url.match?(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://})
+    url
+  end
+
+  # Check if URL has valid protocol
+  def valid_protocol?(url, use_https)
+    return true unless url.match?(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://})
 
-      if use_https
-        url.start_with?('https://')
-      else
-        url.start_with?('http://', 'https://')
-      end
+    if use_https
+      url.start_with?('https://')
+    else
+      url.start_with?('http://', 'https://')
     end
+  end
 
-    # Validate that URL is a root domain (no subdomain)
-    def validate_root_domain(record, attribute, parsed)
-      return unless parsed.subdomain?
+  # Validate that URL is a root domain (no subdomain)
+  def validate_root_domain(record, attribute, parsed)
+    return unless parsed.subdomain?
 
-      record.errors.add(attribute, 'must be a root domain (no subdomains allowed)')
-    end
+    record.errors.add(attribute, 'must be a root domain (no subdomains allowed)')
+  end
 
-    # Validate that URL is either root domain or has custom subdomain (not 'www')
-    def validate_root_or_custom_subdomain(record, attribute, parsed)
-      return unless parsed.subdomain == WWW_SUBDOMAIN
+  # Validate that URL is either root domain or has custom subdomain (not 'www')
+  def validate_root_or_custom_subdomain(record, attribute, parsed)
+    return unless parsed.subdomain == WWW_SUBDOMAIN
 
-      record.errors.add(attribute, 'cannot use www subdomain')
-    end
+    record.errors.add(attribute, 'cannot use www subdomain')
   end
 end
 
-# Register the validator with ActiveModel if it's available
-if defined?(ActiveModel::Validations)
-  module ActiveModel
-    module Validations
-      # Enable usage via validates :url, domain: { validation: :standard }
-      module HelperMethods
-        def validates_domain(*attr_names)
-          validates_with DomainExtractor::DomainValidator, _merge_attributes(attr_names)
-        end
-      end
-    end
-  end
+# Also register in DomainExtractor namespace for backwards compatibility
+module DomainExtractor
+  # DomainValidator is now defined at the top level for Rails autoloading.
+  # This constant provides a reference for explicit usage.
+  #
+  # Validation modes:
+  # - :standard - Validates any valid URL using DomainExtractor.valid?
+  # - :root_domain - Only allows root domains (no subdomains) like https://mysite.com
+  # - :root_or_custom_subdomain - Allows root or custom subdomains, but excludes 'www'
+  #
+  # Optional flags:
+  # - use_protocol (default: true) - Whether protocol (http/https) is required
+  # - use_https (default: true) - Whether https is required (only if use_protocol is true)
+  #
+  # @example Standard validation
+  #   validates :url, domain: { validation: :standard }
+  #
+  # @example Root domain only, no protocol required
+  #   validates :url, domain: { validation: :root_domain, use_protocol: false }
+  DomainValidator = ::DomainValidator
 end

data/lib/domain_extractor/formatter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module DomainExtractor
+  # Formatter provides URL formatting based on validation modes and protocol requirements.
+  #
+  # Formats a URL string according to the specified options:
+  # - Validation modes: :standard, :root_domain, :root_or_custom_subdomain
+  # - Protocol options: use_protocol, use_https
+  # - Trailing slash: use_trailing_slash
+  #
+  # @example Standard formatting
+  #   DomainExtractor.format('https://www.example.com/')
+  #   # => 'https://www.example.com'
+  #
+  # @example Root domain only
+  #   DomainExtractor.format('https://shop.example.com/path', validation: :root_domain)
+  #   # => 'https://example.com'
+  #
+  # @example Without protocol
+  #   DomainExtractor.format('https://example.com', use_protocol: false)
+  #   # => 'example.com'
+  module Formatter
+    VALIDATION_MODES = %i[standard root_domain root_or_custom_subdomain].freeze
+    WWW_SUBDOMAIN = 'www'
+
+    module_function
+
+    # Format a URL according to the specified options
+    #
+    # @param url [String] The URL to format
+    # @param options [Hash] Formatting options
+    # @option options [Symbol] :validation (:standard) Validation mode
+    # @option options [Boolean] :use_protocol (true) Include protocol in output
+    # @option options [Boolean] :use_https (true) Use https instead of http
+    # @option options [Boolean] :use_trailing_slash (false) Include trailing slash
+    # @return [String, nil] Formatted URL or nil if invalid
+    def call(url, **options)
+      validation = options.fetch(:validation, :standard)
+      use_protocol = options.fetch(:use_protocol, true)
+      use_https = options.fetch(:use_https, true)
+      use_trailing_slash = options.fetch(:use_trailing_slash, false)
+
+      validate_options!(validation)
+
+      # Parse the URL
+      parsed = DomainExtractor.parse(url)
+      return nil unless parsed.valid?
+
+      # Build the formatted URL based on validation mode
+      formatted_host = build_host(parsed, validation)
+      build_url(formatted_host, use_protocol, use_https, use_trailing_slash)
+    end
+
+    def validate_options!(validation)
+      return if VALIDATION_MODES.include?(validation)
+
+      raise ArgumentError, "Invalid validation mode: #{validation}. " \
+                           "Must be one of: #{VALIDATION_MODES.join(', ')}"
+    end
+    private_class_method :validate_options!
+
+    # Build the host portion based on validation mode
+    def build_host(parsed, validation)
+      case validation
+      when :standard
+        # Return the full host as-is
+        parsed.host
+      when :root_domain
+        # Return only the root domain (no subdomains)
+        parsed.root_domain
+      when :root_or_custom_subdomain
+        # Return root domain or custom subdomain (strip www)
+        if parsed.subdomain == WWW_SUBDOMAIN
+          parsed.root_domain
+        else
+          parsed.host
+        end
+      end
+    end
+    private_class_method :build_host
+
+    # Build the final URL string with protocol and trailing slash options
+    def build_url(host, use_protocol, use_https, use_trailing_slash)
+      url = ''
+
+      # Add protocol if requested
+      if use_protocol
+        protocol = use_https ? 'https://' : 'http://'
+        url = protocol + host
+      else
+        url = host
+      end
+
+      # Add or remove trailing slash
+      if use_trailing_slash
+        url += '/' unless url.end_with?('/')
+      else
+        url = url.chomp('/')
+      end
+
+      url
+    end
+    private_class_method :build_url
+  end
+end

data/lib/domain_extractor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DomainExtractor
-  VERSION = '0.2.5'
+  VERSION = '0.2.7'
 end

data/lib/domain_extractor.rb

@@ -8,6 +8,7 @@ require_relative 'domain_extractor/errors'
 require_relative 'domain_extractor/parsed_url'
 require_relative 'domain_extractor/parser'
 require_relative 'domain_extractor/query_params'
+require_relative 'domain_extractor/formatter'
 
 # Conditionally load Rails validator if ActiveModel is available
 begin
@@ -70,6 +71,32 @@ module DomainExtractor
       QueryParams.call(query_string)
     end
 
+    # Format a URL according to the specified options.
+    # Returns a formatted URL string or nil if the input is invalid.
+    #
+    # @param url [String] The URL to format
+    # @param options [Hash] Formatting options
+    # @option options [Symbol] :validation (:standard) Validation mode
+    # @option options [Boolean] :use_protocol (true) Include protocol in output
+    # @option options [Boolean] :use_https (true) Use https instead of http
+    # @option options [Boolean] :use_trailing_slash (false) Include trailing slash
+    # @return [String, nil]
+    #
+    # @example Standard formatting
+    #   DomainExtractor.format('https://www.example.com/')
+    #   # => 'https://www.example.com'
+    #
+    # @example Root domain only
+    #   DomainExtractor.format('https://shop.example.com/path', validation: :root_domain)
+    #   # => 'https://example.com'
+    #
+    # @example Without protocol
+    #   DomainExtractor.format('https://example.com', use_protocol: false)
+    #   # => 'example.com'
+    def format(url, **)
+      Formatter.call(url, **)
+    end
+
     alias parse_query parse_query_params
   end
 end

data/spec/domain_validator_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-RSpec.describe DomainExtractor::DomainValidator do
+RSpec.describe DomainValidator do
   # Mock record class for testing
   let(:record_class) do
     Class.new do

data/spec/formatter_spec.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe DomainExtractor::Formatter do
+  describe '.call' do
+    context 'with :standard validation mode' do
+      it 'formats a simple URL with default options' do
+        result = described_class.call('https://example.com')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'removes trailing slash by default' do
+        result = described_class.call('https://example.com/')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'preserves subdomains' do
+        result = described_class.call('https://shop.example.com')
+        expect(result).to eq('https://shop.example.com')
+      end
+
+      it 'preserves www subdomain' do
+        result = described_class.call('https://www.example.com')
+        expect(result).to eq('https://www.example.com')
+      end
+
+      it 'preserves multi-level subdomains' do
+        result = described_class.call('https://api.staging.example.com')
+        expect(result).to eq('https://api.staging.example.com')
+      end
+
+      it 'handles URLs without protocol' do
+        result = described_class.call('example.com')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'strips path from URL' do
+        result = described_class.call('https://example.com/path/to/page')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'strips query parameters from URL' do
+        result = described_class.call('https://example.com?foo=bar')
+        expect(result).to eq('https://example.com')
+      end
+    end
+
+    context 'with :root_domain validation mode' do
+      it 'returns root domain for URL with subdomain' do
+        result = described_class.call('https://shop.example.com', validation: :root_domain)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'returns root domain for URL with www' do
+        result = described_class.call('https://www.example.com', validation: :root_domain)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'returns root domain for URL without subdomain' do
+        result = described_class.call('https://example.com', validation: :root_domain)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'returns root domain for multi-level subdomains' do
+        result = described_class.call('https://api.staging.example.com', validation: :root_domain)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'handles multi-part TLDs' do
+        result = described_class.call('https://shop.example.co.uk', validation: :root_domain)
+        expect(result).to eq('https://example.co.uk')
+      end
+    end
+
+    context 'with :root_or_custom_subdomain validation mode' do
+      it 'preserves root domain' do
+        result = described_class.call('https://example.com', validation: :root_or_custom_subdomain)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'preserves custom subdomains' do
+        result = described_class.call('https://shop.example.com', validation: :root_or_custom_subdomain)
+        expect(result).to eq('https://shop.example.com')
+      end
+
+      it 'strips www subdomain' do
+        result = described_class.call('https://www.example.com', validation: :root_or_custom_subdomain)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'preserves api subdomain' do
+        result = described_class.call('https://api.example.com', validation: :root_or_custom_subdomain)
+        expect(result).to eq('https://api.example.com')
+      end
+
+      it 'preserves multi-level custom subdomains' do
+        result = described_class.call('https://api.staging.example.com', validation: :root_or_custom_subdomain)
+        expect(result).to eq('https://api.staging.example.com')
+      end
+    end
+
+    context 'with use_protocol option' do
+      it 'includes protocol by default' do
+        result = described_class.call('https://example.com')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'includes protocol when use_protocol is true' do
+        result = described_class.call('https://example.com', use_protocol: true)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'excludes protocol when use_protocol is false' do
+        result = described_class.call('https://example.com', use_protocol: false)
+        expect(result).to eq('example.com')
+      end
+
+      it 'excludes protocol with subdomain' do
+        result = described_class.call('https://shop.example.com', use_protocol: false)
+        expect(result).to eq('shop.example.com')
+      end
+
+      it 'works with root_domain validation' do
+        result = described_class.call('https://shop.example.com',
+                                      validation: :root_domain,
+                                      use_protocol: false)
+        expect(result).to eq('example.com')
+      end
+    end
+
+    context 'with use_https option' do
+      it 'uses https by default' do
+        result = described_class.call('http://example.com')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'uses https when use_https is true' do
+        result = described_class.call('http://example.com', use_https: true)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'uses http when use_https is false' do
+        result = described_class.call('https://example.com', use_https: false)
+        expect(result).to eq('http://example.com')
+      end
+
+      it 'preserves http when use_https is false' do
+        result = described_class.call('http://example.com', use_https: false)
+        expect(result).to eq('http://example.com')
+      end
+
+      it 'ignores use_https when use_protocol is false' do
+        result = described_class.call('https://example.com',
+                                      use_protocol: false,
+                                      use_https: false)
+        expect(result).to eq('example.com')
+      end
+    end
+
+    context 'with use_trailing_slash option' do
+      it 'removes trailing slash by default' do
+        result = described_class.call('https://example.com/')
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'removes trailing slash when use_trailing_slash is false' do
+        result = described_class.call('https://example.com/', use_trailing_slash: false)
+        expect(result).to eq('https://example.com')
+      end
+
+      it 'adds trailing slash when use_trailing_slash is true' do
+        result = described_class.call('https://example.com', use_trailing_slash: true)
+        expect(result).to eq('https://example.com/')
+      end
+
+      it 'preserves trailing slash when use_trailing_slash is true' do
+        result = described_class.call('https://example.com/', use_trailing_slash: true)
+        expect(result).to eq('https://example.com/')
+      end
+
+      it 'works without protocol' do
+        result = described_class.call('https://example.com',
+                                      use_protocol: false,
+                                      use_trailing_slash: true)
+        expect(result).to eq('example.com/')
+      end
+
+      it 'works with root_domain validation' do
+        result = described_class.call('https://shop.example.com',
+                                      validation: :root_domain,
+                                      use_trailing_slash: true)
+        expect(result).to eq('https://example.com/')
+      end
+    end
+
+    context 'with combined options' do
+      it 'formats with all options: root_domain, no protocol, with trailing slash' do
+        result = described_class.call('https://shop.example.com/path',
+                                      validation: :root_domain,
+                                      use_protocol: false,
+                                      use_trailing_slash: true)
+        expect(result).to eq('example.com/')
+      end
+
+      it 'formats with root_or_custom_subdomain, http protocol, no trailing slash' do
+        result = described_class.call('https://www.example.com/',
+                                      validation: :root_or_custom_subdomain,
+                                      use_https: false,
+                                      use_trailing_slash: false)
+        expect(result).to eq('http://example.com')
+      end
+
+      it 'formats with standard, no protocol, http, with trailing slash' do
+        result = described_class.call('https://api.example.com',
+                                      validation: :standard,
+                                      use_protocol: false,
+                                      use_trailing_slash: true)
+        expect(result).to eq('api.example.com/')
+      end
+
+      it 'strips www and adds trailing slash' do
+        result = described_class.call('https://www.example.com',
+                                      validation: :root_or_custom_subdomain,
+                                      use_trailing_slash: true)
+        expect(result).to eq('https://example.com/')
+      end
+    end
+
+    context 'with multi-part TLDs' do
+      it 'handles UK domains with standard mode' do
+        result = described_class.call('https://shop.example.co.uk')
+        expect(result).to eq('https://shop.example.co.uk')
+      end
+
+      it 'handles UK domains with root_domain mode' do
+        result = described_class.call('https://shop.example.co.uk', validation: :root_domain)
+        expect(result).to eq('https://example.co.uk')
+      end
+
+      it 'handles Australian domains' do
+        result = described_class.call('https://www.example.com.au',
+                                      validation: :root_or_custom_subdomain)
+        expect(result).to eq('https://example.com.au')
+      end
+    end
+
+    context 'with invalid input' do
+      it 'returns nil for invalid URLs' do
+        result = described_class.call('not-a-url')
+        expect(result).to be_nil
+      end
+
+      it 'returns nil for nil input' do
+        result = described_class.call(nil)
+        expect(result).to be_nil
+      end
+
+      it 'returns nil for empty string' do
+        result = described_class.call('')
+        expect(result).to be_nil
+      end
+
+      it 'returns nil for IP addresses' do
+        result = described_class.call('https://192.168.1.1')
+        expect(result).to be_nil
+      end
+    end
+
+    context 'with error handling' do
+      it 'raises error for invalid validation mode' do
+        expect do
+          described_class.call('https://example.com', validation: :invalid_mode)
+        end.to raise_error(ArgumentError, /Invalid validation mode/)
+      end
+    end
+  end
+end
+
+RSpec.describe DomainExtractor do
+  describe '.format' do
+    it 'delegates to Formatter.call' do
+      result = DomainExtractor.format('https://www.example.com/')
+      expect(result).to eq('https://www.example.com')
+    end
+
+    it 'passes options correctly' do
+      result = DomainExtractor.format('https://shop.example.com',
+                                      validation: :root_domain,
+                                      use_protocol: false)
+      expect(result).to eq('example.com')
+    end
+
+    it 'returns nil for invalid URLs' do
+      result = DomainExtractor.format('invalid-url')
+      expect(result).to be_nil
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: domain_extractor
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - OpenSite AI
@@ -43,6 +43,7 @@ files:
 - lib/domain_extractor.rb
 - lib/domain_extractor/domain_validator.rb
 - lib/domain_extractor/errors.rb
+- lib/domain_extractor/formatter.rb
 - lib/domain_extractor/normalizer.rb
 - lib/domain_extractor/parsed_url.rb
 - lib/domain_extractor/parser.rb
@@ -52,6 +53,7 @@ files:
 - lib/domain_extractor/version.rb
 - spec/domain_extractor_spec.rb
 - spec/domain_validator_spec.rb
+- spec/formatter_spec.rb
 - spec/parsed_url_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/opensite-ai/domain_extractor