### Install Botscout Gem

Source: https://github.com/parallel588/botscout/blob/master/README.md

Add the gem to your Gemfile and run bundle install, or install it directly using the gem command.

```ruby
gem 'botscout'
```

```bash
$ bundle
```

```bash
$ gem install botscout
```

--------------------------------

### Initialize BotScout Client

Source: https://context7.com/parallel588/botscout/llms.txt

Create a new client instance. An API key is optional for basic lookups but required for full access.

```ruby
require 'botscout'

# Initialize without API key (limited requests)
client = Botscout::Client.new

# Initialize with API key for full access
client = Botscout::Client.new("your_api_key_here")
```

--------------------------------

### Initialize and Use Botscout Client

Source: https://github.com/parallel588/botscout/blob/master/README.md

Instantiate the Botscout client with your API key and use the test method to check an email address. Handles success and error cases.

```ruby
botscout = Botscout::Client.new("key")
result = botscout.test mail: email
if result.success?
    Logger.info "Email address is spam: #{email}" if result.bot?
else
    Logger.info "Servis is not available: #{result.error}"
end
```

--------------------------------

### Botscout::Client Initialization

Source: https://context7.com/parallel588/botscout/llms.txt

Initializes a new BotScout API client. An API key is optional for basic lookups but required for higher rate limits and full API access.

```APIDOC
## Botscout::Client.new

Creates a new BotScout API client instance. The API key is optional for basic lookups but required for higher rate limits and full API access.

### Request Example
```ruby
require 'botscout'

# Initialize without API key (limited requests)
client = Botscout::Client.new

# Initialize with API key for full access
client = Botscout::Client.new("your_api_key_here")
```
```

--------------------------------

### Validate User Registration with BotScout

Source: https://context7.com/parallel588/botscout/llms.txt

Integrates BotScout checks into a registration class with error handling that defaults to allowing registration if the API call fails.

```ruby
require 'botscout'

class RegistrationValidator
  def initialize(api_key)
    @client = Botscout::Client.new(api_key)
  end

  def validate_registration(email:, ip:, username:)
    results = {
      email: check_value(mail: email),
      ip: check_value(ip: ip),
      username: check_value(name: username)
    }

    bot_detected = results.values.any? { |r| r[:is_bot] }

    {
      valid: !bot_detected,
      bot_detected: bot_detected,
      checks: results
    }
  end

  private

  def check_value(params)
    result = @client.test(params)

    if result.success?
      { is_bot: result.bot?, error: nil }
    else
      # Log error but don't block registration on API failure
      { is_bot: false, error: result.error }
    end
  end
end

# Usage
validator = RegistrationValidator.new(ENV['BOTSCOUT_API_KEY'])
check = validator.validate_registration(
  email: "newuser@example.com",
  ip: "203.0.113.42",
  username: "newuser2024"
)

if check[:valid]
  puts "Registration allowed"
else
  puts "Bot detected - registration blocked"
  puts "Flagged checks: #{check[:checks].select { |k, v| v[:is_bot] }.keys}"
end
```

--------------------------------

### Query BotScout API

Source: https://context7.com/parallel588/botscout/llms.txt

Check email, IP, or username against the BotScout database using the test method.

```ruby
require 'botscout'

client = Botscout::Client.new("your_api_key")

# Test an email address
result = client.test(mail: "suspicious@example.com")

if result.success?
  if result.bot?
    puts "WARNING: Email is associated with spam bots!"
    # Block registration or flag for review
  else
    puts "Email appears clean"
    # Proceed with registration
  end
else
  puts "API Error: #{result.error}"
  # Handle service unavailability gracefully
end

# Test an IP address
ip_result = client.test(ip: "192.168.1.100")
puts "IP is bot: #{ip_result.bot?}" if ip_result.success?

# Test a username
name_result = client.test(name: "spamuser123")
puts "Username is bot: #{name_result.bot?}" if name_result.success?
```

--------------------------------

### Botscout::Client::Result#success?

