add Idle Timer API to detect user inactivity

Author: dev-aditya-lab

README.md

@@ -527,6 +527,70 @@ preventTabClose(false);
 
 ---
 
+# ⏱️ Idle Timer API – webdev-power-kit
+
+This module helps you detect when a user becomes inactive (idle) for a certain amount of time — perfect for auto-logout, showing alerts, or stopping background activity.
+
+---
+
+## ✨ Features
+
+* Track if user is inactive for X seconds
+* Automatically resets on any activity (scroll, key, mouse, touch)
+* Lightweight and easy to use
+* Uses native browser events
+
+---
+
+## ✅ Functions
+
+### 1. `startIdleTimer(seconds, onIdle)`
+
+📌 Starts tracking user activity and runs your callback when idle.
+
+```js
+import { startIdleTimer } from "webdev-power-kit";
+
+// Run after 10 seconds of inactivity
+startIdleTimer(10, () => {
+  console.log("💤 User is idle!");
+});
+```
+
+#### 📥 Parameters:
+
+| Param     | Type       | Description                                     |
+| --------- | ---------- | ----------------------------------------------- |
+| `seconds` | `number`   | Time in seconds to wait before calling `onIdle` |
+| `onIdle`  | `function` | Callback function to run when user becomes idle |
+
+#### 🔁 Returns:
+
+* `() => void` — A function to stop and clean up the idle timer
+
+---
+
+## 🔐 Browser Support
+
+| Browser | Supported? | Notes           |
+| ------- | ---------- | --------------- |
+| Chrome  | ✅          | Fully supported |
+| Firefox | ✅          | Fully supported |
+| Edge    | ✅          | Fully supported |
+| Safari  | ✅          | Fully supported |
+| Mobile  | ✅          | Fully supported |
+
+---
+
+## 💡 Use Cases
+
+* Auto-logout after inactivity
+* Show “You’re idle” banner
+* Pause API polling when user is inactive
+* Lock app after idle timeout in sensitive dashboards
+---
+
+
 
 
 ## 📄 License

src/idleTimer.js

@@ -0,0 +1,30 @@
+let timeoutId = null;
+const activityEvents = ["mousemove", "keydown", "scroll", "touchstart"];
+
+/**
+ * Detects user inactivity and runs a callback after given seconds.
+ * @param {number} seconds - Idle time in seconds before triggering
+ * @param {() => void} onIdle - Callback to run when user becomes idle
+ * @returns {() => void} - Function to stop the idle timer
+ */
+export function startIdleTimer(seconds, onIdle) {
+  const ms = seconds * 1000;
+
+  const resetTimer = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(onIdle, ms);
+  };
+
+  activityEvents.forEach((event) =>
+    window.addEventListener(event, resetTimer)
+  );
+
+  resetTimer(); // Start the initial timer
+
+  return () => {
+    clearTimeout(timeoutId);
+    activityEvents.forEach((event) =>
+      window.removeEventListener(event, resetTimer)
+    );
+  };
+}

src/index.js

@@ -5,3 +5,4 @@ export * from './vibration.js';
 export * from './network.js';
 export * from './tabVisibility.js';
 export * from './preventClose.js';
+export * from './idleTimer.js';

test/index.html

@@ -19,6 +19,8 @@ <h2>Clipboard Test</h2>
   <hr>
   <p id="tab-status">Tab visibility: ...</p>
   <hr>
+  <p id="idle">Status: Active</p>
+  <hr>
   <button id="enable">Enable Tab Protection</button>
 <button id="disable">Disable Tab Protection</button>
 

test/testScript.js

@@ -3,17 +3,22 @@ import { sendNotification } from '../src/index.js';
 import { getBatteryStatus } from '../src/index.js';
 import { isOnline, listenNetworkStatus } from "../src/index.js";
 import { listenTabVisibility } from "../src/index.js";
-  import { preventTabClose } from "../src/index.js";
+import { preventTabClose } from "../src/index.js";
+import { startIdleTimer } from "../src/index.js";
 
-  document.getElementById("enable").onclick = () => {
-    preventTabClose(true);
-    alert("Tab close protection enabled.");
-  };
+startIdleTimer(5, () => {
+  document.getElementById("idle").textContent = "💤 You are idle!";
+});
+
+document.getElementById("enable").onclick = () => {
+  preventTabClose(true);
+  alert("Tab close protection enabled.");
+};
 
-  document.getElementById("disable").onclick = () => {
-    preventTabClose(false);
-    alert("Tab close protection disabled.");
-  };
+document.getElementById("disable").onclick = () => {
+  preventTabClose(false);
+  alert("Tab close protection disabled.");
+};
 
 listenTabVisibility((visible) => {
   document.getElementById("tab-status").textContent =