@uekichinos/sentinel 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@uekichinos/sentinel` are documented here.
 
+## [0.2.0] - 2026-04-12
+### Added
+- `sentinel.getRemainingMs()` — returns milliseconds until idle; useful for countdown indicators and progress bars
+- `notify.body` factory function — `body` can now be `() => unknown`, evaluated at idle time rather than at init; useful for capturing dynamic state (e.g. current user ID or session ID)
+- Async `notify.headers` support — `headers` function can now return `Promise<Record<string, string>>`, enabling async token refresh before the idle request fires
+- 17 new tests covering the above additions (45 total)
+
 ## [0.1.0] - 2026-04-12
 ### Added
 - Initial release

package/README.md

@@ -66,6 +66,18 @@ Restarts the idle countdown from zero. If currently idle, transitions back to ac
 
 Returns `true` if the user is currently idle.
 
+### `sentinel.getRemainingMs()`
+
+Returns the number of milliseconds remaining until the user is considered idle. Returns `0` when already idle or when the sentinel has not been started.
+
+Useful for building countdown indicators or progress bars:
+
+```js
+setInterval(() => {
+  progressBar.style.width = `${(sentinel.getRemainingMs() / timeoutMs) * 100}%`
+}, 100)
+```
+
 ---
 
 ## Options
@@ -119,17 +131,26 @@ const sentinel = createSentinel({
 |--------|------|---------|-------------|
 | `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` | `Record<string, string> \| () => Record<string, string> \| Promise<Record<string, string>>` | — | Static or dynamic headers (sync or async) |
+| `body` | `unknown \| () => unknown` | — | Request body — serialised to JSON, or a factory evaluated at idle time |
 
-**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.
+**Headers as a function** — the function is called at the moment idle fires, not at init. Supports both sync and async functions. 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
+// Token evaluated at idle time — always fresh (sync)
 headers: () => ({ Authorization: `Bearer ${getToken()}` })
+
+// Async token refresh — awaited before the request fires
+headers: async () => ({ Authorization: `Bearer ${await refreshToken()}` })
+```
+
+**Body as a function** — like headers, a body factory is evaluated at idle time rather than at init. Useful for capturing dynamic state:
+
+```js
+body: () => ({ userId: store.user.id, sessionId: store.session.id })
 ```
 
 The notify request fails silently on network error — `onIdle` always fires regardless.
@@ -181,6 +202,20 @@ pollInterval = setInterval(fetchData, 5000)
 sentinel.start()
 ```
 
+### Countdown indicator
+
+```js
+const TIMEOUT_MS = 15 * 60 * 1000 // 15m in ms
+
+const sentinel = createSentinel({ timeout: TIMEOUT_MS })
+sentinel.start()
+
+setInterval(() => {
+  const pct = (sentinel.getRemainingMs() / TIMEOUT_MS) * 100
+  progressBar.style.width = `${pct}%`
+}, 200)
+```
+
 ### Stop on page unload
 
 ```js

package/dist/index.cjs

