bot-detect

Browser bot-detection SDK you can install on any website to collect behavioral signals and post them to your backend.

Install

npm install @pathum_01/bot-detect

Quick usage

import { initBotDetect } from "@pathum_01/bot-detect";

const botDetect = initBotDetect({
  siteKey: "your_public_site_key",
  endpoint: "https://your-api.example.com/v1/events",
  autoTrack: true,
  flushIntervalMs: 5000,
  debug: true
});

// Optional: stop tracking later
// botDetect.stop();

What it collects

• Browser environment signals (UA, webdriver flag, languages, screen, etc.)
• Behavioral events (mousemove, click, keydown, visibilitychange)
• Session summary metrics (first input delay, typing speed, event ratios)
• Local risk score (0-100) with reasons

Server endpoint contract

POST /v1/events should accept JSON payload like:

{
  "siteKey": "your_public_site_key",
  "sessionId": "abc123",
  "url": "https://example.com/signup",
  "collectedAt": 1710000000000,
  "signals": {},
  "eventSummary": {},
  "localAssessment": { "score": 55, "reasons": ["navigator.webdriver=true"] },
  "events": []
}

Important: always compute the final decision on your server, not only in the browser.

Vercel deployment

This repo is Vercel-ready:

• Root page: / via index.html
• API endpoint: /api/events via api/events.js

After deploy, test:

• GET https://<your-project>.vercel.app/
• GET https://<your-project>.vercel.app/api/events

Set environment variables in Vercel:

• BOT_DETECT_SITE_KEY - validates incoming siteKey
• ALLOWED_ORIGINS - comma-separated origins for strict CORS (required)
• RATE_LIMIT_WINDOW_MS - rate limit window in ms (default 60000)
• RATE_LIMIT_MAX - max requests per IP per window (default 60)
• UPSTASH_REDIS_REST_URL - Upstash Redis REST URL for event persistence
• UPSTASH_REDIS_REST_TOKEN - Upstash Redis REST auth token
• UPSTASH_EVENTS_KEY - Redis list key (default bot_detect_events)
• UPSTASH_MAX_EVENTS - max kept events in Redis list (default 1000)

Production hardening included

• Strict CORS allowlist enforcement for POST /api/events
• Per-IP rate limiting with response headers
• Security headers (X-Frame-Options, Referrer-Policy, etc.)
• Structured server-side event logging
• Optional persistent logging to Upstash Redis (falls back to Vercel logs)