Source: https://context7.com/parallel588/botscout/llms.txt

Returns true if the API request completed successfully without errors, false if there was an error (invalid API key, service unavailable, etc.).

```APIDOC
## Botscout::Client::Result#success?

Returns `true` if the API request completed successfully without errors, `false` if there was an error (invalid API key, service unavailable, etc.).

### Request Example
```ruby
require 'botscout'

client = Botscout::Client.new("invalid_key")
result = client.test(mail: "test@example.com")

if result.success?
  # Process the result
  handle_bot_check(result.bot?)
else
  # API returned an error
  # Error responses start with "!" e.g., "! Sorry, but that doesn't appear to be a valid API key."
  puts "BotScout check failed: #{result.error}"
  # Fallback to alternative validation or allow through
end
```
```

--------------------------------

### Verify Request Success

Source: https://context7.com/parallel588/botscout/llms.txt

Check if the API request completed successfully using the success? method.

```ruby
require 'botscout'

client = Botscout::Client.new("invalid_key")
result = client.test(mail: "test@example.com")

if result.success?
  # Process the result
  handle_bot_check(result.bot?)
else
  # API returned an error
  # Error responses start with "!" e.g., "! Sorry, but that doesn't appear to be a valid API key."
  puts "BotScout check failed: #{result.error}"
  # Fallback to alternative validation or allow through
end
```

--------------------------------

### Botscout::Client::Result#bot?

Source: https://context7.com/parallel588/botscout/llms.txt

Returns true if the tested value matches known bot patterns, false otherwise. Should only be called after verifying success? returns true.

```APIDOC
## Botscout::Client::Result#bot?

Returns `true` if the tested value matches known bot patterns in the BotScout database, `false` otherwise. Should only be called after verifying `success?` returns `true`.

### Request Example
```ruby
require 'botscout'

client = Botscout::Client.new("your_api_key")
result = client.test(mail: "krasnhello@mail.ru")

# Response format from API: "Y|MAIL|0" (bot detected) or "N|MAIL|0" (not a bot)
if result.success?
  if result.bot?
    # result.result == "Y"
    puts "Bot detected - blocking registration"
  else
    # result.result == "N"
    puts "Not a known bot - allowing registration"
  end
end
```
```

--------------------------------

### Botscout::Client#test

Source: https://context7.com/parallel588/botscout/llms.txt

Queries the BotScout API to check if an email address, IP address, or username is associated with known spam bots. Accepts a hash with :mail, :ip, or :name keys. Returns a Botscout::Client::Result object.

```APIDOC
## Botscout::Client#test

Queries the BotScout API to check if an email address, IP address, or username is associated with known spam bots. Accepts a hash with `:mail`, `:ip`, or `:name` keys. Returns a `Botscout::Client::Result` object containing the response data.

### Parameters
#### Query Parameters
- **mail** (string) - Optional - The email address to check.
- **ip** (string) - Optional - The IP address to check.
- **name** (string) - Optional - The username to check.

### Request Example
```ruby
require 'botscout'

client = Botscout::Client.new("your_api_key")

# Test an email address
result = client.test(mail: "suspicious@example.com")

if result.success?
  if result.bot?
    puts "WARNING: Email is associated with spam bots!"
    # Block registration or flag for review
  else
    puts "Email appears clean"
    # Proceed with registration
  end
else
  puts "API Error: #{result.error}"
  # Handle service unavailability gracefully
end

# Test an IP address
ip_result = client.test(ip: "192.168.1.100")
puts "IP is bot: #{ip_result.bot?}" if ip_result.success?

# Test a username
name_result = client.test(name: "spamuser123")
puts "Username is bot: #{name_result.bot?}" if name_result.success?
```

### Response
#### Success Response (200)
- **result** (string) - 'Y' if a bot is detected, 'N' otherwise.
- **type** (string) - The type of check performed (e.g., 'MAIL', 'IP', 'NAME').
- **score** (integer) - The confidence score of the bot detection (0 indicates no bot detected).

#### Response Example
```json
{
  "result": "Y",
  "type": "MAIL",
  "score": 0
}
```
```

