@axeptio/behavior-detection 1.0.0

package/dist/esm/browser.js

@@ -0,0 +1,224 @@
+/**
+ * Browser Build - Auto-initializing standalone bundle for CDN usage
+ *
+ * Usage:
+ * <script src="https://cdn.../behavior-detector.js"></script>
+ * <script>
+ * window.bdSettings = {
+ *   strategies: {
+ *     mouse: { weight: 0.3 },
+ *     scroll: { weight: 0.15 },
+ *     click: { weight: 0.3 },
+ *     keyboard: { weight: 0.1 },
+ *     environment: { weight: 0.08 },
+ *     resize: { weight: 0.02 }
+ *   },
+ *   autoStart: true,
+ *   checkMs: 2000,
+ *   pauseOnHidden: true,  // Auto-pause when tab hidden (default: true)
+ *   onScore: (result) => {
+ *     console.log('Human likelihood:', result.score);
+ *     if (result.score < 0.3) {
+ *       // Likely bot
+ *     }
+ *   },
+ *   ifBot: (result) => {
+ *     // Called when score < threshold
+ *     console.warn('Bot detected:', result);
+ *   },
+ *   botThreshold: 0.3
+ * }
+ * </script>
+ */
+import { BehaviorDetector } from './behavior-detector';
+import { MouseStrategy, ScrollStrategy, ClickStrategy, TapStrategy, KeyboardStrategy, EnvironmentStrategy, ResizeStrategy, } from './strategies/index.js';
+/**
+ * Detect if the current device is mobile
+ */
+function isMobileDevice() {
+    const hasTouchScreen = navigator.maxTouchPoints > 0 || 'ontouchstart' in window;
+    const mobileUA = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+    const smallScreen = window.innerWidth < 768 && window.innerHeight < 1024;
+    return (hasTouchScreen && smallScreen) || mobileUA;
+}
+class BehaviorDetectionAPI {
+    constructor() {
+        this.detector = null;
+        this.checkInterval = null;
+        this.settings = null;
+    }
+    /**
+     * Initialize the detector with settings
+     */
+    init(settings) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w;
+        if (this.detector) {
+            this.stop();
+        }
+        this.settings = settings;
+        this.detector = new BehaviorDetector({
+            pauseOnHidden: settings.pauseOnHidden !== undefined ? settings.pauseOnHidden : true
+        });
+        // Detect if mobile to adjust strategy selection and weights
+        const isMobile = isMobileDevice();
+        const strategies = settings.strategies || {};
+        // Mobile-adjusted default weights
+        const defaultWeights = isMobile ? {
+            mouse: 0, // Disabled on mobile
+            scroll: 0.35, // Increased (more reliable on mobile)
+            click: 0, // Disabled on mobile (use tap instead)
+            tap: 0.35, // Mobile tap detection
+            keyboard: 0.15,
+            environment: 0.10,
+            resize: 0.05, // Orientation changes
+        } : {
+            mouse: 0.30,
+            scroll: 0.15,
+            click: 0.30,
+            tap: 0, // Disabled on desktop
+            keyboard: 0.10,
+            environment: 0.08,
+            resize: 0.02,
+        };
+        // Mouse - Desktop only
+        if (!isMobile && ((_a = strategies.mouse) === null || _a === void 0 ? void 0 : _a.enabled) !== false) {
+            const strategy = new MouseStrategy();
+            const weight = (_c = (_b = strategies.mouse) === null || _b === void 0 ? void 0 : _b.weight) !== null && _c !== void 0 ? _c : defaultWeights.mouse;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Scroll - Universal
+        if (((_d = strategies.scroll) === null || _d === void 0 ? void 0 : _d.enabled) !== false) {
+            const strategy = new ScrollStrategy();
+            const weight = (_f = (_e = strategies.scroll) === null || _e === void 0 ? void 0 : _e.weight) !== null && _f !== void 0 ? _f : defaultWeights.scroll;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Click - Desktop only
+        if (!isMobile && ((_g = strategies.click) === null || _g === void 0 ? void 0 : _g.enabled) !== false) {
+            const strategy = new ClickStrategy();
+            const weight = (_j = (_h = strategies.click) === null || _h === void 0 ? void 0 : _h.weight) !== null && _j !== void 0 ? _j : defaultWeights.click;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Tap - Mobile only
+        if (isMobile && ((_k = strategies.tap) === null || _k === void 0 ? void 0 : _k.enabled) !== false) {
+            const strategy = new TapStrategy();
+            const weight = (_m = (_l = strategies.tap) === null || _l === void 0 ? void 0 : _l.weight) !== null && _m !== void 0 ? _m : defaultWeights.tap;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Keyboard - Universal
+        if (((_o = strategies.keyboard) === null || _o === void 0 ? void 0 : _o.enabled) !== false) {
+            const strategy = new KeyboardStrategy();
+            const weight = (_q = (_p = strategies.keyboard) === null || _p === void 0 ? void 0 : _p.weight) !== null && _q !== void 0 ? _q : defaultWeights.keyboard;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Environment - Universal
+        if (((_r = strategies.environment) === null || _r === void 0 ? void 0 : _r.enabled) !== false) {
+            const strategy = new EnvironmentStrategy();
+            const weight = (_t = (_s = strategies.environment) === null || _s === void 0 ? void 0 : _s.weight) !== null && _t !== void 0 ? _t : defaultWeights.environment;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Resize - Universal
+        if (((_u = strategies.resize) === null || _u === void 0 ? void 0 : _u.enabled) !== false) {
+            const strategy = new ResizeStrategy();
+            const weight = (_w = (_v = strategies.resize) === null || _v === void 0 ? void 0 : _v.weight) !== null && _w !== void 0 ? _w : defaultWeights.resize;
+            this.detector.addStrategy(strategy, weight);
+        }
+        // Start if autoStart is enabled
+        if (settings.autoStart !== false) {
+            this.start();
+        }
+        // Set up periodic checking if checkMs is specified
+        if (settings.checkMs && settings.checkMs > 0) {
+            this.startPeriodicCheck(settings.checkMs);
+        }
+        // Call onReady callback
+        if (settings.onReady) {
+            settings.onReady(this);
+        }
+    }
+    /**
+     * Start detection
+     */
+    start() {
+        if (!this.detector) {
+            console.warn('BehaviorDetector: Call init() before start()');
+            return;
+        }
+        this.detector.start();
+    }
+    /**
+     * Stop detection
+     */
+    stop() {
+        if (this.detector) {
+            this.detector.stop();
+        }
+        if (this.checkInterval !== null) {
+            clearInterval(this.checkInterval);
+            this.checkInterval = null;
+        }
+    }
+    /**
+     * Get current score
+     */
+    async score() {
+        if (!this.detector) {
+            console.warn('BehaviorDetector: Call init() before score()');
+            return null;
+        }
+        return this.detector.score({ breakdown: true });
+    }
+    /**
+     * Start periodic checking
+     */
+    startPeriodicCheck(intervalMs) {
+        if (this.checkInterval !== null) {
+            clearInterval(this.checkInterval);
+        }
+        this.checkInterval = window.setInterval(async () => {
+            var _a, _b;
+            const result = await this.score();
+            if (!result || !this.settings)
+                return;
+            // Call onScore callback
+            if (this.settings.onScore) {
+                this.settings.onScore(result);
+            }
+            // Check thresholds
+            const botThreshold = (_a = this.settings.botThreshold) !== null && _a !== void 0 ? _a : 0.3;
+            const humanThreshold = (_b = this.settings.humanThreshold) !== null && _b !== void 0 ? _b : 0.7;
+            if (result.score < botThreshold && this.settings.ifBot) {
+                this.settings.ifBot(result);
+            }
+            else if (result.score >= humanThreshold && this.settings.ifHuman) {
+                this.settings.ifHuman(result);
+            }
+        }, intervalMs);
+    }
+    /**
+     * Get the underlying detector instance for advanced usage
+     */
+    getDetector() {
+        return this.detector;
+    }
+}
+// Create global API instance
+const api = new BehaviorDetectionAPI();
+// Auto-initialize if settings are already present
+if (typeof window !== 'undefined') {
+    // Expose API globally
+    window.BehaviorDetector = api;
+    // Check for settings on load
+    const checkAndInit = () => {
+        const settings = window.bdSettings;
+        if (settings) {
+            api.init(settings);
+        }
+    };
+    // Try immediate init
+    checkAndInit();
+    // Also try after DOM ready
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', checkAndInit);
+    }
+}
+// No exports needed for browser IIFE build - window.BehaviorDetector is sufficient

package/dist/esm/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @axeptio/behavior-detection
+ *
+ * Lightweight behavior detection library to assess human likelihood of user sessions
+ *
+ * @example Settings-based (all strategies included)
+ * ```ts
+ * import { BehaviorDetector } from '@axeptio/behavior-detection';
+ *
+ * const detector = new BehaviorDetector({
+ *   weights: {
+ *     mouseMovement: 0.3,
+ *     clickAccuracy: 0.3,
+ *   },
+ * });
+ *
+ * detector.start();
+ * const result = await detector.score({ breakdown: true });
+ * ```
+ *
+ * @example Strategy-based (tree-shakeable, import only what you need)
+ * ```ts
+ * import { BehaviorDetector, Mouse, Click, Keyboard } from '@axeptio/behavior-detection';
+ *
+ * const detector = new BehaviorDetector()
+ *   .addStrategy(new Mouse())
+ *   .addStrategy(new Click())
+ *   .addStrategy(new Keyboard());
+ *
+ * detector.start();
+ * const result = await detector.score();
+ * ```
+ */
+export { BehaviorDetector } from './behavior-detector';
+export type { DetectionStrategy, StrategyConfig } from './strategy';
+export { Mouse, Scroll, Click, Tap, Keyboard, Environment, Resize, MouseStrategy, ScrollStrategy, ClickStrategy, TapStrategy, KeyboardStrategy, EnvironmentStrategy, ResizeStrategy, } from './strategies/index.js';
+export type { BehaviorSettings, ScoreOptions, ScoreResult, ScoreBreakdown, TrackedEvent, EventType, ScoringFunction, } from './types';
+export { DEFAULT_SETTINGS } from './types';

package/dist/esm/index.js

@@ -0,0 +1,36 @@
+/**
+ * @axeptio/behavior-detection
+ *
+ * Lightweight behavior detection library to assess human likelihood of user sessions
+ *
+ * @example Settings-based (all strategies included)
+ * ```ts
+ * import { BehaviorDetector } from '@axeptio/behavior-detection';
+ *
+ * const detector = new BehaviorDetector({
+ *   weights: {
+ *     mouseMovement: 0.3,
+ *     clickAccuracy: 0.3,
+ *   },
+ * });
+ *
+ * detector.start();
+ * const result = await detector.score({ breakdown: true });
+ * ```
+ *
+ * @example Strategy-based (tree-shakeable, import only what you need)
+ * ```ts
+ * import { BehaviorDetector, Mouse, Click, Keyboard } from '@axeptio/behavior-detection';
+ *
+ * const detector = new BehaviorDetector()
+ *   .addStrategy(new Mouse())
+ *   .addStrategy(new Click())
+ *   .addStrategy(new Keyboard());
+ *
+ * detector.start();
+ * const result = await detector.score();
+ * ```
+ */
+export { BehaviorDetector } from './behavior-detector';
+export { Mouse, Scroll, Click, Tap, Keyboard, Environment, Resize, MouseStrategy, ScrollStrategy, ClickStrategy, TapStrategy, KeyboardStrategy, EnvironmentStrategy, ResizeStrategy, } from './strategies/index.js';
+export { DEFAULT_SETTINGS } from './types';

package/dist/esm/math-utils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Mathematical utility functions for continuous scoring
+ * Replaces magic number if-else chains with smooth mathematical functions
+ */
+/**
+ * Sigmoid function - Maps any value to [0, 1] with smooth S-curve
+ * @param x - Input value
+ * @param midpoint - Value that maps to 0.5
+ * @param steepness - How steep the curve is (higher = steeper)
+ */
+export declare function sigmoid(x: number, midpoint?: number, steepness?: number): number;
+/**
+ * Inverse sigmoid - High values map to low scores
+ */
+export declare function inverseSigmoid(x: number, midpoint?: number, steepness?: number): number;
+/**
+ * Gaussian (bell curve) - Peak at ideal value, falls off on both sides
+ * @param x - Input value
+ * @param ideal - Optimal value (peak of curve)
+ * @param width - How wide the acceptable range is
+ */
+export declare function gaussian(x: number, ideal?: number, width?: number): number;
+/**
+ * Exponential decay - High values get penalized exponentially
+ */
+export declare function exponentialDecay(x: number, decayRate?: number): number;
+/**
+ * Normalize value to [0, 1] range
+ */
+export declare function normalize(value: number, min?: number, max?: number): number;
+/**
+ * Clamp value to [0, 1]
+ */
+export declare function clamp01(value: number): number;
+/**
+ * Statistical metrics for an array of numbers
+ */
+export interface Statistics {
+    mean: number;
+    variance: number;
+    stdDev: number;
+    cv: number;
+}
+/**
+ * Calculate statistical metrics for an array of numbers
+ * @param values - Array of numerical values
+ * @returns Statistical metrics (mean, variance, stdDev, cv)
+ */
+export declare function calculateStatistics(values: number[]): Statistics;
+/**
+ * Analysis result for interval patterns
+ */
+export interface IntervalAnalysis {
+    statistics: Statistics;
+    uniqueCount: number;
+    allIdentical: boolean;
+}
+/**
+ * Analyze timing intervals for bot-like patterns
+ * Returns raw analysis data without scoring - caller decides heuristics
+ *
+ * @param intervals - Array of time intervals (ms)
+ * @returns Analysis of interval patterns including stats and uniqueness
+ */
+export declare function analyzeIntervals(intervals: number[]): IntervalAnalysis | undefined;
+/**
+ * Score coefficient of variation
+ * Maps CV to human-likeness score using Gaussian
+ * Ideal CV is around 0.4-0.5 (moderate variation)
+ */
+export declare function scoreCoefficientOfVariation(cv: number): number;
+/**
+ * Score entropy - Higher is better (more random = more human)
+ * Uses sigmoid to smoothly map entropy to score
+ */
+export declare function scoreEntropy(normalizedEntropy: number): number;
+/**
+ * Score autocorrelation - Lower is better (less periodic = more human)
+ */
+export declare function scoreAutocorrelation(autocorr: number): number;
+/**
+ * Score jerk - Lower is better (smoother = more human)
+ */
+export declare function scoreJerk(avgJerk: number): number;

package/dist/esm/math-utils.js

@@ -0,0 +1,127 @@
+/**
+ * Mathematical utility functions for continuous scoring
+ * Replaces magic number if-else chains with smooth mathematical functions
+ */
+/**
+ * Sigmoid function - Maps any value to [0, 1] with smooth S-curve
+ * @param x - Input value
+ * @param midpoint - Value that maps to 0.5
+ * @param steepness - How steep the curve is (higher = steeper)
+ */
+export function sigmoid(x, midpoint = 0, steepness = 1) {
+    return 1 / (1 + Math.exp(-steepness * (x - midpoint)));
+}
+/**
+ * Inverse sigmoid - High values map to low scores
+ */
+export function inverseSigmoid(x, midpoint = 0, steepness = 1) {
+    return 1 - sigmoid(x, midpoint, steepness);
+}
+/**
+ * Gaussian (bell curve) - Peak at ideal value, falls off on both sides
+ * @param x - Input value
+ * @param ideal - Optimal value (peak of curve)
+ * @param width - How wide the acceptable range is
+ */
+export function gaussian(x, ideal = 0, width = 1) {
+    const exponent = -Math.pow(x - ideal, 2) / (2 * width * width);
+    return Math.exp(exponent);
+}
+/**
+ * Exponential decay - High values get penalized exponentially
+ */
+export function exponentialDecay(x, decayRate = 0.1) {
+    return Math.exp(-decayRate * x);
+}
+/**
+ * Normalize value to [0, 1] range
+ */
+export function normalize(value, min = 0, max = 1) {
+    if (max === min)
+        return 0.5;
+    return Math.max(0, Math.min(1, (value - min) / (max - min)));
+}
+/**
+ * Clamp value to [0, 1]
+ */
+export function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * Calculate statistical metrics for an array of numbers
+ * @param values - Array of numerical values
+ * @returns Statistical metrics (mean, variance, stdDev, cv)
+ */
+export function calculateStatistics(values) {
+    if (values.length === 0) {
+        return { mean: 0, variance: 0, stdDev: 0, cv: 0 };
+    }
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+    const stdDev = Math.sqrt(variance);
+    const cv = mean > 0 ? stdDev / mean : 0;
+    return { mean, variance, stdDev, cv };
+}
+/**
+ * Analyze timing intervals for bot-like patterns
+ * Returns raw analysis data without scoring - caller decides heuristics
+ *
+ * @param intervals - Array of time intervals (ms)
+ * @returns Analysis of interval patterns including stats and uniqueness
+ */
+export function analyzeIntervals(intervals) {
+    if (intervals.length < 2)
+        return undefined;
+    // Check for identical intervals (round to 10ms to account for floating point)
+    const uniqueCount = new Set(intervals.map(i => Math.round(i / 10))).size;
+    const allIdentical = uniqueCount === 1;
+    // Calculate statistics
+    const statistics = calculateStatistics(intervals);
+    return {
+        statistics,
+        uniqueCount,
+        allIdentical,
+    };
+}
+/**
+ * Score coefficient of variation
+ * Maps CV to human-likeness score using Gaussian
+ * Ideal CV is around 0.4-0.5 (moderate variation)
+ */
+export function scoreCoefficientOfVariation(cv) {
+    // Too low (<0.1) = bot-like (too consistent)
+    // Too high (>1.5) = random noise
+    // Ideal = 0.4-0.6 (natural human variation)
+    if (cv < 0.05)
+        return 0.1; // Almost zero variation - definitely bot
+    if (cv > 2.0)
+        return 0.3; // Too random
+    // Gaussian centered at 0.45 with width of 0.35
+    return gaussian(cv, 0.45, 0.35);
+}
+/**
+ * Score entropy - Higher is better (more random = more human)
+ * Uses sigmoid to smoothly map entropy to score
+ */
+export function scoreEntropy(normalizedEntropy) {
+    // Entropy of 0.7+ is very human
+    // Entropy < 0.3 is very bot-like
+    return sigmoid(normalizedEntropy, 0.5, 8); // Steep curve at midpoint 0.5
+}
+/**
+ * Score autocorrelation - Lower is better (less periodic = more human)
+ */
+export function scoreAutocorrelation(autocorr) {
+    // Low autocorrelation (<0.2) is natural
+    // High autocorrelation (>0.6) is periodic/bot-like
+    return inverseSigmoid(autocorr, 0.4, 10);
+}
+/**
+ * Score jerk - Lower is better (smoother = more human)
+ */
+export function scoreJerk(avgJerk) {
+    // Human jerk typically < 0.01
+    // Bot jerk often > 0.1
+    // Use inverse sigmoid
+    return inverseSigmoid(avgJerk, 0.05, 50);
+}

package/dist/esm/strategies/click.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Click Behavior Detection Strategy
+ * Monitors specific elements for click positioning patterns
+ */
+import { BaseStrategy } from '../strategy';
+export declare class ClickStrategy extends BaseStrategy {
+    readonly name = "click";
+    readonly defaultWeight = 0.3;
+    private events;
+    private targetSelectors;
+    private lastMousePosition;
+    private mouseListener;
+    private clickListeners;
+    private isActive;
+    constructor(options?: {
+        targetSelectors?: string[];
+    });
+    start(): void;
+    /**
+     * Add a new target selector at runtime
+     */
+    addTarget(selector: string): void;
+    private attachClickListeners;
+    private attachClickListenersForSelector;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        positions: {
+            noMouseData: number;
+            outside: number;
+            deadCenter: number;
+            overElement: number;
+        };
+        inViewport: number;
+        trackedElements: number;
+    };
+}