Friendly Captcha SDK is the TypeScript library that website developers install to add Friendly Captcha v2 proof-of-work bot protection to their forms and pages, built for teams that want to block spam and abuse while keeping visitor data private and staying GDPR-compliant.

What it is

Friendly Captcha SDK is the client-side integration library for Friendly Captcha v2. It publishes to npm as @friendlycaptcha/sdk, is written in TypeScript, and is released under the Mozilla Public License 2.0. The code runs on your website and inserts the captcha widget into the page, which makes it the front-end layer of the Friendly Captcha product rather than a standalone service. It lives in the JavaScript and TypeScript web ecosystem and supports both ES module imports and CommonJS require calls, so it fits bundler-based and legacy Node-style front ends alike.

The concrete problem it solves is the friction and privacy cost of conventional bot protection. Traditional captcha widgets ask visitors to solve image puzzles, which tracks them and degrades the experience. Friendly Captcha v2 instead uses a proof-of-work challenge, and this SDK is the piece that mounts that challenge in the browser. The repository itself replaces the earlier v1 integration path: the README states plainly that this is the SDK for Friendly Captcha v2 only, and that the v1 SDK lives in the separate friendly-challenge repository. Teams moving from v1 therefore adopt a different package rather than an in-place upgrade.

Key capabilities

• Installs as the npm package @friendlycaptcha/sdk via npm install @friendlycaptcha/sdk or yarn add @friendlycaptcha/sdk.
• Exposes the FriendlyCaptchaSDK class, which is instantiated once and reused when multiple widgets are created.
• Creates widgets through sdk.createWidget({ element: mount, sitekey: "..." }), mounting the captcha under a chosen HTML element identified by a selector.
• Supports CommonJS environments through require("@friendlycaptcha/sdk") in addition to ES module imports.
• Ships proof-of-work challenge handling, matching the repository topics of proof-of-work, anti-bot, anti-spam, privacy, and gdpr-compliant.
• Includes a build pipeline with npm run build for a minimal build and npm run build:dist, which also builds the documentation.
• Provides tests: npm run test for basic unit tests and a separate sdktest folder for end-to-end tests.
• Generates Docusaurus-format reference docs into dist/docs/docusaurus, and manages licence headers with npm run license-check-and-add.

Who uses it and how

• Front-end teams adding bot protection to signup, login, or contact forms mount a widget into a specific DOM element and supply a sitekey for the deployment.
• Sites with several protected forms create one FriendlyCaptchaSDK instance and reuse it across multiple widgets, which the README recommends explicitly.
• Codebases that still run on CommonJS can integrate without converting to ES modules, since the SDK is published for both module systems.
• Organisations with GDPR and privacy obligations use the proof-of-work model instead of image puzzles, avoiding the tracking that comes with conventional captcha widgets.
• Contributors can work on the SDK itself, but the project requires signing a CLA through cla-assistant before a contribution can be accepted.

Getting started

Install the package with npm install @friendlycaptcha/sdk or yarn add @friendlycaptcha/sdk, then import FriendlyCaptchaSDK and call sdk.createWidget with your mount element and sitekey. Full setup details live in the Developer Hub and the Getting Started guide at developer.friendlycaptcha.com.

How it compares

The facts name one neighbouring tool rather than a set of paid products: the v1 SDK at friendlycaptcha/friendly-challenge, which remains a separate repository. This repository covers Friendly Captcha v2 only, so an existing v1 integration keeps running on the older package until it is deliberately migrated. No replacement list of commercial captcha products is provided in the available facts, so no licence, hosting, or cost comparison against named vendors can be made here.

When to use it — and when not to

Choose this SDK when you want proof-of-work bot protection embedded in a TypeScript or JavaScript front end and you are comfortable following the external Developer Hub for server-side verification, which the README does not cover. Avoid it if you are maintaining a Friendly Captcha v1 integration and are not ready to migrate, since this package targets v2 exclusively, or if you expect the repository README to be a complete integration manual, because it deliberately stays light and defers to the hosted documentation. The project is also small — 33 stars, 15 forks, and a last push on 2026-09-03 — so teams should weigh that scale before depending on it, and contributors should expect a CLA requirement before any patch is accepted.

# using npm
npm install @friendlycaptcha/sdk

# using yarn
yarn add @friendlycaptcha/sdk

import { FriendlyCaptchaSDK } from "@friendlycaptcha/sdk"

// Re-use this SDK if you are creating multiple widgets.
const sdk = new FriendlyCaptchaSDK();

// HTML element that you want to mount the widget under.
const mount = document.querySelector("#my-widget-mount");

// Create the widget
const widget = sdk.createWidget({
    element: mount,
    sitekey: "<your sitekey>"
});

var { FriendlyCaptchaSDK } = require("@friendlycaptcha/sdk");

// Re-use this SDK if you are creating multiple widgets.
const sdk = new FriendlyCaptchaSDK();

# install dependencies 
npm install

# minimal build
npm run build

# build for distribution (also builds docs)
npm run build:dist

# run the basic unit tests
npm run test

 rm -rf ../friendly-docs/docs/sdk/reference && mkdir ../friendly-docs/docs/sdk/reference && cp -r ./dist/docs/docusaurus/ ../friendly-docs/docs/sdk/reference/

# print those files that would be changed
npm run license-check-and-add -- check

# add the headers
npm run license-check-and-add -- add