bot-id

Lightweight, dependency-free helpers for detecting bots, vulnerability-scan probes, and building telemetry events in edge middleware (Next.js, Cloudflare Workers/Pages, etc.).

Works in any environment with the standard Request/fetch/URL Web APIs.

Install

npm install bot-id

Usage

Detect bots from a user-agent

import { detectBot } from 'bot-id';

const bot = detectBot(request.headers.get('user-agent') || '');
if (bot?.category === 'ai') {
  // an AI crawler — e.g. GPTBot, ClaudeBot, PerplexityBot
}

detectBot returns a BotSignature ({ pattern, name, provider, category }) or null. Categories: ai, search, seo, scraper, vuln_scan.

Signature collections are exported for custom logic: AI_BOTS, SEARCH_SEO_BOTS, SCRAPER_BOTS, ALL_BOT_SIGNATURES, AI_BOT_SIGNATURES.

Detect vulnerability-scan paths

import { isVulnScan } from 'bot-id';

if (isVulnScan(url.pathname)) {
  return new Response(null, { status: 403 });
}

Cloudflare edge snapshot

import { extractCfEdgeSnapshot } from 'bot-id';

const cf = extractCfEdgeSnapshot(request); // ASN, TLS, colo, botManagement...

Telemetry events

import { detectBot, buildPayload, sendDetectEvent } from 'bot-id';

const config = { siteId: 'yourdomain.com', apiEndpoint: 'https://your-api.example.com' };
// Pass the detected bot so its name/provider/category are included in the payload.
const bot = detectBot(request.headers.get('user-agent') || '');
const payload = buildPayload(request, config, url.pathname, /* isBlocked */ false, bot);
await sendDetectEvent(config, payload, config.siteTag);

Customizing

• Bot signatures: edit src/bots.ts.
• Vuln-scan path patterns: edit src/vuln.ts.
• Telemetry payload shape: edit src/event.ts.

Run npm run build to regenerate dist/.

License

MIT