@iblai/web-utils 1.11.11 → 1.12.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iblai/web-utils",
-  "version": "1.11.10",
+  "version": "1.11.12",
   "main": "./dist/index.js",
   "module": "./dist/index.esm.js",
   "types": "./dist/index.d.ts",

package/dist/web-utils/src/features/tracking/time-tracker.d.ts

@@ -3,27 +3,78 @@ export interface TimeTrackerConfig {
     onTimeUpdate: (url: string, timeSpent: number) => void;
     getCurrentUrl: () => string;
     onRouteChange?: (callback: () => void) => () => void;
+    /**
+     * Seconds of no user interaction (mouse, keyboard, touch, scroll) after
+     * which the user is considered idle and time tracking pauses. Set to 0 to
+     * disable idle detection. Defaults to 120 (2 minutes).
+     */
+    idleTimeoutSeconds?: number;
+    /**
+     * Pause tracking while the page/tab is hidden (Page Visibility API).
+     * Defaults to true.
+     */
+    pauseOnHidden?: boolean;
+    /**
+     * Pause tracking while the window loses focus (e.g. user switched to another
+     * application or window). Defaults to true.
+     */
+    pauseOnBlur?: boolean;
 }
 export interface TimeTrackerState {
     currentUrl: string;
-    startTime: number;
     intervalId: number | null;
     routeUnsubscribe: (() => void) | null;
+    /** Active time (ms) banked since the last reset. */
+    accumulatedMs: number;
+    /** Timestamp the current active window started, or null while inactive. */
+    activeSince: number | null;
+    isVisible: boolean;
+    isFocused: boolean;
+    isIdle: boolean;
+    idleTimerId: number | null;
 }
 export declare class TimeTracker {
     private state;
     private config;
+    private readonly idleTimeoutMs;
+    private readonly pauseOnHidden;
+    private readonly pauseOnBlur;
+    private readonly idleDetectionEnabled;
+    private lastActivityAt;
+    private readonly handleActivity;
+    private readonly handleVisibilityChange;
+    private readonly handleWindowFocus;
+    private readonly handleWindowBlur;
     constructor(config: TimeTrackerConfig);
     private initialize;
-    private startTracking;
-    private clearInterval;
-    private resetTimer;
+    /** Whether time should currently be counted. */
+    private isActive;
+    /**
+     * Reconcile the active window with the current activity signals: open a new
+     * window when the user becomes active, or bank the elapsed time when they
+     * become inactive.
+     */
+    private syncActiveWindow;
     private getTimeSpent;
+    private resetTimer;
+    private startTracking;
+    private clearTrackingInterval;
     private sendTimeUpdate;
     private handleRouteChange;
+    private attachActivityListeners;
+    private detachActivityListeners;
+    private startIdleTimer;
+    private clearIdleTimer;
+    private markIdle;
+    private onActivity;
+    private onVisibilityChange;
+    private onWindowFocus;
+    private onWindowBlur;
     pause(): void;
     resume(): void;
     destroy(): void;
     getCurrentUrl(): string;
     getTimeSpentSinceLastReset(): number;
+    /** Whether the user is currently considered active (present & interacting). */
+    getIsActive(): boolean;
 }