Bot Classification with Fallback

A module that classifies user agent strings, using the dependency's comprehensive detection when available and the dependency's naive heuristic fallback when advanced pattern support is unavailable.

Capabilities

Classify user agents with fallback

• With advanced detection enabled and user agents ["Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3 Safari/605.1.15"], bots contain only the first entry, humans contain only the second, and the botRatio is 0.5. @test
• With advanced detection disabled and user agents ["Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/90.0.4400.0 Lighthouse", "curl/7.79.1"], both entries are treated as bots by the dependency's naive heuristic fallback and botRatio is 1. @test
• firstBotSample returns the first detected bot user agent based on the chosen detection mode. For inputs ["CustomScanner/1.0", "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"] with advanced detection disabled, it returns "CustomScanner/1.0"; with advanced detection enabled on the same inputs, it returns null. @test

Ignore invalid entries

• null, undefined, or empty string entries are ignored without throwing and do not appear in either bots or humans. For [null, undefined, "", "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"] with advanced detection enabled, bots are empty, humans contain only the last entry, and botRatio is 0. @test

Provide summary metrics

• The botRatio is calculated as bots.length / (bots.length + humans.length) and rounded to two decimal places for non-empty inputs; when no valid entries exist, it is 0. @test

Implementation

@generates

API

export interface ClassificationResult {
  bots: string[];
  humans: string[];
  botRatio: number;
}

export interface DetectionOptions {
  supportsAdvancedDetection?: boolean;
}

export function classifyUserAgents(
  userAgents: Array<string | null | undefined>,
  options?: DetectionOptions
): ClassificationResult;

export function firstBotSample(
  userAgents: Array<string | null | undefined>,
  options?: DetectionOptions
): string | null;

Dependencies { .dependencies }

isbot { .dependency }

Provides bot detection via comprehensive patterns and a naive fallback heuristic.