API Reference

Complete reference for the BotSigged JavaScript SDK.

Initialization

BotSigged.init(config)

Initialize the SDK and return an instance. This is the recommended way to use BotSigged.

const botsigged = BotSigged.init({
  apiKey: 'your-site-api-key',
  onScoreUpdate: (score) => {
    console.log('Score:', score.bot_score);
  }
});

Returns a singleton instance. Calling init() multiple times returns the existing instance.

new BotSigged(config)

Create a new instance directly. Use this when you need multiple instances or more control over lifecycle.

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

const sdk = new BotSigged({
  apiKey: 'your-api-key',
  autoStart: false
});

Configuration Options

Option	Type	Default	Description
apiKey	string	required	Your site’s API key
endpoint	string	Auto	WebSocket endpoint URL
debug	boolean	false	Enable debug logging
autoStart	boolean	true	Start collecting on init
sendInterval	number	2000	Signal batch interval (ms)
actionThreshold	number	70	Score threshold for actions
action	string	'none'	Action when threshold exceeded

Action Types

Action	Description
'none'	No automatic action - handle via callbacks
'block'	Block all form submissions
'challenge'	Require proof-of-work challenge

Callbacks

onScoreUpdate(score)

Called whenever the bot score is updated.

onScoreUpdate: (score) => {
  // score.bot_score: number (0-100)
  // score.classification: string (see Session Classifications doc)
  //   Trusted: 'human' | 'search_engine' | 'known_agent'
  //   Neutral: 'scraper' | 'headless_fetch' | 'suspicious'
  //   Malicious: 'bad_bot' | 'stealth_bot' | 'bad_agent' | 'bad_scraper' | 'abusive_human'
  // score.triggered_rules: string[]
}

onHighBotScore(event)

Called when score exceeds actionThreshold.

onHighBotScore: (event) => {
  // event.score: number
  // event.level: 'low' | 'medium' | 'high' | 'critical'
  // event.scoreUpdate: full score object
  // event.sessionId: string
  // event.fingerprintHash: string (if available)
}

onConnectionChange(connected)

Called when WebSocket connection state changes.

onConnectionChange: (connected) => {
  if (!connected) {
    console.warn('Lost connection to BotSigged');
  }
}

onError(error)

Called on SDK errors.

onError: (error) => {
  console.error('BotSigged error:', error.message);
}

Instance Methods

start()

Start collecting signals and connect to server. Called automatically unless autoStart: false.

await botsigged.start();

stop()

Stop collecting and disconnect.

await botsigged.stop();

getSessionId()

Get the current session identifier.

const sessionId = botsigged.getSessionId();

getLastScore()

Get the most recent score update.

const score = botsigged.getLastScore();
if (score) {
  console.log('Current bot score:', score.bot_score);
}

isConnected()

Check if WebSocket is connected.

if (botsigged.isConnected()) {
  // Ready to receive scores
}

getFingerprint()

Get the browser fingerprint data.

const fp = botsigged.getFingerprint();
console.log('Fingerprint hash:', fp?.hash);

Form Protection

BotSigged can automatically protect forms against instant bot submissions.

Configuration

BotSigged.init({
  apiKey: 'your-api-key',
  formProtection: {
    mode: 'auto',           // Protection mode
    maxHoldTime: 3000,      // Max wait time (ms)
    showLoadingUI: true,    // Show spinner while waiting
    loadingMessage: 'Please wait...'
  }
});

Protection Modes

Mode	Description
'auto'	Recommended. Protects forms, fetch(), and XHR automatically
'none'	No automatic protection
'holdUntilReady'	Hold form submissions until score is available
'holdUntilFormScored'	Strongest - waits for form behavior to be analyzed
'blockInstant'	Block submissions faster than threshold

Manual Form Protection (React/SPA)

For React and single-page applications, use these methods for programmatic control:

waitUntilReady()

Wait until SDK has a detection score before proceeding.

const handleSubmit = async (data) => {
  const { score, timedOut } = await botsigged.waitUntilReady();

  if (score && score > 70) {
    showError('Please try again');
    return;
  }

  await submitForm(data);
};

withProtection(callback)

Wrap a submission function with automatic protection.

const protectedSubmit = botsigged.withProtection(async (data) => {
  const response = await fetch('/api/submit', {
    method: 'POST',
    body: JSON.stringify(data)
  });
  return response.json();
});

// Usage
await protectedSubmit(formData);

protectedFetch()

Create a protected version of fetch().

const safeFetch = botsigged.protectedFetch();

await safeFetch('/api/signup', {
  method: 'POST',
  body: JSON.stringify(userData)
});

canSubmit()

Synchronous check for UI state.

const { allowed, reason, score } = botsigged.canSubmit();

// Use in React
<button disabled={!allowed}>
  {allowed ? 'Submit' : 'Verifying...'}
</button>

Proof-of-Work Challenges

When action: 'challenge' is set, suspected bots must complete a computational challenge before submitting forms.

Challenge Configuration

BotSigged.init({
  apiKey: 'your-api-key',
  action: 'challenge',
  challenge: {
    minLevel: 'high',  // Only challenge high+ scores
    ui: {
      message: "Verifying you're human...",
      successMessage: 'Verified!',
      backgroundColor: 'rgba(0, 0, 0, 0.7)',
      textColor: '#ffffff'
    },
    onChallengeStart: (level, difficulty) => {
      console.log('Challenge started:', level);
    },
    onChallengeComplete: (event) => {
      console.log('Solved in:', event.solveTimeMs, 'ms');
    }
  }
});

Challenge Methods

isChallengeSolving()

Check if a challenge is currently in progress.

if (botsigged.isChallengeSolving()) {
  // Show "please wait" message
}

isChallengeSolved()

Check if the challenge has been completed.

if (botsigged.isChallengeSolved()) {
  // User passed the challenge
}

triggerChallenge(level)

Manually trigger a challenge (for testing).

await botsigged.triggerChallenge('high');

Debugging

Enable Debug Mode

BotSigged.init({
  apiKey: 'your-api-key',
  debug: true
});

Performance Metrics

// Get timing summary
const perf = botsigged.getPerformanceSummary();
console.log('Time to first score:', perf.timeToFirstScoreMs, 'ms');

// Log detailed breakdown
botsigged.logPerformance();

Current Signal State

For debugging, you can inspect current signal buffers:

const signals = botsigged.getCurrentSignals();
const buffers = botsigged.getBufferSizes();
console.log('Buffered mouse events:', buffers.mouse);

Static Methods

BotSigged.getInstance()

Get the current singleton instance (or null).

const instance = BotSigged.getInstance();

BotSigged.destroy()

Destroy the singleton instance.

await BotSigged.destroy();

TypeScript

The SDK includes TypeScript definitions:

import type {
  BotSiggedConfig,
  ScoreUpdate,
  HighBotScoreEvent
} from '@botsigged/sdk';

const config: BotSiggedConfig = {
  apiKey: 'your-api-key',
  onScoreUpdate: (score: ScoreUpdate) => {
    // Fully typed
  }
};