Installation

pnpm add @007captcha/client

Or via script tag (UMD):

<script src="https://unpkg.com/@007captcha/client/dist/umd/index.global.js"></script>

Usage

ES Module

import { render } from '@007captcha/client';

const widget = render({
  siteKey: 'your-secret-key',
  container: '#captcha',
  method: 'ball',
  serverUrl: window.location.origin,
  onSuccess: (token) => {
    fetch('/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token }),
    });
  },
});

Script Tag

<div id="captcha"></div>
<script src="https://unpkg.com/@007captcha/client/dist/umd/index.global.js"></script>
<script>
  OOSevenCaptcha.render({
    siteKey: 'your-secret-key',
    container: '#captcha',
    method: 'ball',
    serverUrl: window.location.origin,
    onSuccess(token) {
      console.log('Verified:', token);
    },
  });
</script>

Form Integration

The widget creates a hidden <input name="captcha-token"> in the DOM. For standard form submissions, you can also retrieve the token programmatically:

const token = widget.getToken();

Challenge Methods

| Method | Description | |--------|-------------| | 'ball' | Follow a moving ball with your cursor in real-time | | 'shape' | Draw a randomly assigned shape (circle, triangle, or square) | | 'maze' | Navigate a procedurally generated maze from entrance to exit | | 'random' | The server picks a random method each time |

All methods require a serverUrl. The server handles session creation, analysis, and token signing — the client is a rendering and input-capture layer.

Configuration

render(config): CaptchaWidget

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteKey | string | required | Secret key shared with server | | container | string \| HTMLElement | required | Mount target (CSS selector or element) | | method | 'ball' \| 'shape' \| 'maze' \| 'random' | 'random' | Challenge method | | serverUrl | string | required | Base URL for the captcha server endpoints | | theme | 'light' \| 'dark' \| 'auto' | 'light' | Widget color theme | | timeLimit | number | varies | Override time limit in ms | | onSuccess | (token: string) => void | — | Called with signed token on pass | | onFailure | (error: Error) => void | — | Called on challenge failure | | onExpired | () => void | — | Called when a token expires |

CaptchaWidget

widget.getToken()   // Returns the current signed token (string)
widget.reset()      // Reset and show a new challenge
widget.destroy()    // Remove the widget from the DOM entirely

Theming

The widget supports 'light', 'dark', and 'auto' themes. In 'auto' mode, it follows the user's system preference via prefers-color-scheme.

render({ theme: 'dark', /* ... */ });

Requirements

• A running @007captcha/server instance with the appropriate endpoints. See the server package or the Express example for setup.
• The siteKey must match between client and server.

License

MIT