API Reference

All public exports from @riavzon/bot-detector are documented below. Every getter (getDataSources, getStorage, getDb, getBatchQueue) throws if called before defineConfiguration resolves.

Initialization

defineConfiguration(config)

Initializes the middleware. Opens all MMDB and LMDB databases, starts the batch write queue, and sets up the cache and database connection. Call it once before attaching detectBots to your app. The full configuration reference is in the Configuration guide.

Returns: Promise<void>

warmUp()

Warms the database connection pool by running parallel SELECT 1 queries, then fires a dummy visitor query to prime the query plan cache. Call this after defineConfiguration resolves but before the server starts accepting traffic.

Returns: Promise<void>

createTables(getDb())

Creates the required database tables (visitors, banned) in the configured database. The CLI equivalent is npx bot-detector load-schema. Call this programmatically when you need to control table creation from code rather than from the CLI.

Returns: Promise<void>

Middleware

detectBots(buildCustomContext?)

Returns an Express RequestHandler. Always call it as a factory: detectBots(). The optional buildCustomContext function runs once per request before any checker executes and populates ctx.custom with typed data you define. When a request passes detection, the middleware sets req.botDetection with success, banned, time, and ipAddress fields.

Returns: RequestHandler

app.use(
  detectBots<ClientSignals>((req) => ({
    hasWebDriver: req.headers['x-webdriver'] === 'true',
  }))
)

ApiResponse

An Express Router that mounts detectBots() at /check and returns { results: req.botDetection, message: 'Fingerprint logged successfully' }.

Type: express.Router

Usage: mount under a path app.use('/bot', ApiResponse) which will expose POST /bot/check.

import { ApiResponse } from '@riavzon/bot-detector'

app.use('/bot', ApiResponse)

Data Access

getDataSources()

Returns the initialized DataSources instance. Throws if called before defineConfiguration resolves. DataSources exposes synchronous MMDB and LMDB lookup methods for every compiled database: ASN, city, country, Tor nodes, proxies, good bots, FireHOL threat feeds, banned IPs, high-risk IPs, and User-Agent patterns. See the Data Sources guide for the full method reference.

Returns: DataSources

getStorage()

Returns the initialized unstorage Storage instance. Throws if called before defineConfiguration resolves. Use it to read and write shared state from within custom checkers.

Returns: Storage (unstorage)

getBatchQueue()

Returns the initialized BatchQueue instance used for deferred database writes. Throws if called before defineConfiguration resolves. Jobs are deduplicated by key within each flush interval.

Returns: BatchQueue

getDb()

Returns the initialized db0 Database instance. Throws if called before defineConfiguration resolves. Use it for direct SQL access to the visitor persistence layer.

Returns: Database

Utilities

parseUA(uaString)

Parses a User-Agent string and returns a ParsedUAResult with browser name, version, type, OS, device type, vendor, and model.

Returns: ParsedUAResult

getGeoData(ip)

Returns the full GeoResponse for any IP address using the compiled MMDB databases. Returns null if the IP is not in the databases. Useful for geo lookups outside the middleware context.

Returns: GeoResponse

banIp(ip, info)

Issues a ufw firewall rule (sudo ufw insert 1 deny from <ip>) to block the IP at the OS level. Only runs when punishmentType.enableFireWallBan is true, returns immediately otherwise. Requires the Node.js process to have passwordless sudo access to ufw.

Returns: Promise<void> | void

updateIsBot(isBot, cookie)

Updates the is_bot column in the visitors table for the given canary_id.

Returns: Promise<void>

updateBannedIP(cookie, ipAddress, country, userAgent, info)

Upserts a row into the banned table with the visitor's canary cookie, IP address, country, User-Agent, ban reasons, and score.

Returns: Promise<void>

updateVisitors(data, cookie, visitorId)

Updates the full fingerprint record in the visitors table for a given canary and visitor ID pair. Returns { success: boolean, reason?: string }.

Returns: Promise<{ success: boolean; reason?: string }>

runGeneration()

Programmatic equivalent of npx bot-detector generate. Compiles banned.mmdb and highRisk.mmdb from your database. When generator.deleteAfterBuild is true, source rows are deleted after each successful compile.

Returns: Promise<void>

Checker System

CheckerRegistry

Registry for custom bot checker plugins. Use CheckerRegistry.register(checker) to add a checker that implements IBotChecker. Checkers are partitioned into cheap and heavy phases and filtered by your configuration at runtime. CheckerRegistry.clear() removes all registered checkers, which is useful in tests.

BadBotDetected / GoodBotDetected

Error subclasses thrown when a checker conclusively identifies a bad or good bot. Re-exported from helpers/exceptions for use in custom checkers and error-handling middleware.

TypeScript Types