CAPTCHA Abstraction

A framework-agnostic TypeScript library that provides a unified abstraction layer for multiple CAPTCHA providers. This package allows you to easily switch between Google reCAPTCHA, hCaptcha, Cloudflare Turnstile, and Friendly Captcha without changing your application code.

Features

🔄 Framework Agnostic: Works with any JavaScript framework or vanilla JavaScript
🎯 Multiple Providers: Support for reCAPTCHA (v2), hCaptcha, Turnstile, and Friendly Captcha
🔧 Unified API: Single interface for all providers
🚀 TypeScript Support: Full type safety and IntelliSense
📦 Lightweight: Minimal dependencies, loads provider scripts on demand
🎨 Flexible Configuration: Support for visible, invisible, and various sizing options
🔒 Multiple Instances: Create multiple CAPTCHA instances with different configurations

Installation

Install using npm:

npm install @thg-altitude/captcha

Quick Start

Constructor Options

interface CaptchaConfig {
    provider: 'recaptcha' | 'hcaptcha' | 'turnstile' | 'friendlyCaptcha';
    siteKey: string;
}

Usage

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

// Create a CAPTCHA instance
const captcha = new Captcha({
    provider: 'recaptcha', // 'recaptcha' | 'hcaptcha' | 'turnstile' | 'friendlyCaptcha'
    siteKey: 'your-site-key'
});

// Render and handle token
await captcha.render('captcha-container', 'login-form', {
    size: 'invisible',
    onToken: (token) => {
        // Submit form with token
        submitForm(token);
    }
});

Provider Support

Google reCAPTCHA v2

✅ Checkbox (normal/compact)
✅ Invisible
✅ Programmatic execution
📖 View the reCAPTCHA Implementation Guide

hCaptcha

✅ Checkbox (normal/compact)
✅ Invisible
✅ Programmatic execution
📖 View the hCaptcha Implementation Guide

Cloudflare Turnstile

✅ Managed (normal/compact/flexible)
✅ Non-interactive
✅ Invisible (dashboard configured)
📖 View the Turnstile Implementation Guide

Friendly Captcha

✅ Automatic puzzle solving
✅ Privacy-focused (GDPR compliant)
✅ Configurable start modes (auto/focus/none)
📖 View the Friendly Captcha Implementation Guide

Provider-Specific Notes

reCAPTCHA

Requires different site keys for visible vs invisible modes
Set size: invisible in render options for invisible widgets
Supports normal and compact sizes for visible widgets

hCaptcha

Same site key works for both visible and invisible modes
Set size: 'invisible' in render options for invisible widgets
Supports normal and compact sizes

Turnstile

Widget behavior configured in Cloudflare dashboard
Supports normal, compact, and flexible sizes
No separate invisible mode configuration needed (this is handled in your turnstile dashboard)
Supports appearance modes always, interaction-only or execute
Support for execution modes (see Turnstile implementation guide for more details)

Friendly Captcha

Privacy-focused CAPTCHA solution that complies with GDPR
Automatically solves puzzles without user interaction in most cases
Supports three start modes:
- auto: Puzzle starts automatically when widget loads (default)
- focus: Puzzle starts when user focuses on any form input within the same form
- none: Puzzle must be started programmatically using execute()
Uses SDK version 0.1.31 from CDN (https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@0.1.31/site.min.js)
Widget events include frc:widget.complete, frc:widget.error, and frc:widget.expire
Reset functionality resets both the widget state and token storage

Error Handling

The library includes custom error classes for better error handling:

import { 
    CaptchaError, 
    ScriptLoadError, 
    TokenError, 
    RenderError, 
    ConfigurationError 
} from '@thg-altitude/captcha';

try {
    await captcha.render('container', 'id');
} catch (error) {
    if (error instanceof ScriptLoadError) {
        // Handle script loading failure
    } else if (error instanceof RenderError) {
        // Handle rendering failure
    }
}

Browser Support

Modern browsers with ES2015+ support
Automatic script loading and cleanup
Works in both browser and server-side rendering environments (renders client-side only)