@arraypress/recaptcha

⚠️ Deprecated. Use @arraypress/captcha v2+ instead — the reCAPTCHA verifier has moved into the unified CAPTCHA package alongside Turnstile and hCaptcha. The API is the same: import { verifyRecaptcha } from '@arraypress/captcha'.

This package stays on v1.x for backwards compatibility but will not receive further updates.

Verify Google reCAPTCHA v2 and v3 tokens. Zero dependencies.

Uses the Fetch API — works in Cloudflare Workers, Node.js 18+, Deno, Bun, and browsers.

Installation

npm install @arraypress/recaptcha

Usage

import { verify } from '@arraypress/recaptcha';

// reCAPTCHA v2
const valid = await verify(token, 'your-secret-key');

// reCAPTCHA v3 with score threshold
const valid = await verify(token, 'your-secret-key', {
  scoreThreshold: 0.7,
  expectedAction: 'checkout',
});

API

verify(token, secretKey, options?)

Verify a reCAPTCHA token. Returns true if valid, false otherwise. Fails closed — network errors return false.

function verify(token: string, secretKey: string, options?: VerifyOptions): Promise<boolean>

Options:

Option	Type	Description
remoteip	string	The client IP address.
scoreThreshold	number	Minimum score for v3 (0.0-1.0, default 0.5).
expectedAction	string	Expected action name for v3.

// v2 — simple pass/fail
const valid = await verify('token-from-form', 'your-secret-key');

// v3 — check score and action
const valid = await verify(token, secretKey, {
  scoreThreshold: 0.7,
  expectedAction: 'checkout',
  remoteip: '203.0.113.1',
});

verifyDetailed(token, secretKey, options?)

Verify a reCAPTCHA token and return the full response from Google. Use this when you need the score, action, error codes, or hostname for logging.

function verifyDetailed(token: string, secretKey: string, options?: VerifyOptions): Promise<VerifyDetailedResponse>

Options:

Option	Type	Description
remoteip	string	The client IP address.

Response fields:

Field	Type	Description
success	boolean	Whether the token is valid.
score	number	reCAPTCHA v3 score (0.0-1.0). Only for v3.
action	string	Action name from the widget. Only for v3.
challenge_ts	string	ISO timestamp of the challenge.
hostname	string	Hostname the challenge was served on.
error-codes	string[]	Error codes if verification failed.

const result = await verifyDetailed(token, secretKey);

if (result.success) {
  console.log('Score:', result.score);       // v3 only
  console.log('Action:', result.action);     // v3 only
  console.log('Hostname:', result.hostname);
} else {
  console.log('Errors:', result['error-codes']);
}

License

MIT