is_it_spam_rails 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e52a3a701411ca162d602b08ef9672ef5e4fadcb8852021af50777a555a76b82
+  data.tar.gz: 90f33118154bf77776ba35778e662512ae3c6ca8569a38c7bc1d5c20f36591ca
+SHA512:
+  metadata.gz: 3c6060a1e7d1dff377d55e699d71cc662dc447713e914b6da8e5cfe403ac4c2788f0438e8ae49641b6a487ae77049dc5320de4677eae0e22451958b6dec72978
+  data.tar.gz: 0f57ee01f7cff1f90c590c728a1de6faa44c83126b637f144f905bb19166dfe2bdcbcb1f76781673ce21c80ee25efcb687173cb944d0f376cf9471181c0b3ccc

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+## [Unreleased]
+
+## [2.0.0] - TBD
+
+### ⚠️ Breaking Changes
+- **IP tracking is now ON by default** - The gem automatically captures and sends end user IP addresses (`request.remote_ip`) to the API
+  - End user IPs are tracked for spam detection and blocking across all apps
+  - To disable: set `config.track_end_user_ip = false` in your initializer
+  - Review your privacy policy before upgrading - IP addresses are personal data under GDPR
+  - Existing apps upgrading from 0.1.x will start tracking IPs immediately upon deployment
+
+### Added
+- **End user IP tracking** - Capture the actual IP address of the person filling out your form
+  - New configuration option: `track_end_user_ip` (default: true)
+  - Sends `end_user_ip` parameter to API for IP-based spam blocking
+  - Enables blocking malicious users across your entire hosting system
+  - IP tracking can be disabled per-app via configuration
+  - Backward compatible with is-it-spam.com API (falls back to server IP if not provided)
+
+### Changed
+- `Client#check_spam` now accepts optional `end_user_ip:` parameter
+- `IsItSpamRails.check_spam` module method now accepts optional `end_user_ip:` parameter
+- Controller extension automatically captures `request.remote_ip` when tracking is enabled
+
+### Privacy & GDPR
+- End user IP addresses are now sent to is-it-spam.com by default
+- IPs are stored in spam check logs for spam detection and analytics
+- Legal basis: Legitimate interest (spam prevention)
+- Users can opt-out with `config.track_end_user_ip = false`
+- App owners should update privacy policies to disclose IP tracking
+
+## [0.1.0] - 2025-06-14
+
+### Added
+- Rails integration gem for is-it-spam.com anti-spam service
+- `is_it_spam` controller method with before_action hooks
+- Manual spam handling mode (returns @spam_check_result for custom handling)
+- Automatic spam handling mode with `on_spam` configuration for redirects
+- Rails configuration through credentials and environment variables
+- HTTP client with comprehensive error handling and rate limiting
+- Rails Railtie for automatic controller extension inclusion
+- Rails generator for easy setup
+- Comprehensive test suite with Rails integration testing
+- Support for nested parameter extraction (contact, commission, inquiry forms)
+- Configurable API timeouts and base URL
+- Rails logger integration for error reporting
+
+### Features
+- **Controller Integration**: Simple `is_it_spam only: [:create], on_spam: { redirect_to: root_path, notice: 'message' }` API
+- **Flexible Configuration**: Rails credentials, environment variables, or manual configuration
+- **Error Handling**: Graceful degradation with proper logging on API failures
+- **Rails Native**: Uses ActiveSupport::Concern and Rails conventions
+- **Production Ready**: Comprehensive error handling and logging

