CAPTCHA Abstraction

A unified abstraction layer for multiple CAPTCHA providers, including Google reCAPTCHA (v2), hCaptcha, Cloudflare Turnstile, and Friendly Captcha (v2).

Installation

npm install @thg-altitude/captcha

Quick Start

import { Captcha } from '@thg-altitude/captcha';

// Initialize with your preferred provider
const captcha = new Captcha({
    provider: 'recaptcha', // 'hcaptcha', 'turnstile', 'friendlyCaptcha'
    siteKey: 'your-site-key'
});

// Render the CAPTCHA
await captcha.render('captcha-container', 'widget-id', {
    onToken: (token) => {
        console.log('CAPTCHA solved:', token);
    }
});

Supported Providers

• Google reCAPTCHA v2 - 'recaptcha'
• hCaptcha - 'hcaptcha'
• Cloudflare Turnstile - 'turnstile'
• Friendly Captcha v2 - 'friendlyCaptcha'

Key Features

• Unified API across all providers
• Invisible CAPTCHA support for seamless user experience
• TypeScript support with full type definitions
• Automatic script loading and cleanup
• Flexible rendering options and callback handling

Basic Usage

Standard CAPTCHA

const captcha = new Captcha({
    provider: 'hcaptcha',
    siteKey: 'your-site-key'
});

await captcha.render('container-id', 'form-captcha');
const token = await captcha.getToken('form-captcha');

Invisible CAPTCHA

const captcha = new Captcha({
    provider: 'recaptcha',
    siteKey: 'your-invisible-site-key',
    invisible: true
});

await captcha.render('container-id', 'invisible-captcha', {
    onToken: (token) => submitForm(token)
});

// Trigger when user submits form
await captcha.execute('invisible-captcha');

Methods

• render(container, id, options?) - Render a CAPTCHA widget
• execute(id) - Manually trigger CAPTCHA execution (for invisible mode)
• getToken(id) - Get the current token for a widget
• reset(id) - Reset a widget to its initial state

Notes

• Each provider has different capabilities and configuration options
• Invisible CAPTCHA behavior varies by provider
• For more detailed documentation and implementation guides, see here