@@ -45,13 +45,18 @@ function parseTtl(ttl) {
 // src/index.ts
 var DEFAULT_EVENTS = ["mousemove", "keydown", "scroll", "click", "touchstart"];
 var DEFAULT_THROTTLE = 500;
-function resolveHeaders(headers) {
+async function resolveHeaders(headers) {
   if (!headers) return {};
-  return typeof headers === "function" ? headers() : headers;
+  const result = typeof headers === "function" ? headers() : headers;
+  return result instanceof Promise ? await result : result;
+}
+function resolveBody(body) {
+  return typeof body === "function" ? body() : body;
 }
 async function fireNotify(notify) {
-  const headers = resolveHeaders(notify.headers);
-  const hasBody = notify.body !== void 0;
+  const headers = await resolveHeaders(notify.headers);
+  const body = resolveBody(notify.body);
+  const hasBody = body !== void 0;
   try {
     await fetch(notify.url, {
       method: notify.method ?? "POST",
@@ -59,7 +64,7 @@ async function fireNotify(notify) {
         ...hasBody ? { "Content-Type": "application/json" } : {},
         ...headers
       },
-      ...hasBody ? { body: JSON.stringify(notify.body) } : {}
+      ...hasBody ? { body: JSON.stringify(body) } : {}
     });
   } catch {
   }
@@ -72,13 +77,16 @@ function createSentinel(options) {
   const throttleMs = options.throttle ?? DEFAULT_THROTTLE;
   const watchVisibility = options.watchVisibility ?? true;
   let timer = null;
+  let timerTarget = null;
   let idle = false;
   let started = false;
   let lastActivity = 0;
   function scheduleIdle() {
     if (timer !== null) clearTimeout(timer);
+    timerTarget = Date.now() + timeoutMs;
     timer = setTimeout(() => {
       timer = null;
+      timerTarget = null;
       idle = true;
       options.onIdle?.();
       if (options.notify) fireNotify(options.notify);
@@ -143,6 +151,10 @@ function createSentinel(options) {
     },
     isIdle() {
       return idle;
+    },
+    getRemainingMs() {
+      if (idle || !started || timerTarget === null) return 0;
+      return Math.max(0, timerTarget - Date.now());
     }
   };
 }

package/dist/index.d.cts

@@ -6,11 +6,14 @@ type NotifyOptions = {
     method?: string;
     /**
      * Headers to include in the request.
-     * Pass a function to evaluate headers at call time — useful for dynamic tokens.
+     * Pass a function (sync or async) to evaluate headers at call time — useful for dynamic or refreshed tokens.
      */
-    headers?: Record<string, string> | (() => Record<string, string>);
-    /** Optional request body — serialised to JSON */
-    body?: unknown;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Optional request body — serialised to JSON.
+     * Pass a function to evaluate the body at idle time — useful for capturing dynamic state.
+     */
+    body?: unknown | (() => unknown);
 };
 type SentinelOptions = {
     /** How long before the user is considered idle */
@@ -37,6 +40,8 @@ type SentinelInstance = {
     reset(): void;
     /** Returns true if the user is currently idle */
     isIdle(): boolean;
+    /** Returns milliseconds remaining until idle. Returns 0 when already idle or not started. */
+    getRemainingMs(): number;
 };
 
 /**

package/dist/index.d.ts

@@ -6,11 +6,14 @@ type NotifyOptions = {
     method?: string;
     /**
      * Headers to include in the request.
-     * Pass a function to evaluate headers at call time — useful for dynamic tokens.
+     * Pass a function (sync or async) to evaluate headers at call time — useful for dynamic or refreshed tokens.
      */
-    headers?: Record<string, string> | (() => Record<string, string>);
-    /** Optional request body — serialised to JSON */
-    body?: unknown;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Optional request body — serialised to JSON.
+     * Pass a function to evaluate the body at idle time — useful for capturing dynamic state.
+     */
+    body?: unknown | (() => unknown);
 };
 type SentinelOptions = {
     /** How long before the user is considered idle */
@@ -37,6 +40,8 @@ type SentinelInstance = {
     reset(): void;
     /** Returns true if the user is currently idle */
     isIdle(): boolean;
+    /** Returns milliseconds remaining until idle. Returns 0 when already idle or not started. */
+    getRemainingMs(): number;
 };
 
 /**

package/dist/index.global.js

@@ -45,13 +45,18 @@ var Sentinel = (() => {
   // src/index.ts
   var DEFAULT_EVENTS = ["mousemove", "keydown", "scroll", "click", "touchstart"];
   var DEFAULT_THROTTLE = 500;
-  function resolveHeaders(headers) {
+  async function resolveHeaders(headers) {
     if (!headers) return {};
-    return typeof headers === "function" ? headers() : headers;
+    const result = typeof headers === "function" ? headers() : headers;
+    return result instanceof Promise ? await result : result;
+  }
+  function resolveBody(body) {
+    return typeof body === "function" ? body() : body;
   }
   async function fireNotify(notify) {
-    const headers = resolveHeaders(notify.headers);
-    const hasBody = notify.body !== void 0;
+    const headers = await resolveHeaders(notify.headers);
+    const body = resolveBody(notify.body);
+    const hasBody = body !== void 0;
     try {
       await fetch(notify.url, {
         method: notify.method ?? "POST",
@@ -59,7 +64,7 @@ var Sentinel = (() => {
           ...hasBody ? { "Content-Type": "application/json" } : {},
           ...headers
         },
-        ...hasBody ? { body: JSON.stringify(notify.body) } : {}
+        ...hasBody ? { body: JSON.stringify(body) } : {}
       });
     } catch {
     }
@@ -72,13 +77,16 @@ var Sentinel = (() => {
     const throttleMs = options.throttle ?? DEFAULT_THROTTLE;
     const watchVisibility = options.watchVisibility ?? true;
     let timer = null;
+    let timerTarget = null;
     let idle = false;
     let started = false;
     let lastActivity = 0;
     function scheduleIdle() {
       if (timer !== null) clearTimeout(timer);
+      timerTarget = Date.now() + timeoutMs;
       timer = setTimeout(() => {
         timer = null;
+        timerTarget = null;
         idle = true;
         options.onIdle?.();
         if (options.notify) fireNotify(options.notify);
@@ -143,6 +151,10 @@ var Sentinel = (() => {
       },
       isIdle() {
         return idle;
+      },
+      getRemainingMs() {
+        if (idle || !started || timerTarget === null) return 0;
+        return Math.max(0, timerTarget - Date.now());
       }
     };
   }

package/dist/index.js

@@ -19,13 +19,18 @@ function parseTtl(ttl) {
 // src/index.ts
 var DEFAULT_EVENTS = ["mousemove", "keydown", "scroll", "click", "touchstart"];
 var DEFAULT_THROTTLE = 500;
-function resolveHeaders(headers) {
+async function resolveHeaders(headers) {
   if (!headers) return {};
-  return typeof headers === "function" ? headers() : headers;
+  const result = typeof headers === "function" ? headers() : headers;
+  return result instanceof Promise ? await result : result;
+}
+function resolveBody(body) {
+  return typeof body === "function" ? body() : body;
 }
 async function fireNotify(notify) {
-  const headers = resolveHeaders(notify.headers);
-  const hasBody = notify.body !== void 0;
+  const headers = await resolveHeaders(notify.headers);
+  const body = resolveBody(notify.body);
+  const hasBody = body !== void 0;
   try {
     await fetch(notify.url, {
       method: notify.method ?? "POST",
@@ -33,7 +38,7 @@ async function fireNotify(notify) {
         ...hasBody ? { "Content-Type": "application/json" } : {},
         ...headers
       },
-      ...hasBody ? { body: JSON.stringify(notify.body) } : {}
+      ...hasBody ? { body: JSON.stringify(body) } : {}
     });
   } catch {
   }
@@ -46,13 +51,16 @@ function createSentinel(options) {
   const throttleMs = options.throttle ?? DEFAULT_THROTTLE;
   const watchVisibility = options.watchVisibility ?? true;
   let timer = null;
+  let timerTarget = null;
   let idle = false;
   let started = false;
   let lastActivity = 0;
   function scheduleIdle() {
     if (timer !== null) clearTimeout(timer);
+    timerTarget = Date.now() + timeoutMs;
     timer = setTimeout(() => {
       timer = null;
+      timerTarget = null;
       idle = true;
       options.onIdle?.();
       if (options.notify) fireNotify(options.notify);
@@ -117,6 +125,10 @@ function createSentinel(options) {
     },
     isIdle() {
       return idle;
+    },
+    getRemainingMs() {
+      if (idle || !started || timerTarget === null) return 0;
+      return Math.max(0, timerTarget - Date.now());
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uekichinos/sentinel",
-  "version": "0.1.0",
+  "version": "0.2.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",