react-watchman/README.md

A human behavior-aware idle detector for React applications. Combines user activity signals with AI-inspired heuristics to detect inactivity intelligently. Ideal for SaaS, banking, and secure apps requiring session timeout and idle monitoring.

# React Watchman

> A human behavior-aware idle detection hook and boundary component for React, designed for intelligent session management, auto-logout, and behavioral analytics in modern web apps.

[![NPM Version](https://img.shields.io/npm/v/react-watchman)](https://www.npmjs.com/package/react-watchman)
[![License](https://img.shields.io/npm/l/react-watchman)](LICENSE)

---

## ✨ Features

- 🧠 **AI-Inspired Idle Detection**: Combines mouse movement, typing, scrolling, and visibility events with customizable heuristics.
- ⚙️ **Customizable Sensitivity & Debounce**: Fine-tune detection accuracy.
- 📦 **React Hook + HOC-Compatible**: Works as a hook (`useReactWatchman`) or wrapped UI (`WatchmanBoundary`).
- 🔐 **Auto Logout & Session Timeout**: Trigger auto-logout logic or alerts after inactivity.
- 📡 **Focus / Blur & Tab Visibility Tracking**: Detect when user switches tabs or windows.
- 💓 **Optional Heartbeat Support**: Add a server ping to keep sessions alive.
- 🧪 **Typescript Support**: Fully typed, developer-friendly.

---

## 📦 Installation

```bash
npm install react-watchman
# or
yarn add react-watchman
```

---

## Demo

Check out the project running [here](https://codesandbox.io/p/sandbox/react-watchman-56sdc2){:target="\_blank"}!

---

## 🚀 Usage

### 1. `useReactWatchman` Hook

```tsx
import { useReactWatchman } from "react-watchman";

function Dashboard() {
  const { isIdle } = useReactWatchman({
    idleTime: 60000,
    onIdle: () => console.log("User is idle"),
    onActive: () => console.log("User is active again"),
    onTabHide: () => console.log("Tab hidden"),
    onTabShow: (ms) => console.log(`Returned after ${ms}ms`),
    onFocus: () => console.log("Window focused"),
    onBlur: () => console.log("Window blurred"),
    debounce: 300,
    sensitivity: 1.0,
  });

  return <div>{isIdle ? "Idle..." : "Active 🟢"}</div>;
}
```

### 2. `WatchmanBoundary` Component

```tsx
import { WatchmanBoundary } from "react-watchman";

export default function App() {
  return (
    <WatchmanBoundary
      timeout={120000}
      debounce={250}
      onIdle={() => console.log("Idle! Logging out soon")}
      onActive={() => console.log("User returned")}
      renderIdle={() => (
        <div className="idle-warning">You’re idle. Logging out...</div>
      )}
    >
      <Dashboard />
    </WatchmanBoundary>
  );
}
```

## 🧠 Parameters & Options

| Option               | Type       | Description                                                           |
| -------------------- | ---------- | --------------------------------------------------------------------- |
| `idleTime`           | `number`   | Time in ms to wait before considering user idle (default: 30000)      |
| `debounce`           | `number`   | Delay for debouncing activity events (default: 250)                   |
| `sensitivity`        | `number`   | 0.1 to 1.0 — sensitivity to idle detection (lower = more tolerant)    |
| `onIdle`             | `function` | Called when user is considered idle                                   |
| `onActive`           | `function` | Called when user becomes active again                                 |
| `onFocus`            | `function` | Called when window gains focus                                        |
| `onBlur`             | `function` | Called when window loses focus                                        |
| `onTabHide`          | `function` | Called when tab becomes hidden                                        |
| `onTabShow`          | `function` | Called when tab becomes visible again, receives duration in ms        |
| `onVisibilityChange` | `function` | Called when tab visibility changes (param: `"visible"` or `"hidden"`) |

## 🧪 Events Tracked

- `mousemove`, `mousedown`, `keydown`, `wheel`, `touchstart`, `scroll`, `pointermove`
- `visibilitychange`, `focus`, `blur`

## 🏭 Industries & Use Cases

| Industry       | How It's Useful                                          |
| -------------- | -------------------------------------------------------- |
| **Fintech**    | Auto-logout inactive users for compliance & security     |
| **SaaS**       | Notify users before logging out, track engagement        |
| **Healthcare** | Ensure sensitive records are not left exposed after idle |
| **E-learning** | Detect disengagement and prompt user re-engagement       |
| **Enterprise** | Log audit trails of focus/blur or session activity       |
| **Banking**    | Strict session expiry enforcement & risk mitigation      |

## 👨‍💻 Why Developers Love It

- ✅ **Plug-and-play**: Simple drop-in solution
- ⚙️ **Configurable**: Fine-grained control for advanced apps
- 🔁 **Reusable**: Hook or boundary component
- 📈 **Scalable**: Add heartbeats, custom triggers, modals, etc.
- 🛡️ **Secure by default**: Helps enforce inactivity-based session logout

## 🧩 Future Plans

- ⏳ Idle countdown timer
- 🧠 Heuristic profiles (adaptive timeout)
- 🔄 Heartbeat/keep-alive via fetch
- 📊 Session activity analytics
- 💬 Idle modal prompts with confirm/extend/logout options

## 📝 License

[MIT License](./react-watchman/license.txt)

## 📫 Contact

Questions or feedback? Reach out via [GitHub](https://github.com/aditya-jha55) or create a discussion.

> Built with ❤️ to make React apps smarter and safer.