@novelcaptcha/node

Node.js server SDK for NovelCaptcha. Issue backend-bound challenge keys, verify browser tokens, and classify emails.

Install

npm install @novelcaptcha/node

Requires Node.js 18+.

Quick start

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

const client = new NovelCaptcha({
  secretKey: process.env.NOVELCAPTCHA_SECRET_KEY!,
  baseUrl: "https://your-novelcaptcha-host",
});

const challenge = await client.createChallenge({
  sitekey: process.env.NOVELCAPTCHA_SITEKEY!,
  type: "invisible",
  context: "login",
});

const result = await client.verify(token, { remoteIp: req.ip });

Constructor options

| Option | Type | Default | Description | |---|---|---|---| | secretKey | string | required | Your server-side NovelCaptcha secret. | | baseUrl | string | https://api.novelcaptcha.com | Origin of your NovelCaptcha deployment. | | timeoutMs | number | 10000 | Request timeout. | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation. |

client.createChallenge(options)

Issues a one-time key for browser NovelCaptcha.execute(challengeKey).

| Option | Type | Required | Notes | |---|---|---|---| | sitekey | string | yes | Public site key. | | type | "visual" \| "invisible" | yes | Public challenge type. | | context | string | yes | Customer flow label. | | customSignals | Record<string, unknown> | no | String-like event and policy attributes. | | customMetrics | Record<string, unknown> | no | Numeric event and policy attributes. |

client.verify(token, { remoteIp? })

Verifies a token. Returns VerifyResult on success. Throws InvalidTokenError, InvalidSecretError, NetworkError, or TimeoutError.

client.classifyEmail(email, { sitekey? })

Classifies an email address into safe, privacy/alias, or temp-mail.

License

MIT