@axeptio/behavior-detection 1.0.0

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

@@ -0,0 +1,39 @@
+/**
+ * Mouse Movement Detection Strategy
+ * Autonomous module that manages its own mouse event listeners and state
+ * Tracks distance and angle to detect unnatural jumps and sharp turns
+ */
+import { BaseStrategy, type TimeSeriesPoint } from '../strategy';
+export declare class MouseStrategy extends BaseStrategy {
+    readonly name = "mouse";
+    readonly defaultWeight = 0.3;
+    private distanceSeries;
+    private angleSeries;
+    private lastPosition;
+    private lastAngle;
+    private cumulativeAngle;
+    private rollingWindowMs;
+    private listener;
+    private leaveListener;
+    private isActive;
+    private screenDiagonal;
+    constructor(options?: {
+        rollingWindow?: number;
+    });
+    start(): void;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    /**
+     * Mouse-specific pattern detection
+     * Detects bot-like patterns: constant velocity, linear paths
+     */
+    private detectMousePatterns;
+    getDebugInfo(): {
+        eventCount: number;
+        rollingWindow: number;
+        isActive: boolean;
+        distanceSeries: TimeSeriesPoint[];
+        angleSeries: TimeSeriesPoint[];
+    };
+}

package/dist/esm/strategies/mouse.js

