captchala

A tiny vanilla-JS shell for CaptchaLa — smart CAPTCHA & bot protection. This package is just a thin loader: it injects the CaptchaLa core SDK from the CDN at runtime, then hands you the global Captchala API with full TypeScript types. No framework required.

Why a CDN loader?

The core anti-bot logic lives on the CaptchaLa CDN, never in this npm package. That keeps the detection logic updatable in real time and means nothing sensitive is bundled into (or pinned by) your app. You ship a ~1 KB shell; the brains stay fresh on the edge.

Install

npm install captchala

Quick start (vanilla JS)

import { loadCaptchala } from 'captchala'

loadCaptchala().then((Captchala) => {
  Captchala
    .init({
      appKey: 'YOUR_APP_KEY',
      product: 'popup', // 'popup' | 'float' | 'embed' | 'bind'
      action: 'login',
    })
    .onSuccess(({ token }) => {
      // Send `token` to your backend to verify.
      console.log('verified:', token)
    })
    .onError(({ message, code }) => {
      console.error('captcha error:', code, message)
    })
    .bindTo('#submit-btn')
})

Prefer rendering inline instead of binding to a trigger? Use .appendTo:

loadCaptchala().then((Captchala) => {
  Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'embed' })
    .onSuccess(({ token }) => sendToServer(token))
    .appendTo('#captcha-container')
})

API

loadCaptchala(): Promise<CaptchalaSDK>

Loads the core SDK from the CDN (with multi-CDN fallback) and resolves with the global Captchala object. Safe to call repeatedly — concurrent calls share one in-flight request and an already-loaded SDK resolves immediately.

isCaptchalaLoaded(): boolean

Returns whether the core SDK is loaded and ready.

Captchala.init(config)

Returns a chainable widget instance.

| Config field | Type | Description | | ---------------------- | -------------------------------------- | -------------------------------------------- | | appKey | string (required) | Your CaptchaLa app's public key. | | product | 'popup' \| 'float' \| 'embed' \| 'bind' | Widget presentation mode. | | action | string | Logical action name for risk scoring. | | lang | string | UI language (BCP-47, e.g. en, zh-CN). | | serverToken | string | Token for server-side verification flows. | | theme | string | Theme name/identifier. | | onServerTokenExpired | () => Promise<string> | Resolve with a fresh server token on expiry. |

Instance methods (all chainable except destroy): .onSuccess(cb), .onError(cb), .onReady(cb), .bindTo(selector), .appendTo(selector), .reset(), .destroy().

TypeScript

Full types ship with the package, including a Window.Captchala global augmentation, so window.Captchala is typed once you've imported anything from captchala.

Docs

Full documentation: https://docs.captcha.la/web-sdk

License

MIT © CaptchaLa