@uekichinos/sentinel 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `@uekichinos/sentinel` are documented here.
+
+## [0.1.0] - 2026-04-12
+### Added
+- Initial release
+- `createSentinel(options)` — create an idle detector instance
+- `sentinel.start()` — begin listening for activity
+- `sentinel.stop()` — remove all listeners and cancel the countdown
+- `sentinel.reset()` — restart the countdown, transitions idle → active if needed
+- `sentinel.isIdle()` — returns current idle state
+- TTL timeout strings: `'30s'`, `'5m'`, `'15m'`, `'1h'` and ms numbers
+- `onIdle` / `onActive` callbacks
+- `notify` option — fires a `fetch` request to a backend endpoint when idle
+- Dynamic `headers` function — evaluated at idle time for fresh tokens
+- `watchVisibility` — pauses countdown when the tab is hidden (default: true)
+- `throttle` — minimum ms between activity handler calls (default: 500)
+- `events` — configurable list of DOM events that count as activity
+- Fails silently on notify network errors — never blocks callbacks
+- ESM, CJS, and IIFE builds
+- Zero dependencies
+- 28 tests

package/README.md

@@ -0,0 +1,210 @@
+# @uekichinos/sentinel
+
+[![Socket Badge](https://badge.socket.dev/npm/package/@uekichinos/sentinel/0.1.0)](https://socket.dev/npm/package/@uekichinos/sentinel/overview/0.1.0)
+
+Lightweight idle detection for the browser. Fires callbacks and optionally notifies a backend when the user goes inactive. Zero dependencies.
+
+```js
+const sentinel = createSentinel({
+  timeout: '15m',
+  onIdle: () => showLogoutWarning(),
+  onActive: () => hideLogoutWarning(),
+})
+
+sentinel.start()
+```
+
+---
+
+## Installation
+
+```bash
+npm install @uekichinos/sentinel
+```
+
+---
+
+## Quick start
+
+```js
+import { createSentinel } from '@uekichinos/sentinel'
+
+const sentinel = createSentinel({
+  timeout: '15m',
+  onIdle: () => console.log('User is idle'),
+  onActive: () => console.log('User is back'),
+})
+
+sentinel.start()
+```
+
+---
+
+## API
+
+### `createSentinel(options)`
+
+Returns a `SentinelInstance`.
+
+```ts
+createSentinel(options: SentinelOptions): SentinelInstance
+```
+
+### `sentinel.start()`
+
+Begins listening for user activity and starts the idle countdown. Safe to call multiple times — idempotent.
+
+### `sentinel.stop()`
+
+Removes all event listeners and cancels the countdown. Resets internal state so `start()` can be called again.
+
+### `sentinel.reset()`
+
+Restarts the idle countdown from zero. If currently idle, transitions back to active and fires `onActive`.
+
+### `sentinel.isIdle()`
+
+Returns `true` if the user is currently idle.
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | `TtlInput` | — | How long before the user is considered idle |
+| `onIdle` | `() => void` | — | Called when the user transitions active → idle |
+| `onActive` | `() => void` | — | Called when the user transitions idle → active |
+| `notify` | `NotifyOptions` | — | Fetch a backend endpoint when idle (see below) |
+| `events` | `string[]` | see below | DOM events that count as activity |
+| `throttle` | `number` | `500` | Min ms between activity handler calls |
+| `watchVisibility` | `boolean` | `true` | Pause countdown when the tab is hidden |
+
+**Default events:** `mousemove`, `keydown`, `scroll`, `click`, `touchstart`
+
+---
+
+## TTL formats
+
+| Format | Duration |
+|--------|----------|
+| `'30s'` | 30 seconds |
+| `'5m'` | 5 minutes |
+| `'15m'` | 15 minutes |
+| `'1h'` | 1 hour |
+| `5000` | 5000 milliseconds |
+
+---
+
+## `notify` — backend notification
+
+Fire a fetch request automatically when the user goes idle. Useful for invalidating server-side sessions or logging inactivity.
+
+```js
+const sentinel = createSentinel({
+  timeout: '15m',
+  notify: {
+    url: '/api/session/idle',
+    method: 'POST',                          // default
+    headers: () => ({                        // function — evaluated at idle time
+      Authorization: `Bearer ${getToken()}`,
+      'Content-Type': 'application/json',
+    }),
+    body: { reason: 'idle' },
+  },
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | — | Endpoint to call |
+| `method` | `string` | `'POST'` | HTTP method |
+| `headers` | `Record<string, string> \| () => Record<string, string>` | — | Static or dynamic headers |
+| `body` | `unknown` | — | Request body — serialised to JSON |
+
+**Headers as a function** — the function is called at the moment idle fires, not at init. This ensures you always send a fresh token rather than one captured when the page loaded.
+
+```js
+// Token captured at init — may be stale after a refresh
+headers: { Authorization: `Bearer ${getToken()}` }
+
+// Token evaluated at idle time — always fresh
+headers: () => ({ Authorization: `Bearer ${getToken()}` })
+```
+
+The notify request fails silently on network error — `onIdle` always fires regardless.
+
+---
+
+## Examples
+
+### Auto-logout with session warning
+
+```js
+let warningTimer
+
+const sentinel = createSentinel({
+  timeout: '14m',
+  onIdle: () => {
+    showWarning('You will be logged out in 1 minute')
+    warningTimer = setTimeout(() => logout(), 60_000)
+  },
+  onActive: () => {
+    hideWarning()
+    clearTimeout(warningTimer)
+  },
+  notify: {
+    url: '/api/session/extend',
+    headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+  },
+})
+
+sentinel.start()
+```
+
+### Pause API polling when idle
+
+```js
+let pollInterval
+
+const sentinel = createSentinel({
+  timeout: '5m',
+  onIdle: () => {
+    clearInterval(pollInterval)
+  },
+  onActive: () => {
+    pollInterval = setInterval(fetchData, 5000)
+  },
+})
+
+pollInterval = setInterval(fetchData, 5000)
+sentinel.start()
+```
+
+### Stop on page unload
+
+```js
+sentinel.start()
+window.addEventListener('beforeunload', () => sentinel.stop())
+```
+
+---
+
+## Via `<script>` tag (no bundler)
+
+```html
+<script src="https://unpkg.com/@uekichinos/sentinel/dist/index.global.js"></script>
+<script>
+  const sentinel = Sentinel.createSentinel({
+    timeout: '15m',
+    onIdle: () => console.log('idle'),
+  })
+  sentinel.start()
+</script>
+```
+
+---
+
+## License
+
+MIT © [uekichinos](https://www.npmjs.com/~uekichinos)

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please **do not** open a public GitHub issue.
+
+Instead, report it privately via GitHub:
+[https://github.com/uekichinos/sentinel/security/advisories/new](https://github.com/uekichinos/sentinel/security/advisories/new)
+
+Please include:
+- A description of the vulnerability
+- Steps to reproduce
+- Potential impact
+
+You can expect a response within **72 hours**. If the vulnerability is confirmed, a fix will be released as soon as possible and credited to you (unless you prefer to remain anonymous).

package/dist/index.cjs

@@ -0,0 +1,153 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSentinel: () => createSentinel
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/parse-ttl.ts
+var UNITS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+function parseTtl(ttl) {
+  if (typeof ttl === "number") {
+    return ttl > 0 ? ttl : null;
+  }
+  const match = ttl.match(/^(\d+(?:\.\d+)?)(s|m|h|d)$/);
+  if (!match) return null;
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+  return value > 0 ? value * UNITS[unit] : null;
+}
+
+// src/index.ts
+var DEFAULT_EVENTS = ["mousemove", "keydown", "scroll", "click", "touchstart"];
+var DEFAULT_THROTTLE = 500;
+function resolveHeaders(headers) {
+  if (!headers) return {};
+  return typeof headers === "function" ? headers() : headers;
+}
+async function fireNotify(notify) {
+  const headers = resolveHeaders(notify.headers);
+  const hasBody = notify.body !== void 0;
+  try {
+    await fetch(notify.url, {
+      method: notify.method ?? "POST",
+      headers: {
+        ...hasBody ? { "Content-Type": "application/json" } : {},
+        ...headers
+      },
+      ...hasBody ? { body: JSON.stringify(notify.body) } : {}
+    });
+  } catch {
+  }
+}
+function createSentinel(options) {
+  const parsedTimeout = parseTtl(options.timeout);
+  if (!parsedTimeout) throw new Error(`@uekichinos/sentinel: invalid timeout "${options.timeout}"`);
+  const timeoutMs = parsedTimeout;
+  const events = options.events ?? DEFAULT_EVENTS;
+  const throttleMs = options.throttle ?? DEFAULT_THROTTLE;
+  const watchVisibility = options.watchVisibility ?? true;
+  let timer = null;
+  let idle = false;
+  let started = false;
+  let lastActivity = 0;
+  function scheduleIdle() {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      idle = true;
+      options.onIdle?.();
+      if (options.notify) fireNotify(options.notify);
+    }, timeoutMs);
+  }
+  function handleActivity() {
+    const now = Date.now();
+    if (now - lastActivity < throttleMs) return;
+    lastActivity = now;
+    if (idle) {
+      idle = false;
+      options.onActive?.();
+    }
+    scheduleIdle();
+  }
+  function handleVisibility() {
+    if (document.hidden) {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    } else {
+      handleActivity();
+    }
+  }
+  return {
+    start() {
+      if (started) return;
+      started = true;
+      idle = false;
+      lastActivity = Date.now();
+      for (const event of events) {
+        document.addEventListener(event, handleActivity, { passive: true });
+      }
+      if (watchVisibility) {
+        document.addEventListener("visibilitychange", handleVisibility);
+      }
+      scheduleIdle();
+    },
+    stop() {
+      if (!started) return;
+      started = false;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      for (const event of events) {
+        document.removeEventListener(event, handleActivity);
+      }
+      if (watchVisibility) {
+        document.removeEventListener("visibilitychange", handleVisibility);
+      }
+    },
+    reset() {
+      if (!started) return;
+      if (idle) {
+        idle = false;
+        options.onActive?.();
+      }
+      lastActivity = Date.now();
+      scheduleIdle();
+    },
+    isIdle() {
+      return idle;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSentinel
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+type TtlInput = number | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+type NotifyOptions = {
+    /** URL to POST to when the user goes idle */
+    url: string;
+    /** HTTP method — defaults to 'POST' */
+    method?: string;
+    /**
+     * Headers to include in the request.
+     * Pass a function to evaluate headers at call time — useful for dynamic tokens.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Optional request body — serialised to JSON */
+    body?: unknown;
+};
+type SentinelOptions = {
+    /** How long before the user is considered idle */
+    timeout: TtlInput;
+    /** DOM events that count as user activity (default: mousemove, keydown, scroll, click, touchstart) */
+    events?: string[];
+    /** Minimum ms between activity handler calls — prevents hammering on mousemove (default: 500) */
+    throttle?: number;
+    /** Pause the idle countdown while the tab is hidden (default: true) */
+    watchVisibility?: boolean;
+    /** Fire a fetch request when the user goes idle */
+    notify?: NotifyOptions;
+    /** Called when the user transitions from active → idle */
+    onIdle?: () => void;
+    /** Called when the user transitions from idle → active */
+    onActive?: () => void;
+};
+type SentinelInstance = {
+    /** Start listening for activity and begin the idle countdown */
+    start(): void;
+    /** Stop all listeners and cancel the countdown */
+    stop(): void;
+    /** Reset the idle countdown (and transition idle → active if currently idle) */
+    reset(): void;
+    /** Returns true if the user is currently idle */
+    isIdle(): boolean;
+};
+
+/**
+ * Creates an idle detector that fires callbacks and optionally notifies a
+ * backend endpoint when the user stops interacting with the page.
+ *
+ * @example
+ * const sentinel = createSentinel({
+ *   timeout: '15m',
+ *   notify: {
+ *     url: '/api/session/idle',
+ *     headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+ *   },
+ *   onIdle: () => showLogoutWarning(),
+ *   onActive: () => hideLogoutWarning(),
+ * })
+ *
+ * sentinel.start()
+ */
+declare function createSentinel(options: SentinelOptions): SentinelInstance;
+
+export { type NotifyOptions, type SentinelInstance, type SentinelOptions, type TtlInput, createSentinel };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+type TtlInput = number | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+type NotifyOptions = {
+    /** URL to POST to when the user goes idle */
+    url: string;
+    /** HTTP method — defaults to 'POST' */
+    method?: string;
+    /**
+     * Headers to include in the request.
+     * Pass a function to evaluate headers at call time — useful for dynamic tokens.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Optional request body — serialised to JSON */
+    body?: unknown;
+};
+type SentinelOptions = {
+    /** How long before the user is considered idle */
+    timeout: TtlInput;
+    /** DOM events that count as user activity (default: mousemove, keydown, scroll, click, touchstart) */
+    events?: string[];
+    /** Minimum ms between activity handler calls — prevents hammering on mousemove (default: 500) */
+    throttle?: number;
+    /** Pause the idle countdown while the tab is hidden (default: true) */
+    watchVisibility?: boolean;
+    /** Fire a fetch request when the user goes idle */
+    notify?: NotifyOptions;
+    /** Called when the user transitions from active → idle */
+    onIdle?: () => void;
+    /** Called when the user transitions from idle → active */
+    onActive?: () => void;
+};
+type SentinelInstance = {
+    /** Start listening for activity and begin the idle countdown */
+    start(): void;
+    /** Stop all listeners and cancel the countdown */
+    stop(): void;
+    /** Reset the idle countdown (and transition idle → active if currently idle) */
+    reset(): void;
+    /** Returns true if the user is currently idle */
+    isIdle(): boolean;
+};
+
+/**
+ * Creates an idle detector that fires callbacks and optionally notifies a
+ * backend endpoint when the user stops interacting with the page.
+ *
+ * @example
+ * const sentinel = createSentinel({
+ *   timeout: '15m',
+ *   notify: {
+ *     url: '/api/session/idle',
+ *     headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+ *   },
+ *   onIdle: () => showLogoutWarning(),
+ *   onActive: () => hideLogoutWarning(),
+ * })
+ *
+ * sentinel.start()
+ */
+declare function createSentinel(options: SentinelOptions): SentinelInstance;
+
+export { type NotifyOptions, type SentinelInstance, type SentinelOptions, type TtlInput, createSentinel };

package/dist/index.global.js

@@ -0,0 +1,151 @@
+"use strict";
+var Sentinel = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/index.ts
+  var index_exports = {};
+  __export(index_exports, {
+    createSentinel: () => createSentinel
+  });
+
+  // src/parse-ttl.ts
+  var UNITS = {
+    s: 1e3,
+    m: 6e4,
+    h: 36e5,
+    d: 864e5
+  };
+  function parseTtl(ttl) {
+    if (typeof ttl === "number") {
+      return ttl > 0 ? ttl : null;
+    }
+    const match = ttl.match(/^(\d+(?:\.\d+)?)(s|m|h|d)$/);
+    if (!match) return null;
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    return value > 0 ? value * UNITS[unit] : null;
+  }
+
+  // src/index.ts
+  var DEFAULT_EVENTS = ["mousemove", "keydown", "scroll", "click", "touchstart"];
+  var DEFAULT_THROTTLE = 500;
+  function resolveHeaders(headers) {
+    if (!headers) return {};
+    return typeof headers === "function" ? headers() : headers;
+  }
+  async function fireNotify(notify) {
+    const headers = resolveHeaders(notify.headers);
+    const hasBody = notify.body !== void 0;
+    try {
+      await fetch(notify.url, {
+        method: notify.method ?? "POST",
+        headers: {
+          ...hasBody ? { "Content-Type": "application/json" } : {},
+          ...headers
+        },
+        ...hasBody ? { body: JSON.stringify(notify.body) } : {}
+      });
+    } catch {
+    }
+  }
+  function createSentinel(options) {
+    const parsedTimeout = parseTtl(options.timeout);
+    if (!parsedTimeout) throw new Error(`@uekichinos/sentinel: invalid timeout "${options.timeout}"`);
+    const timeoutMs = parsedTimeout;
+    const events = options.events ?? DEFAULT_EVENTS;
+    const throttleMs = options.throttle ?? DEFAULT_THROTTLE;
+    const watchVisibility = options.watchVisibility ?? true;
+    let timer = null;
+    let idle = false;
+    let started = false;
+    let lastActivity = 0;
+    function scheduleIdle() {
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        idle = true;
+        options.onIdle?.();
+        if (options.notify) fireNotify(options.notify);
+      }, timeoutMs);
+    }
+    function handleActivity() {
+      const now = Date.now();
+      if (now - lastActivity < throttleMs) return;
+      lastActivity = now;
+      if (idle) {
+        idle = false;
+        options.onActive?.();
+      }
+      scheduleIdle();
+    }
+    function handleVisibility() {
+      if (document.hidden) {
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      } else {
+        handleActivity();
+      }
+    }
+    return {
+      start() {
+        if (started) return;
+        started = true;
+        idle = false;
+        lastActivity = Date.now();
+        for (const event of events) {
+          document.addEventListener(event, handleActivity, { passive: true });
+        }
+        if (watchVisibility) {
+          document.addEventListener("visibilitychange", handleVisibility);
+        }
+        scheduleIdle();
+      },
+      stop() {
+        if (!started) return;
+        started = false;
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        for (const event of events) {
+          document.removeEventListener(event, handleActivity);
+        }
+        if (watchVisibility) {
+          document.removeEventListener("visibilitychange", handleVisibility);
+        }
+      },
+      reset() {
+        if (!started) return;
+        if (idle) {
+          idle = false;
+          options.onActive?.();
+        }
+        lastActivity = Date.now();
+        scheduleIdle();
+      },
+      isIdle() {
+        return idle;
+      }
+    };
+  }
+  return __toCommonJS(index_exports);
+})();
+//# sourceMappingURL=index.global.js.map

package/dist/index.js

@@ -0,0 +1,126 @@
+// src/parse-ttl.ts
+var UNITS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+function parseTtl(ttl) {
+  if (typeof ttl === "number") {
+    return ttl > 0 ? ttl : null;
+  }
+  const match = ttl.match(/^(\d+(?:\.\d+)?)(s|m|h|d)$/);
+  if (!match) return null;
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+  return value > 0 ? value * UNITS[unit] : null;
+}
+
+// src/index.ts
+var DEFAULT_EVENTS = ["mousemove", "keydown", "scroll", "click", "touchstart"];
+var DEFAULT_THROTTLE = 500;
+function resolveHeaders(headers) {
+  if (!headers) return {};
+  return typeof headers === "function" ? headers() : headers;
+}
+async function fireNotify(notify) {
+  const headers = resolveHeaders(notify.headers);
+  const hasBody = notify.body !== void 0;
+  try {
+    await fetch(notify.url, {
+      method: notify.method ?? "POST",
+      headers: {
+        ...hasBody ? { "Content-Type": "application/json" } : {},
+        ...headers
+      },
+      ...hasBody ? { body: JSON.stringify(notify.body) } : {}
+    });
+  } catch {
+  }
+}
+function createSentinel(options) {
+  const parsedTimeout = parseTtl(options.timeout);
+  if (!parsedTimeout) throw new Error(`@uekichinos/sentinel: invalid timeout "${options.timeout}"`);
+  const timeoutMs = parsedTimeout;
+  const events = options.events ?? DEFAULT_EVENTS;
+  const throttleMs = options.throttle ?? DEFAULT_THROTTLE;
+  const watchVisibility = options.watchVisibility ?? true;
+  let timer = null;
+  let idle = false;
+  let started = false;
+  let lastActivity = 0;
+  function scheduleIdle() {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      idle = true;
+      options.onIdle?.();
+      if (options.notify) fireNotify(options.notify);
+    }, timeoutMs);
+  }
+  function handleActivity() {
+    const now = Date.now();
+    if (now - lastActivity < throttleMs) return;
+    lastActivity = now;
+    if (idle) {
+      idle = false;
+      options.onActive?.();
+    }
+    scheduleIdle();
+  }
+  function handleVisibility() {
+    if (document.hidden) {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    } else {
+      handleActivity();
+    }
+  }
+  return {
+    start() {
+      if (started) return;
+      started = true;
+      idle = false;
+      lastActivity = Date.now();
+      for (const event of events) {
+        document.addEventListener(event, handleActivity, { passive: true });
+      }
+      if (watchVisibility) {
+        document.addEventListener("visibilitychange", handleVisibility);
+      }
+      scheduleIdle();
+    },
+    stop() {
+      if (!started) return;
+      started = false;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      for (const event of events) {
+        document.removeEventListener(event, handleActivity);
+      }
+      if (watchVisibility) {
+        document.removeEventListener("visibilitychange", handleVisibility);
+      }
+    },
+    reset() {
+      if (!started) return;
+      if (idle) {
+        idle = false;
+        options.onActive?.();
+      }
+      lastActivity = Date.now();
+      scheduleIdle();
+    },
+    isIdle() {
+      return idle;
+    }
+  };
+}
+export {
+  createSentinel
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@uekichinos/sentinel",
+  "version": "0.1.0",
+  "description": "Lightweight idle detection for the browser. Fires callbacks and optionally notifies a backend when the user goes inactive. Supports TTL timeouts, tab visibility pausing, activity throttling, and dynamic auth headers. Zero dependencies.",
+  "keywords": [
+    "uekichinos",
+    "sentinel",
+    "idle",
+    "idle-detection",
+    "inactivity",
+    "session-timeout",
+    "auto-logout",
+    "user-activity",
+    "visibility"
+  ],
+  "author": {
+    "name": "uekichinos",
+    "url": "https://www.npmjs.com/~uekichinos"
+  },
+  "homepage": "https://github.com/uekichinos/sentinel#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uekichinos/sentinel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uekichinos/sentinel/issues"
+  },
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/uekichinos"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.cjs",
+    "dist/*.d.ts",
+    "dist/*.d.cts",
+    "dist/*.global.js",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.8.9",
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4",
+    "vitest": "^3.2.4"
+  }
+}