data/CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Ruby gem that provides Rails integration for the is-it-spam.com anti-spam service. The gem adds `check_spam` before_action hooks to Rails controllers for automatic spam detection.
+
+## Architecture
+
+The gem follows a modular architecture:
+
+- **Core API Client** (`lib/is_it_spam_rails/client.rb`) - HTTP client for is-it-spam.com API
+- **Configuration** (`lib/is_it_spam_rails/configuration.rb`) - Handles API credentials and settings
+- **Rails Integration** (`lib/is_it_spam_rails/railtie.rb`) - Integrates with Rails through Railtie
+- **Controller Extension** (`lib/is_it_spam_rails/controller_extension.rb`) - Adds `check_spam` method to controllers
+- **Spam Checker** (`lib/is_it_spam_rails/spam_checker.rb`) - Core spam checking logic
+- **Rails Generator** (`lib/generators/is_it_spam_rails/install_generator.rb`) - Creates initializer file
+
+## Commands
+
+### Testing
+```bash
+rake test                           # Run all tests
+rake test test/test_client.rb       # Run specific test file
+```
+
+### Development
+```bash
+bin/setup                          # Install dependencies
+bin/console                        # Start interactive console
+bundle install                    # Install gem dependencies
+```
+
+### Gem Tasks
+```bash
+rake build                         # Build the gem
+rake install                       # Install locally
+rake release                       # Release to RubyGems
+```
+
+### Rails Integration Testing
+```bash
+bin/rails is_it_spam:test_connection    # Test API connection
+bin/rails is_it_spam:test_spam_check   # Test spam detection
+bin/rails is_it_spam:config            # Show configuration
+bin/rails is_it_spam:install           # Install initializer
+```
+
+## Development Notes
+
+- Uses Minitest for testing with WebMock for HTTP stubbing
+- All methods should include YARD documentation
+- Classes should have description comments
+- Environment variables: `IS_IT_SPAM_API_KEY`, `IS_IT_SPAM_API_SECRET`, `IS_IT_SPAM_BASE_URL`
+- Rails credentials path: `is_it_spam_rails.api_key`, `is_it_spam_rails.api_secret`
+- Gem supports Rails 6.0+ and Ruby 3.1+
+- Uses HTTParty for HTTP requests
+- Configuration auto-loads from Rails credentials or environment variables

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Benjamin Deutscher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,253 @@
+# IsItSpamRails
+
+Rails integration gem for [is-it-spam.com](https://is-it-spam.com) anti-spam service. Provides easy-to-use before_action hooks for automatic spam detection in your Rails controllers.
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem 'is_it_spam_rails'
+```
+
+Then execute:
+
+```bash
+$ bundle install
+```
+
+Run the installer to create the initializer:
+
+```bash
+$ bin/rails is_it_spam:install
+```
+
+## Configuration
+
+Configure your API credentials in `config/initializers/is_it_spam_rails.rb`:
+
+### Option 1: Rails Credentials (Recommended)
+
+```bash
+$ rails credentials:edit
+```
+
+Add your credentials:
+
+```yaml
+is_it_spam_rails:
+  api_key: your_api_key_here
+  api_secret: your_api_secret_here
+  base_url: https://is-it-spam.com  # optional
+```
+
+Then in your initializer:
+
+```ruby
+IsItSpamRails.configure do |config|
+  config.api_key = Rails.application.credentials.is_it_spam_rails[:api_key]
+  config.api_secret = Rails.application.credentials.is_it_spam_rails[:api_secret]
+end
+```
+
+### Option 2: Environment Variables
+
+Set environment variables:
+
+```bash
+export IS_IT_SPAM_API_KEY=your_api_key_here
+export IS_IT_SPAM_API_SECRET=your_api_secret_here
+export IS_IT_SPAM_BASE_URL=https://is-it-spam.com  # optional
+```
+
+The gem will automatically use these if no explicit configuration is provided.
+
+### End User IP Tracking
+
+By default, the gem tracks the IP address of the person filling out your form (`request.remote_ip`) and sends it to the is-it-spam.com API for IP-based spam blocking.
+
+**Privacy Considerations:**
+- End user IPs are stored in spam check logs for analytics and spam detection
+- IPs can be blocked at system, user, or app level
+- Consider your privacy policy and GDPR requirements when deploying this feature
+
+**Configuration:**
+
+```ruby
+IsItSpamRails.configure do |config|
+  config.api_key = "your_api_key"
+  config.api_secret = "your_api_secret"
+  config.track_end_user_ip = true  # Default: true
+end
+```
+
+**To disable IP tracking:**
+
+```ruby
+IsItSpamRails.configure do |config|
+  config.api_key = "your_api_key"
+  config.api_secret = "your_api_secret"
+  config.track_end_user_ip = false  # Disable end user IP tracking
+end
+```
+
+When disabled, the API will still receive the server's IP address (for rate limiting purposes), but individual form submitters won't be tracked.
+
+**Breaking Change:** Starting with version 2.0.0, IP tracking is **ON by default**. If you upgrade from an earlier version, end user IPs will automatically be tracked unless you explicitly disable it. Review your privacy policy before upgrading.
+
+## Usage
+
+### Basic Usage
+
+Add spam checking to your controllers with the `is_it_spam` method. By default, the gem sets `@spam_check_result` and lets you handle spam detection manually:
+
+```ruby
+class ContactController < ApplicationController
+  is_it_spam only: [:create]
+  
+  def create
+    # Check if spam was detected
+    if @spam_check_result&.spam?
+      # Handle spam manually
+      flash[:alert] = "Your submission appears to be spam"
+      redirect_to root_path
+      return
+    end
+    
+    # Process legitimate submissions
+    confidence = @spam_check_result&.confidence_score
+    Rails.logger.info "Legitimate submission with #{(confidence * 100).round(1)}% confidence"
+    # ...
+  end
+end
+```
+
+### Automatic Spam Handling
+
+For automatic spam handling, use the `on_spam` configuration to redirect spam submissions:
+
+```ruby
+class ContactController < ApplicationController
+  is_it_spam only: [:create], on_spam: {
+    redirect_to: root_path,
+    notice: 'Thank you for your message'
+  }
+  
+  def create
+    # This action only executes for legitimate (non-spam) submissions
+    # @spam_check_result is available and will never be spam
+    
+    # Process the legitimate submission
+    # ...
+  end
+end
+```
+
+### Configuration Options
+
+The `on_spam` hash accepts the following options:
+
+```ruby
+class ContactController < ApplicationController
+  is_it_spam only: [:create], on_spam: {
+    redirect_to: root_path,           # Path to redirect on spam detection
+    notice: 'Thank you for contacting us'  # Flash notice message
+  }
+end
+```
+
+You can also use `alert` instead of `notice`:
+
+```ruby
+class ContactController < ApplicationController
+  is_it_spam only: [:create], on_spam: {
+    redirect_to: root_path,
+    alert: 'There was an issue with your submission'
+  }
+end
+```
+
+### Dynamic Redirect Paths
+
+Use route helpers or callable objects for dynamic paths:
+
+```ruby
+class ContactController < ApplicationController
+  is_it_spam only: [:create], on_spam: {
+    redirect_to: Rails.application.routes.url_helpers.root_path,
+    notice: I18n.t('contact.success')
+  }
+end
+```
+
+### Parameter Detection
+
+The gem automatically detects form parameters from common nested keys:
+- `:commission`, `:contact`, `:inquiry`, `:message`, `:form`
+- Maps `name`, `email`, and `message` fields
+- Supports `first_name`/`last_name` combination for name field
+
+## Testing and Debugging
+
+The gem includes rake tasks for testing your configuration:
+
+```bash
+# Test API connection
+$ bin/rails is_it_spam:test_connection
+
+# Test spam detection with sample data
+$ bin/rails is_it_spam:test_spam_check
+
+# Show current configuration
+$ bin/rails is_it_spam:config
+```
+
+## API
+
+### Direct API Usage
+
+You can also use the API directly without the before_action:
+
+```ruby
+result = IsItSpamRails.check_spam(
+  name: "John Doe",
+  email: "john@example.com", 
+  message: "Your message here",
+  custom_fields: { company: "Acme Corp" }
+)
+
+if result.spam?
+  puts "Spam detected: #{result.spam_reasons.join(', ')}"
+  puts "Confidence: #{(result.confidence_score * 100).round(1)}%"
+else
+  puts "Message appears legitimate"
+end
+```
+
+### Health Check
+
+Check if the API service is available:
+
+```ruby
+if IsItSpamRails.health_check
+  puts "API is healthy"
+else
+  puts "API is not responding"
+end
+```
+
+## Error Handling
+
+The gem is designed to fail gracefully. If the API is unavailable, rate limited, or returns errors, your application will continue to function normally. Errors are logged but don't block legitimate users.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/its-benjamin-deutscher/is-it-spam.com.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/generators/is_it_spam_rails/install_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module IsItSpamRails
+  module Generators
+    # Rails generator for installing IsItSpamRails
+    #
+    # Creates an initializer file with configuration template
+    class InstallGenerator < Rails::Generators::Base
+      desc "Install IsItSpamRails by creating an initializer"
+
+      # Define source location for templates
+      source_root File.expand_path("templates", __dir__)
+
+      # Create the initializer file
+      #
+      # @return [void]
+      def create_initializer
+        template "initializer.rb", "config/initializers/is_it_spam_rails.rb"
+      end
+
+      # Display installation instructions
+      #
+      # @return [void]
+      def show_instructions
+        say ""
+        say "IsItSpamRails has been installed!", :green
+        say ""
+        say "Next steps:"
+        say "1. Configure your API credentials in config/initializers/is_it_spam_rails.rb"
+        say "2. Add your credentials to Rails credentials or environment variables"
+        say "3. Use is_it_spam in your controllers as a before_action"
+        say ""
+        say "Example usage in a controller:"
+        say "  class ContactController < ApplicationController"
+        say "    is_it_spam only: [:create], on_spam: {"
+        say "      redirect_to: root_path,"
+        say "      notice: 'Thank you for your message'"
+        say "    }"
+        say "  end"
+        say ""
+        say "For more information, visit: https://is-it-spam.com/docs"
+      end
+    end
+  end
+end

data/lib/generators/is_it_spam_rails/templates/initializer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Configuration for IsItSpamRails gem
+# 
+# This initializer configures the connection to the is-it-spam.com API
+# for automated spam detection in your Rails application.
+#
+# For more information, visit: https://is-it-spam.com/docs
+
+IsItSpamRails.configure do |config|
+  # Your API credentials from is-it-spam.com
+  # You can get these from your dashboard at https://is-it-spam.com/dashboard
+  
+  # Option 1: Use Rails credentials (recommended)
+  # Run: rails credentials:edit
+  # Add:
+  #   is_it_spam_rails:
+  #     api_key: your_api_key_here
+  #     api_secret: your_api_secret_here
+  #     base_url: https://is-it-spam.com  # optional, defaults to production
+  #
+  # Then uncomment these lines:
+  # config.api_key = Rails.application.credentials.is_it_spam_rails[:api_key]
+  # config.api_secret = Rails.application.credentials.is_it_spam_rails[:api_secret]
+  # config.base_url = Rails.application.credentials.is_it_spam_rails[:base_url] # optional
+  
+  # Option 2: Use environment variables
+  # Set these in your environment:
+  # IS_IT_SPAM_API_KEY=your_api_key_here
+  # IS_IT_SPAM_API_SECRET=your_api_secret_here
+  # IS_IT_SPAM_BASE_URL=https://is-it-spam.com  # optional
+  #
+  # Then uncomment these lines:
+  # config.api_key = ENV["IS_IT_SPAM_API_KEY"]
+  # config.api_secret = ENV["IS_IT_SPAM_API_SECRET"]
+  # config.base_url = ENV["IS_IT_SPAM_BASE_URL"] # optional
+  
+  # Option 3: Direct configuration (not recommended for production)
+  # config.api_key = "your_api_key_here"
+  # config.api_secret = "your_api_secret_here"
+  
+  # Optional configuration
+  # config.base_url = "https://is-it-spam.com"  # API base URL
+  # config.timeout = 30                         # Request timeout in seconds
+  # config.logger = Rails.logger                # Logger for debugging
+end
+
+# Usage in controllers:
+#
+# class ContactController < ApplicationController
+#   # Basic usage - detects spam and redirects with notice
+#   check_spam only: :create
+#   
+#   # Custom configuration
+#   check_spam only: :create, 
+#              redirect_path: root_path, 
+#              notice: "Thank you for your message"
+#   
+#   # With custom parameter mapping
+#   check_spam only: :create,
+#              param_key: :contact_form,  # if your params are nested under contact_form
+#              custom_fields: {           # map additional fields
+#                company: :company_name,
+#                phone: :phone_number
+#              }
+#   
+#   def create
+#     # Your normal controller logic
+#     # Spam checking happens automatically before this action
+#     
+#     # You can access the spam check result if needed:
+#     # @spam_check_result.spam? 
+#     # @spam_check_result.confidence_score
+#     # @spam_check_result.spam_reasons
+#   end
+# end

data/lib/is_it_spam_rails/client.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module IsItSpamRails
+  # Main client class for interacting with the Is It Spam API
+  #
+  # Provides methods for checking spam and communicating with the API
+  class Client
+    include HTTParty
+
+    # API version
+    API_VERSION = "v1"
+    # Default timeout for requests
+    DEFAULT_TIMEOUT = 30
+
+    # Initialize client with credentials
+    #
+    # @param api_key [String] Your API key from Is It Spam
+    # @param api_secret [String] Your API secret from Is It Spam
+    # @param base_url [String] Base URL for the API (default: https://is-it-spam.com)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @raise [ConfigurationError] When credentials are missing
+    def initialize(api_key:, api_secret:, base_url: "https://is-it-spam.com", timeout: DEFAULT_TIMEOUT)
+      @api_key = api_key
+      @api_secret = api_secret
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+
+      validate_credentials!
+
+      self.class.base_uri @base_url
+      self.class.default_timeout @timeout
+    end
+
+    # Check if the provided content is spam
+    #
+    # @param name [String] Name from the contact form
+    # @param email [String] Email address from the contact form
+    # @param message [String] Message content from the contact form
+    # @param custom_fields [Hash] Additional custom fields to check (optional)
+    # @param end_user_ip [String, nil] IP address of the end user filling the form (optional)
+    # @return [SpamCheckResult] The result of the spam check
+    # @raise [ValidationError] When required parameters are missing or invalid
+    # @raise [ApiError] When the API returns an error
+    # @raise [RateLimitError] When rate limits are exceeded
+    def check_spam(name:, email:, message:, custom_fields: {}, end_user_ip: nil)
+      validate_required_params(name: name, email: email, message: message)
+
+      payload = {
+        spam_check: {
+          name: name,
+          email: email,
+          message: message,
+          additional_fields: custom_fields
+        }
+      }
+
+      # Only include end_user_ip if tracking is enabled and IP is provided
+      if IsItSpamRails.configuration.track_end_user_ip && end_user_ip.present?
+        payload[:spam_check][:end_user_ip] = end_user_ip
+      end
+
+      response = make_request(:post, "/api/#{API_VERSION}/spam_checks", body: payload.to_json)
+      SpamCheckResult.new(response.parsed_response)
+    end
+
+    # Check the health of the API service
+    #
+    # @return [Boolean] true if the service is healthy
+    # @raise [ApiError] When the API is unavailable
+    def health_check
+      make_request(:get, "/up")
+      true
+    rescue ApiError => e
+      raise e unless e.status_code == 503
+      false
+    end
+
+    private
+
+    # Validate that API credentials are present
+    #
+    # @raise [ConfigurationError] When credentials are missing
+    def validate_credentials!
+      raise ConfigurationError, "API key is required" if @api_key.nil? || @api_key.empty?
+      raise ConfigurationError, "API secret is required" if @api_secret.nil? || @api_secret.empty?
+    end
+
+    # Validate required parameters for spam checking
+    #
+    # @param name [String] Name parameter
+    # @param email [String] Email parameter
+    # @param message [String] Message parameter
+    # @raise [ValidationError] When parameters are invalid
+    def validate_required_params(name:, email:, message:)
+      errors = {}
+
+      errors[:name] = ["can't be blank"] if name.nil? || name.empty?
+      errors[:email] = ["can't be blank"] if email.nil? || email.empty?
+      errors[:message] = ["can't be blank"] if message.nil? || message.empty?
+
+      # Basic email format validation
+      if email && !email.match?(/\A[^@\s]+@[^@\s]+\z/)
+        errors[:email] = (errors[:email] || []) << "is not a valid email address"
+      end
+
+      unless errors.empty?
+        raise ValidationError.new("Validation failed", errors: errors)
+      end
+    end
+
+    # Make an HTTP request to the API
+    #
+    # @param method [Symbol] HTTP method (:get, :post, etc.)
+    # @param path [String] API endpoint path
+    # @param options [Hash] Additional request options
+    # @return [HTTParty::Response] HTTP response object
+    # @raise [ApiError, RateLimitError, ValidationError] Based on response
+    def make_request(method, path, **options)
+      request_options = {
+        headers: {
+          "Content-Type" => "application/json",
+          "X-API-Key" => @api_key,
+          "X-API-Secret" => @api_secret,
+          "User-Agent" => "IsItSpam Rails Gem #{IsItSpamRails::VERSION}"
+        }
+      }.merge(options)
+
+      response = self.class.send(method, path, request_options)
+      handle_response(response)
+    end
+
+    # Handle API response and raise appropriate errors
+    #
+    # @param response [HTTParty::Response] HTTP response object
+    # @return [HTTParty::Response] Response for successful requests
+    # @raise [ApiError, RateLimitError, ValidationError] Based on status code
+    def handle_response(response)
+      case response.code
+      when 200..299
+        response
+      when 400
+        handle_error_response(response, ApiError)
+      when 401
+        handle_error_response(response, ApiError)
+      when 404
+        raise ApiError.new("Endpoint not found", status_code: 404, response_body: response.body)
+      when 422
+        handle_validation_error(response)
+      when 429
+        handle_error_response(response, RateLimitError)
+      when 500..599
+        handle_error_response(response, ApiError)
+      else
+        raise ApiError.new("Unexpected response code: #{response.code}",
+                          status_code: response.code,
+                          response_body: response.body)
+      end
+    end
+
+    # Handle error responses with JSON body
+    #
+    # @param response [HTTParty::Response] HTTP response object
+    # @param error_class [Class] Error class to raise
+    # @raise [ApiError, RateLimitError] Specified error class
+    def handle_error_response(response, error_class)
+      begin
+        error_data = response.parsed_response
+        message = error_data["error"] || "API request failed"
+      rescue
+        message = "API request failed"
+      end
+
+      raise error_class.new(message, status_code: response.code, response_body: response.body)
+    end
+
+    # Handle validation error responses
+    #
+    # @param response [HTTParty::Response] HTTP response object
+    # @raise [ValidationError] With field-specific errors
+    def handle_validation_error(response)
+      begin
+        error_data = response.parsed_response
+        message = error_data["error"] || "Validation failed"
+        errors = error_data["errors"] || {}
+      rescue
+        message = "Validation failed"
+        errors = {}
+      end
+
+      raise ValidationError.new(message, errors: errors, status_code: 422, response_body: response.body)
+    end
+  end
+
+  # Represents the result of a spam check operation
+  #
+  # Provides convenient methods for accessing spam detection results
+  class SpamCheckResult
+    # @return [Boolean] Whether content was identified as spam
+    attr_reader :spam
+    # @return [Float] Confidence score between 0.0 and 1.0
+    attr_reader :confidence
+    # @return [Array<String>] Reasons why content was flagged as spam
+    attr_reader :reasons
+
+    # Initialize spam check result
+    #
+    # @param data [Hash] Response data from the API
+    def initialize(data)
+      @spam = data["spam"]
+      @confidence = data["confidence"].to_f
+      @reasons = (data["reasons"] || []).dup.freeze
+    end
+
+    # Check if content was identified as spam
+    #
+    # @return [Boolean] true if content was identified as spam
+    def spam?
+      @spam
+    end
+
+    # Check if content appears legitimate
+    #
+    # @return [Boolean] true if content appears legitimate
+    def legitimate?
+      !spam?
+    end
+
+    # Get confidence score
+    #
+    # @return [Float] Confidence score between 0.0 and 1.0
+    def confidence_score
+      @confidence
+    end
+
+    # Get reasons for spam detection
+    #
+    # @return [Array<String>] Reasons why content was flagged as spam
+    def spam_reasons
+      @reasons
+    end
+
+    # Get human-readable summary of the result
+    #
+    # @return [String] Human-readable summary of the result
+    def summary
+      if spam?
+        "Spam detected (#{(@confidence * 100).round(1)}% confidence): #{@reasons.join(', ')}"
+      else
+        "Content appears legitimate (#{(@confidence * 100).round(1)}% confidence)"
+      end
+    end
+
+    # Convert result to hash
+    #
+    # @return [Hash] Hash representation of the result
+    def to_h
+      {
+        spam: @spam,
+        confidence: @confidence,
+        reasons: @reasons
+      }
+    end
+
+    # Convert result to JSON
+    #
+    # @param args [Array] Arguments passed to to_json
+    # @return [String] JSON representation of the result
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/is_it_spam_rails/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module IsItSpamRails
+  # Configuration class for IsItSpamRails gem
+  #
+  # Handles global configuration settings for the Rails integration
+  class Configuration
+    # @return [String, nil] API key for authentication
+    attr_accessor :api_key
+    # @return [String, nil] API secret for authentication
+    attr_accessor :api_secret
+    # @return [String] Base URL for the API
+    attr_accessor :base_url
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+    # @return [Logger, nil] Logger instance for debugging
+    attr_accessor :logger
+    # @return [Boolean] Whether to track end user IP addresses (default: true)
+    attr_accessor :track_end_user_ip
+
+    # Initialize configuration with default values
+    def initialize
+      @base_url = "https://is-it-spam.com"
+      @timeout = 30
+      @logger = rails_logger
+      @track_end_user_ip = true
+    end
+
+    # Get configured client instance
+    #
+    # @return [Client] The configured client
+    # @raise [ConfigurationError] When required configuration is missing
+    def client
+      @client ||= Client.new(
+        api_key: api_key,
+        api_secret: api_secret,
+        base_url: base_url,
+        timeout: timeout
+      )
+    end
+
+    # Reset the client (useful for testing or credential changes)
+    def reset_client!
+      @client = nil
+    end
+
+    # Check if configuration is valid
+    #
+    # @return [Boolean] true if configuration has required values
+    def valid?
+      !api_key.nil? && !api_key.empty? &&
+        !api_secret.nil? && !api_secret.empty?
+    end
+
+    # Validate configuration and raise error if invalid
+    #
+    # @raise [ConfigurationError] When configuration is invalid
+    def validate!
+      raise ConfigurationError, "API key is required" if api_key.nil? || api_key.empty?
+      raise ConfigurationError, "API secret is required" if api_secret.nil? || api_secret.empty?
+    end
+
+    private
+
+    # Get Rails logger if available, nil otherwise
+    #
+    # @return [Logger, nil] Rails logger or nil
+    def rails_logger
+      return nil unless defined?(Rails)
+      return nil unless Rails.respond_to?(:logger)
+      Rails.logger
+    rescue
+      nil
+    end
+  end
+end

data/lib/is_it_spam_rails/controller_extension.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module IsItSpamRails
+  # Controller extension providing spam checking functionality
+  #
+  # Adds the `is_it_spam` class method to Rails controllers for automatic spam detection
+  module ControllerExtension
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Add spam checking as a before_action
+      #
+      # @param options [Hash] Configuration options
+      # @option options [Hash] :on_spam Options for handling spam detection
+      # @option options [String, Proc] :on_spam[:redirect_to] Path to redirect to when spam is detected
+      # @option options [String] :on_spam[:notice] Flash notice message to display
+      # @option options [String] :on_spam[:alert] Flash alert message to display
+      # @option options [Symbol, String] :form_param_name Name of the nested parameter containing form data
+      def is_it_spam(options = {})
+        on_spam_options = options.delete(:on_spam) || {}
+        form_param_name = options.delete(:form_param_name)
+        
+        before_action(options) do
+          check_for_spam(on_spam_options, form_param_name)
+        end
+      end
+    end
+
+    private
+
+    # Check for spam and handle accordingly
+    #
+    # @param on_spam_options [Hash] Options for spam handling
+    # @param form_param_name [Symbol, String, nil] Name of the nested parameter containing form data
+    # @return [void]
+    def check_for_spam(on_spam_options = {}, form_param_name = nil)
+      # Extract form parameters - try custom parameter name first if provided
+      form_params = extract_form_params(form_param_name)
+      
+      # Skip if essential parameters are blank
+      return unless form_params[:name].present? && form_params[:email].present? && form_params[:message].present?
+
+      # Capture end user IP if tracking is enabled and request is available
+      end_user_ip = if IsItSpamRails.configuration.track_end_user_ip && respond_to?(:request) && request.respond_to?(:remote_ip)
+                      request.remote_ip
+                    else
+                      nil
+                    end
+
+      begin
+        @spam_check_result = IsItSpamRails.check_spam(
+          name: form_params[:name],
+          email: form_params[:email],
+          message: form_params[:message],
+          custom_fields: {},
+          end_user_ip: end_user_ip
+        )
+        
+        if @spam_check_result&.spam? && on_spam_options.any?
+          handle_spam_detection(on_spam_options)
+        end
+      rescue IsItSpamRails::ValidationError => e
+        Rails.logger&.warn("Spam check validation failed: #{e.message}")
+      rescue IsItSpamRails::RateLimitError => e
+        Rails.logger&.warn("Spam check rate limit exceeded: #{e.message}")
+      rescue IsItSpamRails::ApiError => e
+        Rails.logger&.error("Spam check API error: #{e.message}")
+      rescue StandardError => e
+        Rails.logger&.error("Spam check unexpected error: #{e.message}")
+      end
+    end
+
+    # Extract form parameters from nested params
+    #
+    # @param form_param_name [Symbol, String, nil] Name of the nested parameter containing form data
+    # @return [Hash] Extracted form parameters
+    def extract_form_params(form_param_name = nil)
+      # First try custom form parameter name if provided
+      if form_param_name && params[form_param_name.to_sym].is_a?(ActionController::Parameters)
+        nested_params = params[form_param_name.to_sym]
+        return {
+          name: nested_params[:name] || nested_params[:first_name] || "#{nested_params[:first_name]} #{nested_params[:last_name]}".strip,
+          email: nested_params[:email],
+          message: nested_params[:message] || nested_params[:body] || nested_params[:content]
+        }
+      end
+      
+      # Try common form parameter keys for backward compatibility
+      common_keys = [:commission, :contact, :inquiry, :message, :form]
+      
+      # Try nested parameters
+      common_keys.each do |key|
+        if params[key].is_a?(ActionController::Parameters)
+          nested_params = params[key]
+          return {
+            name: nested_params[:name] || nested_params[:first_name] || "#{nested_params[:first_name]} #{nested_params[:last_name]}".strip,
+            email: nested_params[:email],
+            message: nested_params[:message] || nested_params[:body] || nested_params[:content]
+          }
+        end
+      end
+      
+      # Fallback to direct parameter access
+      {
+        name: params[:name] || params[:first_name] || "#{params[:first_name]} #{params[:last_name]}".strip,
+        email: params[:email],
+        message: params[:message] || params[:body] || params[:content]
+      }
+    end
+
+    # Handle spam detection by redirecting with flash message
+    #
+    # @param options [Hash] Spam handling options
+    # @return [void]
+    def handle_spam_detection(options = {})
+      redirect_path = options[:redirect_to] || root_path
+      redirect_path = redirect_path.call if redirect_path.respond_to?(:call)
+      
+      flash_options = {}
+      flash_options[:notice] = options[:notice] if options[:notice]
+      flash_options[:alert] = options[:alert] if options[:alert]
+      
+      redirect_to redirect_path, flash_options
+    end
+  end
+end

data/lib/is_it_spam_rails/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module IsItSpamRails
+  # Rails integration through Railtie
+  #
+  # Automatically configures the gem when Rails loads and adds controller helpers
+  class Railtie < Rails::Railtie
+    # Add spam checking functionality to ActionController::Base
+    initializer "is_it_spam_rails.add_controller_helpers" do
+      ActiveSupport.on_load(:action_controller) do
+        include IsItSpamRails::ControllerExtension
+      end
+    end
+
+    # Add rake tasks
+    rake_tasks do
+      load File.expand_path("../tasks/is_it_spam_rails.rake", __dir__)
+    end
+
+    # Add generators
+    generators do
+      require_relative "../generators/is_it_spam_rails/install_generator"
+    end
+  end
+end

data/lib/is_it_spam_rails/version.rb

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

data/lib/is_it_spam_rails.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "is_it_spam_rails/version"
+require_relative "is_it_spam_rails/client"
+require_relative "is_it_spam_rails/configuration"
+require_relative "is_it_spam_rails/controller_extension"
+require_relative "is_it_spam_rails/railtie" if defined?(Rails::Railtie)
+
+# Rails integration gem for is-it-spam.com anti-spam service
+#
+# Provides Rails-specific functionality including:
+# - Configuration through Rails initializers
+# - Before action hooks for controllers
+# - Rails generator for setup
+module IsItSpamRails
+  class Error < StandardError; end
+
+  # Configuration error raised when credentials are missing or invalid
+  class ConfigurationError < Error; end
+
+  # API error raised when the API returns an error response
+  class ApiError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status_code
+    # @return [String, nil] Raw response body
+    attr_reader :response_body
+
+    # Initialize API error
+    #
+    # @param message [String] Error message
+    # @param status_code [Integer, nil] HTTP status code
+    # @param response_body [String, nil] Raw response body
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  # Rate limit error raised when API rate limits are exceeded
+  class RateLimitError < ApiError; end
+
+  # Validation error raised when request parameters are invalid
+  class ValidationError < ApiError
+    # @return [Hash] Field-specific validation errors
+    attr_reader :errors
+
+    # Initialize validation error
+    #
+    # @param message [String] Error message
+    # @param errors [Hash] Field-specific validation errors
+    # @param options [Hash] Additional options
+    def initialize(message, errors: {}, **options)
+      super(message, **options)
+      @errors = errors
+    end
+  end
+
+  # Global configuration for the gem
+  #
+  # @return [Configuration] The global configuration instance
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Configure the gem with a block
+  #
+  # @yield [configuration] Configuration block
+  # @yieldparam configuration [Configuration] The configuration instance
+  def self.configure
+    yield(configuration)
+  end
+
+  # Get the configured client instance
+  #
+  # @return [Client] The configured client
+  def self.client
+    configuration.client
+  end
+
+  # Shortcut method for checking spam
+  #
+  # @param name [String] Name from the contact form
+  # @param email [String] Email address from the contact form
+  # @param message [String] Message content from the contact form
+  # @param custom_fields [Hash] Additional custom fields to check
+  # @param end_user_ip [String, nil] IP address of the end user filling the form (optional)
+  # @return [SpamCheckResult] The result of the spam check
+  def self.check_spam(name:, email:, message:, custom_fields: {}, end_user_ip: nil)
+    client.check_spam(name: name, email: email, message: message, custom_fields: custom_fields, end_user_ip: end_user_ip)
+  end
+
+  # Check API health
+  #
+  # @return [Boolean] true if the service is healthy
+  def self.health_check
+    client.health_check
+  end
+end

data/lib/tasks/is_it_spam_rails.rake

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+namespace :is_it_spam do
+  desc "Install IsItSpamRails by creating an initializer"
+  task :install => :environment do
+    Rails::Generators.invoke("is_it_spam_rails:install")
+  end
+
+  desc "Test connection to Is It Spam API"
+  task :test_connection => :environment do
+    begin
+      puts "Testing connection to Is It Spam API..."
+      
+      if IsItSpamRails.configuration.valid?
+        result = IsItSpamRails.health_check
+        if result
+          puts "✅ Connection successful!"
+          puts "API Key: #{IsItSpamRails.configuration.api_key[0..7]}..."
+          puts "Base URL: #{IsItSpamRails.configuration.base_url}"
+        else
+          puts "❌ API is not healthy (returned false)"
+        end
+      else
+        puts "❌ Configuration is invalid. Please check your API credentials."
+        puts "Current configuration:"
+        puts "  API Key: #{IsItSpamRails.configuration.api_key.present? ? '[SET]' : '[NOT SET]'}"
+        puts "  API Secret: #{IsItSpamRails.configuration.api_secret.present? ? '[SET]' : '[NOT SET]'}"
+        puts "  Base URL: #{IsItSpamRails.configuration.base_url}"
+      end
+    rescue IsItSpamRails::ConfigurationError => e
+      puts "❌ Configuration error: #{e.message}"
+    rescue IsItSpamRails::ApiError => e
+      puts "❌ API error: #{e.message}"
+      puts "Status code: #{e.status_code}" if e.status_code
+    rescue StandardError => e
+      puts "❌ Unexpected error: #{e.message}"
+    end
+  end
+
+  desc "Test spam detection with sample data"
+  task :test_spam_check => :environment do
+    begin
+      puts "Testing spam detection with sample data..."
+      
+      # Test with legitimate content
+      puts "\n--- Testing legitimate content ---"
+      legitimate_result = IsItSpamRails.check_spam(
+        name: "John Doe",
+        email: "john@example.com",
+        message: "I'm interested in your services. Could you please provide more information?"
+      )
+      puts "Result: #{legitimate_result.spam? ? 'SPAM' : 'LEGITIMATE'}"
+      puts "Confidence: #{(legitimate_result.confidence_score * 100).round(1)}%"
+      puts "Reasons: #{legitimate_result.spam_reasons.join(', ')}" if legitimate_result.spam_reasons.any?
+      
+      # Test with spam content
+      puts "\n--- Testing spam content ---"
+      spam_result = IsItSpamRails.check_spam(
+        name: "Spammer",
+        email: "spam@suspicious.com",
+        message: "URGENT!!! FREE MONEY!!! Click here now to get rich quick! Act fast!"
+      )
+      puts "Result: #{spam_result.spam? ? 'SPAM' : 'LEGITIMATE'}"
+      puts "Confidence: #{(spam_result.confidence_score * 100).round(1)}%"
+      puts "Reasons: #{spam_result.spam_reasons.join(', ')}" if spam_result.spam_reasons.any?
+      
+      puts "\n✅ Spam detection test completed!"
+      
+    rescue IsItSpamRails::ConfigurationError => e
+      puts "❌ Configuration error: #{e.message}"
+    rescue IsItSpamRails::ValidationError => e
+      puts "❌ Validation error: #{e.message}"
+      puts "Errors: #{e.errors}" if e.errors.any?
+    rescue IsItSpamRails::ApiError => e
+      puts "❌ API error: #{e.message}"
+      puts "Status code: #{e.status_code}" if e.status_code
+    rescue StandardError => e
+      puts "❌ Unexpected error: #{e.message}"
+    end
+  end
+
+  desc "Show current configuration"
+  task :config => :environment do
+    puts "IsItSpamRails Configuration:"
+    puts "  API Key: #{IsItSpamRails.configuration.api_key.present? ? IsItSpamRails.configuration.api_key[0..7] + '...' : '[NOT SET]'}"
+    puts "  API Secret: #{IsItSpamRails.configuration.api_secret.present? ? '[SET]' : '[NOT SET]'}"
+    puts "  Base URL: #{IsItSpamRails.configuration.base_url}"
+    puts "  Timeout: #{IsItSpamRails.configuration.timeout} seconds"
+    puts "  Valid: #{IsItSpamRails.configuration.valid? ? '✅' : '❌'}"
+  end
+end

data/sig/is_it_spam_rails.rbs

@@ -0,0 +1,4 @@
+module IsItSpamRails
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: is_it_spam_rails
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Benjamin Deutscher
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Provides Rails integration for the is-it-spam.com API with before_action
+  hooks for automatic spam detection in controllers.
+email:
+- ben@bdeutscher.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/is_it_spam_rails/install_generator.rb
+- lib/generators/is_it_spam_rails/templates/initializer.rb
+- lib/is_it_spam_rails.rb
+- lib/is_it_spam_rails/client.rb
+- lib/is_it_spam_rails/configuration.rb
+- lib/is_it_spam_rails/controller_extension.rb
+- lib/is_it_spam_rails/railtie.rb
+- lib/is_it_spam_rails/version.rb
+- lib/tasks/is_it_spam_rails.rake
+- sig/is_it_spam_rails.rbs
+homepage: https://is-it-spam.com
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://is-it-spam.com
+  source_code_uri: https://github.com/its-benjamin-deutscher/is-it-spam.com
+  changelog_uri: https://github.com/its-benjamin-deutscher/is-it-spam.com/blob/main/lib/is_it_spam_rails/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Rails integration for is-it-spam.com anti-spam service
+test_files: []