@@ -0,0 +1,155 @@
+/**
+ * Mouse Movement Detection Strategy
+ * Autonomous module that manages its own mouse event listeners and state
+ * Tracks distance and angle to detect unnatural jumps and sharp turns
+ */
+import { BaseStrategy } from '../strategy';
+import { calculateStatistics, gaussian } from '../math-utils';
+export class MouseStrategy extends BaseStrategy {
+    constructor(options) {
+        super();
+        this.name = 'mouse';
+        this.defaultWeight = 0.30;
+        this.distanceSeries = [];
+        this.angleSeries = [];
+        this.lastPosition = null;
+        this.lastAngle = 0;
+        this.cumulativeAngle = 0;
+        this.rollingWindowMs = 5000;
+        this.listener = null;
+        this.leaveListener = null;
+        this.isActive = false;
+        this.screenDiagonal = 1;
+        if ((options === null || options === void 0 ? void 0 : options.rollingWindow) !== undefined)
+            this.rollingWindowMs = options.rollingWindow;
+    }
+    start() {
+        if (this.isActive)
+            return;
+        this.isActive = true;
+        // Calculate screen diagonal for normalization (distance relative to screen size)
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        this.screenDiagonal = Math.sqrt(width * width + height * height);
+        this.listener = (e) => {
+            const mouseEvent = e;
+            const now = Date.now();
+            const currentPos = { x: mouseEvent.clientX, y: mouseEvent.clientY };
+            // Calculate distance and angle from previous position
+            if (this.lastPosition) {
+                const dx = currentPos.x - this.lastPosition.x;
+                const dy = currentPos.y - this.lastPosition.y;
+                const pixelDistance = Math.sqrt(dx * dx + dy * dy);
+                // Normalize distance to screen diagonal (0-1 range)
+                // A full diagonal movement = 1.0, a 10px movement on 2000px screen = 0.005
+                const normalizedDistance = pixelDistance / this.screenDiagonal;
+                // Only record if movement is meaningful (> 0.001 = ~2px on 2000px screen)
+                if (normalizedDistance > 0.001) {
+                    const rawAngle = Math.atan2(dy, dx); // -PI to PI
+                    // Unwrap angle to avoid discontinuities (e.g., circles)
+                    let angleDiff = rawAngle - this.lastAngle;
+                    // Normalize difference to -PI to PI
+                    while (angleDiff > Math.PI)
+                        angleDiff -= 2 * Math.PI;
+                    while (angleDiff < -Math.PI)
+                        angleDiff += 2 * Math.PI;
+                    this.cumulativeAngle += angleDiff;
+                    this.lastAngle = rawAngle;
+                    // Store normalized distance (not raw pixels)
+                    this.distanceSeries.push({ value: normalizedDistance, timestamp: now });
+                    this.angleSeries.push({ value: this.cumulativeAngle, timestamp: now });
+                    // Notify detector for confidence tracking
+                    this.notifyEvent(Math.min(1, normalizedDistance * 100));
+                }
+                // Apply rolling window efficiently: remove old events from start
+                // Since events are chronological, we only check from the beginning
+                const cutoff = now - this.rollingWindowMs;
+                while (this.distanceSeries.length > 0 && this.distanceSeries[0].timestamp < cutoff) {
+                    this.distanceSeries.shift();
+                    this.angleSeries.shift(); // Keep both arrays in sync
+                }
+            }
+            this.lastPosition = currentPos;
+        };
+        document.addEventListener('mousemove', this.listener, { passive: true });
+        // Clear data when mouse leaves the window (discontinuous tracking)
+        this.leaveListener = () => {
+            this.distanceSeries = [];
+            this.angleSeries = [];
+            this.lastPosition = null;
+            this.lastAngle = 0;
+            this.cumulativeAngle = 0;
+        };
+        document.addEventListener('mouseleave', this.leaveListener, { passive: true });
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        if (this.listener) {
+            document.removeEventListener('mousemove', this.listener);
+            this.listener = null;
+        }
+        if (this.leaveListener) {
+            document.removeEventListener('mouseleave', this.leaveListener);
+            this.leaveListener = null;
+        }
+    }
+    reset() {
+        this.distanceSeries = [];
+        this.angleSeries = [];
+        this.lastPosition = null;
+        this.lastAngle = 0;
+        this.cumulativeAngle = 0;
+    }
+    score() {
+        if (this.distanceSeries.length < 10)
+            return undefined;
+        // Mouse-specific pattern detection (optimized for normalized continuous data)
+        // Generic smoothness detector is calibrated for discrete events, not continuous movement
+        return this.detectMousePatterns();
+    }
+    /**
+     * Mouse-specific pattern detection
+     * Detects bot-like patterns: constant velocity, linear paths
+     */
+    detectMousePatterns() {
+        if (this.distanceSeries.length < 10)
+            return undefined;
+        let score = 0;
+        let factors = 0;
+        // 1. VELOCITY CONSISTENCY - Bots often move at constant speed
+        const distances = this.distanceSeries.map(p => p.value);
+        if (distances.length >= 3) {
+            const stats = calculateStatistics(distances);
+            // Real human movement has high variation (CV ~0.8-1.2)
+            // page.mouse.move() with steps has lower CV (~0.4-0.6)
+            // Narrower gaussian to be strict
+            score += gaussian(stats.cv, 0.9, 0.35);
+            factors++;
+        }
+        // 2. DIRECTION CHANGES - Bots often have too few or too many sharp turns
+        const angles = this.angleSeries.map(p => p.value);
+        if (angles.length >= 3) {
+            const angleChanges = [];
+            for (let i = 1; i < angles.length; i++) {
+                angleChanges.push(Math.abs(angles[i] - angles[i - 1]));
+            }
+            const avgChange = angleChanges.reduce((a, b) => a + b, 0) / angleChanges.length;
+            // Real humans have moderate but varied direction changes
+            // page.mouse.move() linear interpolation has very small, consistent changes
+            score += gaussian(avgChange, 0.15, 0.12);
+            factors++;
+        }
+        return factors > 0 ? score / factors : undefined;
+    }
+    getDebugInfo() {
+        return {
+            eventCount: this.distanceSeries.length,
+            rollingWindow: this.rollingWindowMs,
+            isActive: this.isActive,
+            distanceSeries: this.distanceSeries,
+            angleSeries: this.angleSeries,
+        };
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Resize Behavior Detection Strategy
+ */
+import { BaseStrategy } from '../strategy';
+export declare class ResizeStrategy extends BaseStrategy {
+    readonly name = "resize";
+    readonly defaultWeight = 0.02;
+    private events;
+    private listener;
+    private isActive;
+    private lastMousePosition;
+    private mouseListener;
+    start(): void;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        withMouseData: number;
+    };
+}

package/dist/esm/strategies/resize.js

@@ -0,0 +1,93 @@
+/**
+ * Resize Behavior Detection Strategy
+ */
+import { BaseStrategy } from '../strategy';
+import { inverseSigmoid, sigmoid } from '../math-utils';
+export class ResizeStrategy extends BaseStrategy {
+    constructor() {
+        super(...arguments);
+        this.name = 'resize';
+        this.defaultWeight = 0.02;
+        this.events = [];
+        this.listener = null;
+        this.isActive = false;
+        this.lastMousePosition = null;
+        this.mouseListener = null;
+    }
+    start() {
+        if (this.isActive)
+            return;
+        this.isActive = true;
+        // Track mouse for resize detection
+        this.mouseListener = (e) => {
+            const mouseEvent = e;
+            this.lastMousePosition = {
+                x: mouseEvent.clientX,
+                y: mouseEvent.clientY,
+            };
+        };
+        document.addEventListener('mousemove', this.mouseListener, { passive: true });
+        // Track resizes
+        this.listener = () => {
+            var _a, _b;
+            const mouseX = (_a = this.lastMousePosition) === null || _a === void 0 ? void 0 : _a.x;
+            const mouseY = (_b = this.lastMousePosition) === null || _b === void 0 ? void 0 : _b.y;
+            let mouseNearEdge = false;
+            if (mouseX !== undefined && mouseY !== undefined) {
+                const edgeThreshold = 50;
+                mouseNearEdge = (mouseX < edgeThreshold ||
+                    mouseX > window.innerWidth - edgeThreshold ||
+                    mouseY < edgeThreshold ||
+                    mouseY > window.innerHeight - edgeThreshold);
+            }
+            this.events.push({
+                width: window.innerWidth,
+                height: window.innerHeight,
+                mouseX,
+                mouseY,
+                mouseNearEdge,
+                timestamp: Date.now(),
+            });
+        };
+        window.addEventListener('resize', this.listener);
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        if (this.listener) {
+            window.removeEventListener('resize', this.listener);
+            this.listener = null;
+        }
+        if (this.mouseListener) {
+            document.removeEventListener('mousemove', this.mouseListener);
+            this.mouseListener = null;
+        }
+    }
+    reset() {
+        this.events = [];
+    }
+    score() {
+        if (this.events.length === 0)
+            return undefined;
+        let score = 0;
+        let factors = 0;
+        // Frequency
+        score += inverseSigmoid(this.events.length, 5, 0.5);
+        factors++;
+        // Mouse near edge
+        const withMouse = this.events.filter(e => e.mouseX !== undefined);
+        if (withMouse.length > 0) {
+            const nearEdge = withMouse.filter(e => e.mouseNearEdge).length;
+            score += sigmoid(nearEdge / withMouse.length, 0.5, 8);
+            factors++;
+        }
+        return factors > 0 ? score / factors : undefined;
+    }
+    getDebugInfo() {
+        return {
+            eventCount: this.events.length,
+            withMouseData: this.events.filter(e => e.mouseX !== undefined).length,
+        };
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Scroll Behavior Detection Strategy
+ * Autonomous module managing scroll event listeners
+ * Tracks normalized scroll distance and velocity patterns
+ */
+import { BaseStrategy, type TimeSeriesPoint } from '../strategy';
+export declare class ScrollStrategy extends BaseStrategy {
+    readonly name = "scroll";
+    readonly defaultWeight = 0.15;
+    private distanceSeries;
+    private velocitySeries;
+    private lastScrollY;
+    private lastTimestamp;
+    private rollingWindowMs;
+    private documentHeight;
+    private listener;
+    private isActive;
+    constructor(options?: {
+        rollingWindow?: number;
+    });
+    start(): void;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    /**
+     * Scroll-specific pattern detection
+     * Detects bot-like patterns: constant deltas, instant jumps, too smooth
+     */
+    private detectScrollPatterns;
+    getDebugInfo(): {
+        eventCount: number;
+        rollingWindow: number;
+        isActive: boolean;
+        distanceSeries: TimeSeriesPoint[];
+        velocitySeries: TimeSeriesPoint[];
+    };
+}

package/dist/esm/strategies/scroll.js

@@ -0,0 +1,145 @@
+/**
+ * Scroll Behavior Detection Strategy
+ * Autonomous module managing scroll event listeners
+ * Tracks normalized scroll distance and velocity patterns
+ */
+import { BaseStrategy } from '../strategy';
+import { calculateStatistics, gaussian, inverseSigmoid } from '../math-utils';
+export class ScrollStrategy extends BaseStrategy {
+    constructor(options) {
+        super();
+        this.name = 'scroll';
+        this.defaultWeight = 0.15;
+        this.distanceSeries = [];
+        this.velocitySeries = [];
+        this.lastScrollY = null;
+        this.lastTimestamp = 0;
+        this.rollingWindowMs = 5000;
+        this.documentHeight = 1;
+        this.listener = null;
+        this.isActive = false;
+        if ((options === null || options === void 0 ? void 0 : options.rollingWindow) !== undefined)
+            this.rollingWindowMs = options.rollingWindow;
+    }
+    start() {
+        if (this.isActive)
+            return;
+        this.isActive = true;
+        // Calculate document height for normalization
+        this.documentHeight = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight, 1);
+        this.listener = (_e) => {
+            const scrollY = window.scrollY;
+            const now = Date.now();
+            // Always update last position on first event
+            if (this.lastScrollY === null) {
+                this.lastScrollY = scrollY;
+                this.lastTimestamp = now;
+                return;
+            }
+            const pixelDelta = scrollY - this.lastScrollY;
+            const deltaTime = now - this.lastTimestamp;
+            // Skip if no actual scroll happened
+            if (pixelDelta === 0) {
+                return;
+            }
+            // Normalize scroll distance to document height (0-1 range)
+            const normalizedDistance = Math.abs(pixelDelta) / this.documentHeight;
+            // Record all scroll movements (no threshold - let pattern detection decide)
+            if (deltaTime > 0) {
+                const velocity = normalizedDistance / deltaTime; // normalized units per ms
+                // Store as time series
+                this.distanceSeries.push({ value: normalizedDistance, timestamp: now });
+                this.velocitySeries.push({ value: velocity, timestamp: now });
+                // Notify detector for confidence tracking
+                this.notifyEvent(Math.min(1, normalizedDistance * 10));
+                // Apply rolling window efficiently
+                const cutoff = now - this.rollingWindowMs;
+                while (this.distanceSeries.length > 0 && this.distanceSeries[0].timestamp < cutoff) {
+                    this.distanceSeries.shift();
+                    this.velocitySeries.shift();
+                }
+            }
+            this.lastScrollY = scrollY;
+            this.lastTimestamp = now;
+        };
+        // Listen on window for scroll events (document scrolling)
+        window.addEventListener('scroll', this.listener, { passive: true });
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        if (this.listener) {
+            window.removeEventListener('scroll', this.listener);
+            this.listener = null;
+        }
+    }
+    reset() {
+        this.distanceSeries = [];
+        this.velocitySeries = [];
+        this.lastScrollY = null;
+        this.lastTimestamp = 0;
+    }
+    score() {
+        if (this.distanceSeries.length < 2)
+            return undefined;
+        // Scroll-specific pattern detection
+        return this.detectScrollPatterns();
+    }
+    /**
+     * Scroll-specific pattern detection
+     * Detects bot-like patterns: constant deltas, instant jumps, too smooth
+     */
+    detectScrollPatterns() {
+        if (this.distanceSeries.length < 2)
+            return undefined;
+        let score = 0;
+        let factors = 0;
+        // 1. IDENTICAL DELTAS - Smoking gun for bots
+        const distances = this.distanceSeries.map(p => p.value);
+        if (distances.length >= 2) {
+            // Check if all distances are identical (tolerance for floating point)
+            const uniqueDistances = new Set(distances.map(d => Math.round(d * 1000))).size;
+            if (uniqueDistances === 1) {
+                // All scroll amounts identical = definite bot
+                return 0.05;
+            }
+        }
+        // 2. DISTANCE CONSISTENCY - Bots often scroll same amount repeatedly
+        if (distances.length >= 2) {
+            const stats = calculateStatistics(distances);
+            // Real humans have high CV (>0.8) due to natural scroll acceleration/deceleration
+            // Simple automation has lower CV even with varied amounts
+            // Gaussian centered high with narrow width - be strict
+            score += gaussian(stats.cv, 1.0, 0.4);
+            factors++;
+        }
+        // 3. VELOCITY VARIATION - Humans have highly variable scroll speeds
+        const velocities = this.velocitySeries.map(p => p.value);
+        if (velocities.length >= 2) {
+            const stats = calculateStatistics(velocities);
+            // Human velocity is very chaotic (acceleration/deceleration)
+            // Automation has more consistent velocity even with delays
+            score += gaussian(stats.cv, 1.2, 0.5);
+            factors++;
+        }
+        // 4. INSTANT JUMPS - Detect programmatic scrollTo
+        const instantJumps = distances.filter(d => d > 0.1).length; // >10% of document in one event
+        if (distances.length > 0) {
+            const jumpRatio = instantJumps / distances.length;
+            // Penalize high jump ratio (programmatic scrollTo)
+            score += inverseSigmoid(jumpRatio, 0.3, 15);
+            factors++;
+        }
+        return factors > 0 ? score / factors : undefined;
+    }
+    getDebugInfo() {
+        return {
+            eventCount: this.distanceSeries.length,
+            rollingWindow: this.rollingWindowMs,
+            isActive: this.isActive,
+            distanceSeries: this.distanceSeries,
+            velocitySeries: this.velocitySeries,
+        };
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Tap Behavior Detection Strategy (Mobile)
+ * Monitors touch interactions on specific elements
+ * Analyzes tap duration, precision, movement, and timing patterns
+ */
+import { BaseStrategy } from '../strategy';
+export declare class TapStrategy extends BaseStrategy {
+    readonly name = "tap";
+    readonly defaultWeight = 0.35;
+    private events;
+    private targetSelectors;
+    private touchStartListeners;
+    private touchEndListeners;
+    private activeTouches;
+    private isActive;
+    constructor(options?: {
+        targetSelectors?: string[];
+    });
+    start(): void;
+    addTarget(selector: string): void;
+    private attachTouchListeners;
+    private attachTouchListenersForSelector;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        positions: {
+            outside: number;
+            deadCenter: number;
+            overElement: number;
+        };
+        durations: number[];
+        movements: number[];
+        inViewport: number;
+        trackedElements: number;
+    };
+}