BotSigged SDK

A lightweight SDK for real-time bot detection via WebSocket to be connected to botsigged.com (account required).

Bundle Size

The SDK uses code splitting to minimize initial load time. Optional features are lazy-loaded only when enabled.

ESM Build (npm package)

| File | Size | Gzipped | When Loaded | |------|------|---------|-------------| | index.js | 66 KB | 17 KB | Always (initial) | | challenge-.js | 6 KB | 2 KB | Only if action: 'challenge' | | hash-.js | 9 KB | 4 KB | Only if hashVerification.enabled |

IIFE Build (script tag)

| File | Size | Gzipped | |------|------|---------| | botsigged.js | 85 KB | 25 KB |

The IIFE build includes all features in a single file for simplicity.

Features

• Lightweight - ~17 KB gzipped initial bundle (ESM)
• Code splitting - Challenge and hash modules lazy-loaded on demand
• Modular architecture:
  • Mouse, scroll, and form behavior tracking
  • Browser fingerprinting
  • WebSocket transport (Phoenix channels)
  • Form protection (optionally auto-blocks bots before detection completes)
  • PoW challenge system (optional)

Installation

npm install @botsigged/sdk

Or include directly in HTML:

<script src="https://unpkg.com/@botsigged/sdk/dist/botsigged.js"></script>

Usage

Basic

import { BotSigged } from '@botsigged/sdk';

const botsigged = new BotSigged({
  apiKey: 'pk_your_api_key_here',
});

The SDK auto-starts and begins collecting behavioral signals immediately.

With Account Identification

Track risk across sessions by associating a user account:

const botsigged = new BotSigged({
  apiKey: 'pk_your_api_key_here',
  accountId: 'user_123', // Associate session with account on init
});

// Or identify later (e.g., after login)
await botsigged.identify({ accountId: 'user_123' });

Server-Side Verification

Pass the session ID to your backend for server-side score lookup:

const botsigged = new BotSigged({
  apiKey: 'pk_your_api_key_here',

  // Option 1: Cookie (for traditional form posts)
  cookie: true, // Sets '_bsid' cookie

  // Option 2: Headers (for SPAs using fetch/XHR)
  headers: true, // Adds 'X-BotSigged-ID' header to requests

  // Option 3: Hidden form field (cookie-free forms)
  formInject: true, // Injects '_bsid' hidden input
});

Then verify on your backend:

GET https://api.botsigged.com/v1/sessions/{session_id}
Authorization: Bearer sk_your_secret_key

Form Protection

Automatically hold form submissions until bot detection completes:

const botsigged = new BotSigged({
  apiKey: 'pk_your_api_key_here',
  formProtection: {
    mode: 'holdUntilReady', // Wait for score before allowing submit
    maxHoldTime: 3000,      // Max 3s wait
  },
});

React / SPA Usage

For programmatic form submissions:

const botsigged = new BotSigged({ apiKey: 'pk_your_api_key_here' });

// Wait for detection before submitting
const handleSubmit = async (data) => {
  const { score, timedOut } = await botsigged.waitUntilReady();

  if (score && score > 70) {
    return; // Block suspicious submissions
  }

  await fetch('/api/submit', {
    method: 'POST',
    body: JSON.stringify(data),
  });
};

Blocking Bots

Automatically block or challenge high-scoring sessions:

const botsigged = new BotSigged({
  apiKey: 'pk_your_api_key_here',
  action: 'block',      // or 'challenge' for PoW
  actionThreshold: 70,  // Score threshold
});

License

MIT