--------------------------------

### Botscout::Client::Result#error

Source: https://context7.com/parallel588/botscout/llms.txt

Returns the error message string when the API request fails, or nil if the request was successful. Error messages are extracted from responses that begin with "!".

```APIDOC
## Botscout::Client::Result#error

Returns the error message string when the API request fails, or `nil` if the request was successful. Error messages are extracted from responses that begin with "!".

### Request Example
```ruby
require 'botscout'

client = Botscout::Client.new("bad_api_key")
result = client.test(mail: "user@example.com")

if result.has_error?
  error_message = result.error
  # Returns: " Sorry, but that doesn't appear to be a valid API key."

  case error_message
  when /API key/
    Rails.logger.error "BotScout API key invalid - check configuration"
  when /rate limit/
    Rails.logger.warn "BotScout rate limit exceeded"
  else
    Rails.logger.error "BotScout error: #{error_message}"
  end
end
```
```

--------------------------------

### Check Bot Status

Source: https://context7.com/parallel588/botscout/llms.txt

Verify if a tested value matches known bot patterns using the bot? method after a successful request.

```ruby
require 'botscout'

client = Botscout::Client.new("your_api_key")
result = client.test(mail: "krasnhello@mail.ru")

# Response format from API: "Y|MAIL|0" (bot detected) or "N|MAIL|0" (not a bot)
if result.success?
  if result.bot?
    # result.result == "Y"
    puts "Bot detected - blocking registration"
  else
    # result.result == "N"
    puts "Not a known bot - allowing registration"
  end
end
```

--------------------------------

### Retrieve Error Messages

Source: https://context7.com/parallel588/botscout/llms.txt

Access the error message string returned by the API when a request fails.

```ruby
require 'botscout'

client = Botscout::Client.new("bad_api_key")
result = client.test(mail: "user@example.com")

if result.has_error?
  error_message = result.error
  # Returns: " Sorry, but that doesn't appear to be a valid API key."

  case error_message
  when /API key/
    Rails.logger.error "BotScout API key invalid - check configuration"
  when /rate limit/
    Rails.logger.warn "BotScout rate limit exceeded"
  else
    Rails.logger.error "BotScout error: #{error_message}"
  end
end
```

--------------------------------

### Check for Error Conditions

Source: https://context7.com/parallel588/botscout/llms.txt

Determine if the API response indicates an error using the has_error? method.

```ruby
require 'botscout'

client = Botscout::Client.new

# Simulate connection timeout handling
begin
  result = client.test(mail: "user@example.com")

  if result.has_error?
    # Errors include: invalid API key, rate limiting, service unavailable
    log_botscout_failure(result.error)
    allow_registration_with_flag  # Fail open strategy
  else
    block_if_bot(result.bot?)
  end
rescue => e
  # Connection errors are caught internally and returned as error results
  # e.g., "Service is not available: Connection timed out"
  handle_service_outage
end
```

--------------------------------

### Botscout::Client::Result#has_error?

Source: https://context7.com/parallel588/botscout/llms.txt

Returns true if the API response indicates an error condition, false otherwise. This is the inverse of success? and checks if the response begins with "!".

```APIDOC
## Botscout::Client::Result#has_error?

Returns `true` if the API response indicates an error condition, `false` otherwise. This is the inverse of `success?` and checks if the response begins with "!".

### Request Example
```ruby
require 'botscout'

client = Botscout::Client.new

# Simulate connection timeout handling
begin
  result = client.test(mail: "user@example.com")

  if result.has_error?
    # Errors include: invalid API key, rate limiting, service unavailable
    log_botscout_failure(result.error)
    allow_registration_with_flag  # Fail open strategy
  else
    block_if_bot(result.bot?)
  end
rescue => e
  # Connection errors are caught internally and returned as error results
  # e.g., "Service is not available: Connection timed out"
  handle_service_outage
end
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.