0.0
The project is in a healthy, maintained state
A Ruby library for integrating Private Captcha verification into your applications
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Runtime

~> 2.0
 Project Readme

private-captcha-ruby

Gem Version CI

Ruby client for server-side verification of Private Captcha solutions.

Installation

Add this line to your application's Gemfile:

gem 'private_captcha'

And then execute:

bundle install

Or install it yourself as:

gem install private_captcha

Quick Start

require 'private_captcha'

# Initialize the client with your API key
client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key-here'
end

# Verify a captcha solution
begin
  result = client.verify('user-solution-from-frontend')
  if result.success
    puts 'Captcha verified successfully!'
  else
    puts "Verification failed: #{result.error_message}"
  end
rescue PrivateCaptcha::Error => e
  puts "Error: #{e.message}"
end

Usage

Web Framework Integration

Sinatra Example

require 'sinatra'
require 'private_captcha'

client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
end

post '/submit' do
  begin
    # Verify captcha from form data
    client.verify_request(request)

    # Process your form data here
    'Form submitted successfully!'
  rescue PrivateCaptcha::Error
    status 400
    'Captcha verification failed'
  end
end

Rails Example

class FormsController < ApplicationController
  def submit
    client = PrivateCaptcha::Client.new do |config|
      config.api_key = 'your-api-key'
    end

    begin
      client.verify_request(request)
      # Process form data
      render plain: 'Success!'
    rescue PrivateCaptcha::Error
      render plain: 'Captcha failed', status: :bad_request
    end
  end
end

Rack Middleware

require 'private_captcha'

use PrivateCaptcha::Middleware,
  api_key: 'your-api-key',
  failed_status_code: 403

Configuration

Client Options

require 'private_captcha'

client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
  config.domain = PrivateCaptcha::Configuration::EU_DOMAIN  # replace domain for self-hosting or EU isolation
  config.form_field = 'private-captcha-solution'            # custom form field name
  config.max_backoff_seconds = 20                           # maximum wait between retries
  config.attempts = 5                                       # number of retry attempts
  config.logger = Logger.new(STDOUT)                        # optional logger
end

Non-standard backend domains

require 'private_captcha'

# Use EU domain
eu_client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
  config.domain = PrivateCaptcha::Configuration::EU_DOMAIN  # api.eu.privatecaptcha.com
end

# Or specify custom domain in case of self-hosting
custom_client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
  config.domain = 'your-custom-domain.com'
end

Retry Configuration

result = client.verify(
  'solution',
  max_backoff_seconds: 15,  # maximum wait between retries
  attempts: 3               # number of retry attempts
)

Requirements

  • Ruby 3.0+
  • No external dependencies (uses only standard library)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues with this Ruby client, please open an issue on GitHub. For Private Captcha service questions, visit privatecaptcha.com.