@captcha-la/electron

Captchala verification SDK for Electron desktop apps (Windows / macOS / Linux).

Links

• Website: https://captcha.la
• Dashboard (sign up & get your appKey): https://dash.captcha.la
• Documentation: https://captcha.la/docs/sdk/electron
• All SDK docs: https://captcha.la/docs
• Support: [email protected]

Install

npm install @captcha-la/electron

Quick Start

const { CaptchalaClient } = require('@captcha-la/electron');

async function verifyCaptcha(serverToken) {
  const client = new CaptchalaClient({
    appKey: 'your_app_key',  // get yours at https://dash.captcha.la
    serverToken,
    lang: 'zh-CN',
    theme: 'light',
  });

  try {
    const result = await client.verify();
    console.log('pass_token:', result.passToken);
    // Send result.passToken to your backend for server-side validation
    return result;
  } catch (err) {
    if (err.message === 'captcha_dismissed') {
      console.log('User closed captcha');
    } else {
      console.error('Error:', err.message);
    }
  } finally {
    client.destroy();
  }
}

Note: verify() must be called from the main process (not renderer).

Getting your appKey

1. Sign in at https://dash.captcha.la
2. Create an app → copy the appKey
3. Set up your backend to issue server_token via Captchala server API (see https://captcha.la/docs)

Integration flow

Your Backend                    Your Electron App                Captchala
     |                               |                              |
     |  1. Issue server_token        |                              |
     | <---------------------------> |                              |
     |                               |                              |
     |     2. CaptchalaClient.verify(serverToken)                   |
     |                               | ─── encrypted ticket ──────> |
     |                               | <── captcha challenge ────── |
     |                               |     (native window opens)    |
     |                               |                              |
     |     3. User completes captcha |                              |
     |                               | ─── pass_token ────────────> |
     |                               |                              |
     |  4. Validate pass_token       |                              |
     | <---------------------------> |                              |

API

See full reference at https://captcha.la/docs/sdk/electron.

new CaptchalaClient(config)

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | appKey | string | Yes | — | Get at https://dash.captcha.la | | serverToken | string | Yes* | — | One-time token from your backend | | action | string | No | "default" | Business action (e.g. "login") | | lang | string | No | "zh-CN" | UI language | | theme | string | No | "light" | "light" or "dark" | | timeoutMs | number | No | 15000 | HTTP timeout (ms) | | retryCount | number | No | 3 | Retries per server | | maskClosable | boolean | No | false | Allow dismiss by clicking outside | | enableOfflineMode | boolean | No | false | Fallback when servers unreachable | | account | string | No | — | User identifier for risk scoring | | onReady | function | No | — | Called when captcha is rendered | | onFail | function | No | — | Called on recoverable error (user can retry) |

* Required when your app is configured to require a server-issued token (see https://dash.captcha.la).

client.verify(): Promise<CaptchalaResult>

Starts the verification flow. A native captcha window opens automatically.

Resolves with:

{
  passToken: string;      // Submit to your backend for validation
  challengeId: string;    // Challenge identifier
  ttl: number;            // Token validity in seconds
  isOffline: boolean;     // true if verified offline
  isClientOnly: boolean;  // true if client-only verification
}

Rejects with:

• Error('captcha_dismissed') — user closed the captcha
• Error('code: message') — verification failed

Other methods

• client.dismiss() — programmatically close the captcha
• client.setServerToken(token) — update server token (refresh)
• client.destroy() — release native resources
• CaptchalaClient.version() — SDK version
• CaptchalaClient.getDeviceId() / .getFingerprint() — device identifiers

Requirements

| Platform | Requirements | |----------|-------------| | Windows | Windows 10 (build 1809+) | | macOS | macOS 11+ | | Linux | Standard desktop libraries (GTK + libcurl) | | Node.js | 18+ | | Electron | 28+ |

Supported architectures

| Platform | Architectures | |----------|---------------| | Windows | x64 | | macOS | arm64 (Apple Silicon), x64 (Intel) | | Linux | x64, arm64 |

License

MIT — see LICENSE.