@captigo/hcaptcha

hCaptcha adapter for Captigo — client widget lifecycle and server-side token verification.

Provides a browser-side widget lifecycle and a server-side token verification helper behind the same CaptchaAdapter interface as the rest of the captigo ecosystem.

Installation

npm install @captigo/hcaptcha

@captigo/core is installed automatically as a transitive dependency.

Quick start

1. Create the adapter

import { hcaptcha } from "@captigo/hcaptcha";

const adapter = hcaptcha({ siteKey: "your-site-key" });

2. Client-side — render a widget

const widget = adapter.render(container, {
  callbacks: {
    onSuccess: (token) => setHiddenField(token.value),
    onExpire: () => clearField(),
    onError: (err) => console.error(err.message),
  },
});

// Cleanup on unmount:
widget.destroy();

3. Server-side — verify the token

const result = await adapter.verify(token, process.env.HCAPTCHA_SECRET!);
if (!result.success) {
  return Response.json({ error: "CAPTCHA failed" }, { status: 400 });
}

Invisible widget

Set size: "invisible" to render a hidden widget that fires when you call widget.execute():

const adapter = hcaptcha({ siteKey: "...", size: "invisible" });

// adapter.meta.mode === "interactive"

const widget = adapter.render(container, { callbacks: { onSuccess: setToken } });

// On form submit:
const token = await widget.execute();
await submitForm(token.value);

The execute() call resolves when the user completes the (possibly invisible) challenge, or rejects if the challenge expires or errors.

Configuration reference

| Option | Type | Default | Description | |---|---|---|---| | siteKey | string | — | Required. Your hCaptcha site key. | | size | "normal" \| "compact" \| "invisible" | "normal" | Widget variant. "invisible" requires widget.execute(). | | theme | "light" \| "dark" | "light" | Widget color scheme. | | language | string | browser default | Language override (e.g. "en", "fr"). | | endpoint | string | "https://hcaptcha.com" | Custom endpoint for enterprise customers. | | tabindex | number | — | Tab index for the widget iframe. |

Behavior notes

• Invisible mode: Calling widget.execute() runs the challenge; the token is delivered to onSuccess, and the promise returned by execute() resolves once that happens.
• Challenge expiry: If an invisible challenge is dismissed or expires without a solve, any pending execute() promise is rejected.
• execute(action?): An optional action string may be passed for API compatibility with captigo’s widget shape; hCaptcha does not use it, so it is ignored.
• Server verification: Tokens are checked with https://api.hcaptcha.com/siteverify (see adapter.verify).

Documentation

• Server-side verification (hCaptcha section)
• Supported providers
• hCaptcha docs

Repository · Issues