@novelcaptcha/browser

Browser SDK for NovelCaptcha's backend-issued challenge-key flow.

Install

npm install @novelcaptcha/browser

Quick start

import { NovelCaptcha } from "@novelcaptcha/browser";

await NovelCaptcha.load({
  sitekey: "sk_your_site_key",
  scriptUrl: "https://your-novelcaptcha-host/api/api.js",
});

async function submitLogin(email: string, password: string) {
  const challenge = await fetch("/api/login/challenge", { method: "POST" }).then((r) => r.json());
  const { token } = await NovelCaptcha.execute(challenge.challengeKey);

  await fetch("/api/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password, captchaToken: token }),
  });
}

Your backend issues the challenge key with @novelcaptcha/node, novelcaptcha for Python, or POST /challenge/issue.

API

| Method | Description | |---|---| | NovelCaptcha.load(options) | Loads the widget runtime once per page. | | NovelCaptcha.execute(challengeKey, options?) | Consumes a one-time key and resolves with { token }. | | NovelCaptcha.on(event, handler) | Subscribes to loaded, solved, cancelled, expired, or failed. | | NovelCaptcha.isReady() | Returns true after load() completes. |

Legacy direct token helpers are intentionally not part of this API. The backend decides visual versus invisible when it issues the challenge key.

Errors

Every SDK error extends NovelCaptchaError. Common classes: NotReadyError, ScriptLoadError, ChallengeDismissedError, TimeoutError, and UnsupportedEnvironmentError.

License

MIT