@tsdevstack/react-bot-detection 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tsdevstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# @tsdevstack/react-bot-detection
+
+React hooks and components for client-side bot detection using behavioral analysis and honeypot fields.
+
+## Features
+
+- **Behavioral Analysis** - Tracks mouse movements, typing patterns, and form interactions
+- **Honeypot Fields** - Hidden fields that bots typically fill out
+- **Zero Dependencies** - Only requires React as a peer dependency
+- **TypeScript** - Full type definitions included
+- **SSR Safe** - Works with Next.js and other SSR frameworks
+
+## Installation
+
+```bash
+npm install @tsdevstack/react-bot-detection
+```
+
+## Quick Start
+
+The simplest way to add bot protection to your forms:
+
+```tsx
+import { BotProtectedForm } from '@tsdevstack/react-bot-detection';
+
+function ContactForm() {
+  const handleSubmit = async (formData: FormData, botResult) => {
+    // botResult contains detection info you can send to your backend
+    const response = await fetch('/api/contact', {
+      method: 'POST',
+      body: JSON.stringify({
+        email: formData.get('email'),
+        message: formData.get('message'),
+        botScore: botResult.score,
+        isBot: botResult.isBot,
+      }),
+    });
+  };
+
+  return (
+    <BotProtectedForm onSubmit={handleSubmit}>
+      <input name="email" type="email" placeholder="Email" />
+      <textarea name="message" placeholder="Message" />
+    </BotProtectedForm>
+  );
+}
+```
+
+## API Reference
+
+### `<BotProtectedForm>`
+
+A form wrapper that combines behavioral analysis and honeypot detection.
+
+```tsx
+import { BotProtectedForm } from '@tsdevstack/react-bot-detection';
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Form content (inputs, labels, etc.) |
+| `onSubmit` | `(data: FormData, result: BotDetectionResult) => Promise<void>` | required | Called on valid submission |
+| `onBotDetected` | `(result: BotDetectionResult) => void` | - | Called when bot is detected |
+| `submitButtonText` | `string` | `"Submit"` | Button text |
+| `loadingButtonText` | `string` | `"Processing"` | Button text while submitting |
+| `className` | `string` | - | CSS class for form element |
+| `ButtonComponent` | `ComponentType<ButtonComponentProps>` | - | Custom button component |
+| `showDebugPanel` | `boolean` | `false` | Show debug info (dev only) |
+
+#### Custom Button Component
+
+Integrate with your design system:
+
+```tsx
+import { BotProtectedForm } from '@tsdevstack/react-bot-detection';
+import { Button } from '@/components/ui/button';
+
+<BotProtectedForm
+  onSubmit={handleSubmit}
+  ButtonComponent={({ children, disabled, type }) => (
+    <Button type={type} disabled={disabled}>
+      {children}
+    </Button>
+  )}
+>
+  {/* form fields */}
+</BotProtectedForm>
+```
+
+---
+
+### `useBotDetection()`
+
+Hook for behavioral analysis. Use this for custom form implementations.
+
+```tsx
+import { useBotDetection } from '@tsdevstack/react-bot-detection';
+```
+
+#### Returns
+
+```ts
+interface UseBotDetectionReturn {
+  botScore: number;           // Current score (0-100+)
+  detectionReasons: string[]; // Human-readable reasons
+  isBot: boolean;             // true if score >= 50
+  handleFieldFocus: () => void;  // Call on field focus
+  handleFormSubmit: () => BotDetectionResult;  // Call before submit
+  stats: BotDetectionStats;   // Raw statistics
+}
+```
+
+#### Example
+
+```tsx
+import { useBotDetection } from '@tsdevstack/react-bot-detection';
+
+function CustomForm() {
+  const { handleFieldFocus, handleFormSubmit, isBot } = useBotDetection();
+
+  const onSubmit = (e: FormEvent) => {
+    e.preventDefault();
+
+    const result = handleFormSubmit();
+    if (result.isBot) {
+      console.log('Bot detected:', result.reasons);
+      return;
+    }
+
+    // Proceed with form submission
+  };
+
+  return (
+    <form onSubmit={onSubmit}>
+      <input onFocus={handleFieldFocus} name="email" />
+      <button type="submit" disabled={isBot}>Submit</button>
+    </form>
+  );
+}
+```
+
+---
+
+### `useHoneypot()`
+
+Hook for honeypot-based detection. Use alongside `useBotDetection` for custom forms.
+
+```tsx
+import { useHoneypot } from '@tsdevstack/react-bot-detection';
+```
+
+#### Returns
+
+```ts
+interface UseHoneypotReturn {
+  isBotDetected: boolean;      // true if honeypot was filled
+  botScore: number;            // Score contribution (50 if triggered)
+  handleBotDetected: () => void;  // Manual trigger
+  resetDetection: () => void;  // Reset state
+  HoneypotComponent: () => ReactElement;  // Pre-configured component
+}
+```
+
+#### Example
+
+```tsx
+import { useHoneypot, useBotDetection } from '@tsdevstack/react-bot-detection';
+
+function CustomForm() {
+  const { HoneypotComponent, isBotDetected } = useHoneypot();
+  const { handleFormSubmit } = useBotDetection();
+
+  const onSubmit = (e: FormEvent) => {
+    e.preventDefault();
+
+    if (isBotDetected) {
+      return; // Silently reject
+    }
+
+    const result = handleFormSubmit();
+    // Combine honeypot + behavioral results
+  };
+
+  return (
+    <form onSubmit={onSubmit}>
+      <HoneypotComponent />
+      <input name="email" />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+---
+
+### `<Honeypot>`
+
+Standalone honeypot component for full control.
+
+```tsx
+import { Honeypot } from '@tsdevstack/react-bot-detection';
+
+<Honeypot onBotDetected={() => setIsBot(true)} />
+```
+
+---
+
+## Types
+
+### `BotDetectionResult`
+
+```ts
+interface BotDetectionResult {
+  score: number;              // Combined score (0-100+)
+  reasons: string[];          // Detection reasons
+  isBot: boolean;             // true if score >= 50
+  stats: BotDetectionStats;   // Raw statistics
+  honeypotTriggered: boolean; // true if honeypot filled
+}
+```
+
+### `BotDetectionStats`
+
+```ts
+interface BotDetectionStats {
+  mouseMovements: number;  // Mouse events tracked
+  typingEvents: number;    // Keystrokes tracked
+  focusEvents: number;     // Focus events tracked
+  timeSpent: number;       // Time on form (ms)
+}
+```
+
+### `ButtonComponentProps`
+
+```ts
+interface ButtonComponentProps {
+  type: 'submit';
+  disabled: boolean;
+  className?: string;
+  children: React.ReactNode;
+}
+```
+
+---
+
+## How Detection Works
+
+### Behavioral Analysis
+
+The `useBotDetection` hook tracks:
+
+| Signal | Score | Description |
+|--------|-------|-------------|
+| No mouse movement | +30 | Bots often don't move the mouse |
+| Unnatural mouse patterns | +20 | Perfectly straight lines, no variation |
+| Consistent typing speed | +15 | Humans have variable typing rhythm |
+| Superhuman typing | +20 | < 50ms between keystrokes |
+| Fast form completion | +40 | < 2 seconds total time |
+| Few focus events | +15 | < 2 field interactions |
+| WebDriver detected | +25 | `navigator.webdriver === true` |
+| Headless browser | +35 | Window size is 0 |
+
+**Threshold:** Score >= 50 is considered a bot.
+
+### Honeypot Detection
+
+Hidden fields styled to be invisible to humans but visible to bots that parse HTML. When filled, adds +100 to score.
+
+---
+
+## Best Practices
+
+### 1. Always Validate Server-Side
+
+Client-side detection can be bypassed. Always validate the `botScore` on your backend:
+
+```ts
+// API route
+export async function POST(req: Request) {
+  const { botScore, isBot, ...formData } = await req.json();
+
+  if (isBot || botScore >= 50) {
+    // Log for analysis, but don't reveal detection
+    return new Response('OK', { status: 200 });
+  }
+
+  // Process legitimate submission
+}
+```
+
+### 2. Don't Block Immediately
+
+Silently accept bot submissions but don't process them. This prevents bots from learning your detection methods.
+
+### 3. Use Debug Panel in Development
+
+```tsx
+<BotProtectedForm onSubmit={handleSubmit} showDebugPanel={process.env.NODE_ENV === 'development'}>
+```
+
+### 4. Combine with Rate Limiting
+
+Bot detection is one layer. Also implement:
+- Rate limiting per IP
+- CAPTCHA for suspicious scores (30-49)
+- Email verification for signups
+
+---
+
+## License
+
+MIT

package/dist/components/bot-protected-form.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+import type { BotDetectionResult, ButtonComponentProps } from '../types';
+export interface BotProtectedFormProps {
+    /** Form content (input fields, etc.) */
+    children: React.ReactNode;
+    /** Called on form submission with FormData and bot detection result */
+    onSubmit: (data: FormData, botDetection: BotDetectionResult) => Promise<void>;
+    /** Called when bot is detected (optional) */
+    onBotDetected?: (result: BotDetectionResult) => void;
+    /** Text for submit button (default: "Submit") */
+    submitButtonText?: string;
+    /** Text while submitting (default: "Processing") */
+    loadingButtonText?: string;
+    /** CSS class for the form element */
+    className?: string;
+    /** Custom button component to match your design system */
+    ButtonComponent?: React.ComponentType<ButtonComponentProps>;
+    /** Show debug panel with detection stats (default: false) */
+    showDebugPanel?: boolean;
+}
+/**
+ * Form wrapper with integrated bot detection.
+ *
+ * Combines behavioral analysis and honeypot detection to protect forms
+ * from automated submissions.
+ *
+ * @example
+ * ```tsx
+ * import { BotProtectedForm } from '@tsdevstack/react-bot-detection';
+ * import { Button } from '@/components/ui/button';
+ *
+ * <BotProtectedForm
+ *   onSubmit={async (formData, botResult) => {
+ *     // Send formData and botResult to your API
+ *   }}
+ *   ButtonComponent={Button}
+ * >
+ *   <input name="email" type="email" />
+ * </BotProtectedForm>
+ * ```
+ */
+export declare function BotProtectedForm({ children, onSubmit, onBotDetected, submitButtonText, loadingButtonText, className, ButtonComponent, showDebugPanel, }: BotProtectedFormProps): React.ReactElement;

package/dist/components/bot-protected-form.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { useBotDetection } from "../hooks/use-bot-detection.js";
+import { useHoneypot } from "../hooks/use-honeypot.js";
+function DefaultButton({ children, disabled, className, type }) {
+    return /*#__PURE__*/ jsx("button", {
+        type: type,
+        disabled: disabled,
+        className: className,
+        style: {
+            padding: '0.5rem 1rem',
+            cursor: disabled ? 'not-allowed' : 'pointer',
+            opacity: disabled ? 0.5 : 1
+        },
+        children: children
+    });
+}
+function BotProtectedForm({ children, onSubmit, onBotDetected, submitButtonText = 'Submit', loadingButtonText = 'Processing', className = '', ButtonComponent = DefaultButton, showDebugPanel = false }) {
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [isClient, setIsClient] = useState(false);
+    const { botScore, detectionReasons, isBot, handleFieldFocus, handleFormSubmit, stats } = useBotDetection();
+    const { isBotDetected: honeypotTriggered, HoneypotComponent } = useHoneypot();
+    useEffect(()=>{
+        setIsClient(true);
+    }, []);
+    const handleSubmit = useCallback(async (e)=>{
+        e.preventDefault();
+        setIsSubmitting(true);
+        try {
+            const behaviorResult = handleFormSubmit();
+            const finalBotScore = behaviorResult.score + (honeypotTriggered ? 100 : 0);
+            const allReasons = [
+                ...behaviorResult.reasons,
+                ...honeypotTriggered ? [
+                    'Honeypot field filled'
+                ] : []
+            ];
+            const botDetectionResult = {
+                score: finalBotScore,
+                reasons: allReasons,
+                isBot: finalBotScore >= 50 || honeypotTriggered,
+                stats,
+                honeypotTriggered
+            };
+            if (botDetectionResult.isBot) {
+                onBotDetected?.(botDetectionResult);
+                setIsSubmitting(false);
+                return;
+            }
+            const formData = new FormData(e.currentTarget);
+            await onSubmit(formData, botDetectionResult);
+        } catch (error) {
+            console.error('Form submission error:', error);
+        } finally{
+            setIsSubmitting(false);
+        }
+    }, [
+        handleFormSubmit,
+        honeypotTriggered,
+        onBotDetected,
+        onSubmit,
+        stats
+    ]);
+    return /*#__PURE__*/ jsxs("form", {
+        onSubmit: handleSubmit,
+        className: className,
+        children: [
+            /*#__PURE__*/ jsx(HoneypotComponent, {}),
+            /*#__PURE__*/ jsx("div", {
+                onFocus: handleFieldFocus,
+                children: children
+            }),
+            /*#__PURE__*/ jsx(ButtonComponent, {
+                type: "submit",
+                disabled: isSubmitting,
+                className: "w-full",
+                children: isSubmitting ? loadingButtonText : submitButtonText
+            }),
+            showDebugPanel && isClient && /*#__PURE__*/ jsx("div", {
+                style: {
+                    marginTop: '1rem',
+                    fontSize: '0.75rem',
+                    color: '#666'
+                },
+                children: /*#__PURE__*/ jsxs("details", {
+                    children: [
+                        /*#__PURE__*/ jsx("summary", {
+                            style: {
+                                cursor: 'pointer'
+                            },
+                            children: "Bot Detection Debug"
+                        }),
+                        /*#__PURE__*/ jsx("pre", {
+                            style: {
+                                marginTop: '0.5rem',
+                                fontSize: '0.75rem',
+                                whiteSpace: 'pre-wrap'
+                            },
+                            children: JSON.stringify({
+                                botScore,
+                                detectionReasons,
+                                isBot,
+                                honeypotTriggered,
+                                stats
+                            }, null, 2)
+                        })
+                    ]
+                })
+            })
+        ]
+    });
+}
+export { BotProtectedForm };

package/dist/components/bot-protected-form.test.d.ts

@@ -0,0 +1 @@
+export {};