nova-hooks 2.0.0

package/dist/index.cjs.js

@@ -0,0 +1,232 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let socket_io_client = require("socket.io-client");
+let react = require("react");
+//#region src/socket.ts
+var socket;
+var projectName;
+/**
+* Connects to the socket server and emits a connection event
+* @param socketUrl The URL of the socket server to connect to
+*/
+var connectSocket = (socketUrl, project) => {
+	if (!socketUrl || socketUrl.trim() === "") throw new Error("Socket URL is required to connect.");
+	if (!project || project.trim() === "") throw new Error("Project name is required to connect.");
+	if (socket) return;
+	socket = (0, socket_io_client.io)(socketUrl);
+	projectName = project;
+	socket.on("connect", () => {
+		console.log("Nova socket connected");
+	});
+	socket.on("disconnect", () => {
+		console.log("Nova socket disconnected");
+	});
+};
+/**
+* Disconnects the socket server and cleans up the instance
+*/
+var disconnectSocket = () => {
+	if (socket) {
+		socket.disconnect();
+		socket = void 0;
+	}
+};
+//#endregion
+//#region src/event-bus.ts
+var SimpleEventEmitter = class {
+	listeners = {};
+	on(event, callback) {
+		if (!this.listeners[event]) this.listeners[event] = [];
+		this.listeners[event].push(callback);
+	}
+	emit(event, data) {
+		if (this.listeners[event]) this.listeners[event].forEach((cb) => cb(data));
+	}
+};
+var ActionType = {
+	Button: "Button",
+	Menu: "Menu",
+	Login: "Login",
+	Link: "Link"
+};
+var PageVisitAction = "Page Visit";
+var APP_EVENT = "APP_EVENT";
+var eventBus = new SimpleEventEmitter();
+var NOVA_USER_ACTIVITY_EVENT = "nova-user-activity";
+var pendingClicks = /* @__PURE__ */ new Map();
+var batchTimer = null;
+/**
+* Event listener for APP_EVENT that processes and enriches event data
+* Adds project name, timestamp, and page context before sending to server
+*/
+eventBus.on(APP_EVENT, (eventData) => {
+	if (!eventData) return;
+	try {
+		if (!socket) {
+			console.warn("Nova socket is not initialized. Please call connectSocket first.");
+			return;
+		}
+		const pageUrl = typeof window !== "undefined" ? window.location.pathname : "Unknown";
+		const pageTitle = typeof document !== "undefined" ? document.title : "Unknown";
+		const enrichedEvent = {
+			...eventData,
+			Project: projectName,
+			CreatedDate: (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").replace("Z", ""),
+			PageUrl: pageUrl,
+			PageTitle: pageTitle
+		};
+		if (enrichedEvent.ActionType !== "Page Visit") {
+			const key = `${enrichedEvent.ActionType}-${enrichedEvent.Action}-${enrichedEvent.PageUrl}`;
+			if (pendingClicks.has(key)) {
+				const existing = pendingClicks.get(key);
+				if ("Count" in existing && "Count" in enrichedEvent) existing.Count += enrichedEvent.Count || 1;
+				existing.CreatedDate = enrichedEvent.CreatedDate;
+			} else pendingClicks.set(key, enrichedEvent);
+			if (!batchTimer) batchTimer = setTimeout(() => {
+				pendingClicks.forEach((event) => {
+					socket?.emit(NOVA_USER_ACTIVITY_EVENT, event);
+				});
+				pendingClicks.clear();
+				batchTimer = null;
+			}, 1e3);
+		} else socket?.emit(NOVA_USER_ACTIVITY_EVENT, enrichedEvent);
+	} catch (error) {
+		console.error("Nova Error: ", error);
+	}
+});
+/**
+* Emits an event with the provided event data and optionally executes a callback function
+* @param eventData The event data to be emitted
+* @param callback Optional callback function to be executed before emitting the event
+*/
+function withEvent(eventData, callback) {
+	if (callback && typeof callback === "function") callback();
+	eventBus.emit(APP_EVENT, eventData);
+}
+//#endregion
+//#region src/hooks.ts
+var getCssPath = (el) => {
+	const path = [];
+	let current = el;
+	while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.body) {
+		let selector = current.tagName.toLowerCase();
+		if (current.id) {
+			selector += `#${current.id}`;
+			path.unshift(selector);
+			break;
+		} else if (current.className && typeof current.className === "string") selector += `.${current.className.trim().split(/\s+/).join(".")}`;
+		path.unshift(selector);
+		current = current.parentElement;
+	}
+	return path.join(" > ");
+};
+/**
+* Hook to track global click events and emit them to the server
+* Listens for click events on the document and automatically captures button/link clicks
+* @param empId Optional employee ID for tracking
+* @param roleId Optional role ID for tracking
+*/
+var useGlobalClickTracker = (empId, roleId) => {
+	(0, react.useEffect)(() => {
+		if (typeof window === "undefined") return;
+		const handler = (e) => {
+			let target = e.target;
+			while (target && target !== document.body) {
+				let trackId = target.getAttribute("data-nova-track-id");
+				let actionType = target.getAttribute("data-nova-track-type");
+				if (!trackId) {
+					const tagName = target.tagName.toLowerCase();
+					const role = target.getAttribute("role");
+					const isButton = tagName === "button" || role === "button" || tagName === "input" && (target.type === "submit" || target.type === "button");
+					const isLink = tagName === "a";
+					const isInteractiveRole = role === "menuitem" || role === "tab" || role === "option";
+					const isClickableDiv = window.getComputedStyle(target).cursor === "pointer";
+					if (isButton || isLink || isInteractiveRole || isClickableDiv) {
+						trackId = target.innerText?.trim() || target.getAttribute("aria-label")?.trim() || target.title?.trim() || target.getAttribute("name")?.trim() || `[UI Path] ${getCssPath(target)}`;
+						actionType = isLink ? "Link" : isButton ? "Button" : "Menu";
+						if (trackId.length > 80) trackId = trackId.substring(0, 80) + "...";
+					}
+				}
+				if (trackId && actionType) {
+					withEvent({
+						Action: trackId,
+						ActionType: actionType,
+						EmpId: empId || "UNKNOWN",
+						EmpRole: roleId || "UNKNOWN",
+						Count: 1
+					});
+					break;
+				}
+				target = target.parentElement;
+			}
+		};
+		document.addEventListener("click", handler);
+		return () => {
+			document.removeEventListener("click", handler);
+		};
+	}, [empId, roleId]);
+};
+var DURATION_THRESHOLD = 5;
+/**
+* Hook to track accurate active page visit duration
+* Uses Page Visibility API to only count time when the tab is actively visible
+* @param action The action name for the page visit
+* @param empId Optional employee ID for tracking
+* @param empRole Optional employee role for tracking
+*/
+var usePageTimeTracker = (action, empId, empRole) => {
+	const activeTimeRef = (0, react.useRef)(0);
+	const lastVisibleTimeRef = (0, react.useRef)(Date.now());
+	const isVisibleRef = (0, react.useRef)(true);
+	(0, react.useEffect)(() => {
+		if (typeof window === "undefined") return;
+		lastVisibleTimeRef.current = Date.now();
+		isVisibleRef.current = document.visibilityState === "visible";
+		const handleVisibilityChange = () => {
+			if (document.visibilityState === "visible") {
+				lastVisibleTimeRef.current = Date.now();
+				isVisibleRef.current = true;
+			} else {
+				if (isVisibleRef.current) activeTimeRef.current += Date.now() - lastVisibleTimeRef.current;
+				isVisibleRef.current = false;
+			}
+		};
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		return () => {
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+			let totalActiveTime = activeTimeRef.current;
+			if (isVisibleRef.current) totalActiveTime += Date.now() - lastVisibleTimeRef.current;
+			const duration = Math.round(totalActiveTime / 1e3);
+			if (duration > DURATION_THRESHOLD) withEvent({
+				Action: action,
+				ActionType: PageVisitAction,
+				EmpId: empId || "UNKNOWN",
+				EmpRole: empRole || "UNKNOWN",
+				Duration: duration
+			});
+		};
+	}, [
+		action,
+		empId,
+		empRole
+	]);
+};
+//#endregion
+exports.ActionType = ActionType;
+exports.PageVisitAction = PageVisitAction;
+exports.connectSocket = connectSocket;
+exports.disconnectSocket = disconnectSocket;
+Object.defineProperty(exports, "projectName", {
+	enumerable: true,
+	get: function() {
+		return projectName;
+	}
+});
+Object.defineProperty(exports, "socket", {
+	enumerable: true,
+	get: function() {
+		return socket;
+	}
+});
+exports.useGlobalClickTracker = useGlobalClickTracker;
+exports.usePageTimeTracker = usePageTimeTracker;
+exports.withEvent = withEvent;

package/dist/index.es.js

@@ -0,0 +1,213 @@
+import { io } from "socket.io-client";
+import { useEffect, useRef } from "react";
+//#region src/socket.ts
+var socket;
+var projectName;
+/**
+* Connects to the socket server and emits a connection event
+* @param socketUrl The URL of the socket server to connect to
+*/
+var connectSocket = (socketUrl, project) => {
+	if (!socketUrl || socketUrl.trim() === "") throw new Error("Socket URL is required to connect.");
+	if (!project || project.trim() === "") throw new Error("Project name is required to connect.");
+	if (socket) return;
+	socket = io(socketUrl);
+	projectName = project;
+	socket.on("connect", () => {
+		console.log("Nova socket connected");
+	});
+	socket.on("disconnect", () => {
+		console.log("Nova socket disconnected");
+	});
+};
+/**
+* Disconnects the socket server and cleans up the instance
+*/
+var disconnectSocket = () => {
+	if (socket) {
+		socket.disconnect();
+		socket = void 0;
+	}
+};
+//#endregion
+//#region src/event-bus.ts
+var SimpleEventEmitter = class {
+	listeners = {};
+	on(event, callback) {
+		if (!this.listeners[event]) this.listeners[event] = [];
+		this.listeners[event].push(callback);
+	}
+	emit(event, data) {
+		if (this.listeners[event]) this.listeners[event].forEach((cb) => cb(data));
+	}
+};
+var ActionType = {
+	Button: "Button",
+	Menu: "Menu",
+	Login: "Login",
+	Link: "Link"
+};
+var PageVisitAction = "Page Visit";
+var APP_EVENT = "APP_EVENT";
+var eventBus = new SimpleEventEmitter();
+var NOVA_USER_ACTIVITY_EVENT = "nova-user-activity";
+var pendingClicks = /* @__PURE__ */ new Map();
+var batchTimer = null;
+/**
+* Event listener for APP_EVENT that processes and enriches event data
+* Adds project name, timestamp, and page context before sending to server
+*/
+eventBus.on(APP_EVENT, (eventData) => {
+	if (!eventData) return;
+	try {
+		if (!socket) {
+			console.warn("Nova socket is not initialized. Please call connectSocket first.");
+			return;
+		}
+		const pageUrl = typeof window !== "undefined" ? window.location.pathname : "Unknown";
+		const pageTitle = typeof document !== "undefined" ? document.title : "Unknown";
+		const enrichedEvent = {
+			...eventData,
+			Project: projectName,
+			CreatedDate: (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").replace("Z", ""),
+			PageUrl: pageUrl,
+			PageTitle: pageTitle
+		};
+		if (enrichedEvent.ActionType !== "Page Visit") {
+			const key = `${enrichedEvent.ActionType}-${enrichedEvent.Action}-${enrichedEvent.PageUrl}`;
+			if (pendingClicks.has(key)) {
+				const existing = pendingClicks.get(key);
+				if ("Count" in existing && "Count" in enrichedEvent) existing.Count += enrichedEvent.Count || 1;
+				existing.CreatedDate = enrichedEvent.CreatedDate;
+			} else pendingClicks.set(key, enrichedEvent);
+			if (!batchTimer) batchTimer = setTimeout(() => {
+				pendingClicks.forEach((event) => {
+					socket?.emit(NOVA_USER_ACTIVITY_EVENT, event);
+				});
+				pendingClicks.clear();
+				batchTimer = null;
+			}, 1e3);
+		} else socket?.emit(NOVA_USER_ACTIVITY_EVENT, enrichedEvent);
+	} catch (error) {
+		console.error("Nova Error: ", error);
+	}
+});
+/**
+* Emits an event with the provided event data and optionally executes a callback function
+* @param eventData The event data to be emitted
+* @param callback Optional callback function to be executed before emitting the event
+*/
+function withEvent(eventData, callback) {
+	if (callback && typeof callback === "function") callback();
+	eventBus.emit(APP_EVENT, eventData);
+}
+//#endregion
+//#region src/hooks.ts
+var getCssPath = (el) => {
+	const path = [];
+	let current = el;
+	while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.body) {
+		let selector = current.tagName.toLowerCase();
+		if (current.id) {
+			selector += `#${current.id}`;
+			path.unshift(selector);
+			break;
+		} else if (current.className && typeof current.className === "string") selector += `.${current.className.trim().split(/\s+/).join(".")}`;
+		path.unshift(selector);
+		current = current.parentElement;
+	}
+	return path.join(" > ");
+};
+/**
+* Hook to track global click events and emit them to the server
+* Listens for click events on the document and automatically captures button/link clicks
+* @param empId Optional employee ID for tracking
+* @param roleId Optional role ID for tracking
+*/
+var useGlobalClickTracker = (empId, roleId) => {
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		const handler = (e) => {
+			let target = e.target;
+			while (target && target !== document.body) {
+				let trackId = target.getAttribute("data-nova-track-id");
+				let actionType = target.getAttribute("data-nova-track-type");
+				if (!trackId) {
+					const tagName = target.tagName.toLowerCase();
+					const role = target.getAttribute("role");
+					const isButton = tagName === "button" || role === "button" || tagName === "input" && (target.type === "submit" || target.type === "button");
+					const isLink = tagName === "a";
+					const isInteractiveRole = role === "menuitem" || role === "tab" || role === "option";
+					const isClickableDiv = window.getComputedStyle(target).cursor === "pointer";
+					if (isButton || isLink || isInteractiveRole || isClickableDiv) {
+						trackId = target.innerText?.trim() || target.getAttribute("aria-label")?.trim() || target.title?.trim() || target.getAttribute("name")?.trim() || `[UI Path] ${getCssPath(target)}`;
+						actionType = isLink ? "Link" : isButton ? "Button" : "Menu";
+						if (trackId.length > 80) trackId = trackId.substring(0, 80) + "...";
+					}
+				}
+				if (trackId && actionType) {
+					withEvent({
+						Action: trackId,
+						ActionType: actionType,
+						EmpId: empId || "UNKNOWN",
+						EmpRole: roleId || "UNKNOWN",
+						Count: 1
+					});
+					break;
+				}
+				target = target.parentElement;
+			}
+		};
+		document.addEventListener("click", handler);
+		return () => {
+			document.removeEventListener("click", handler);
+		};
+	}, [empId, roleId]);
+};
+var DURATION_THRESHOLD = 5;
+/**
+* Hook to track accurate active page visit duration
+* Uses Page Visibility API to only count time when the tab is actively visible
+* @param action The action name for the page visit
+* @param empId Optional employee ID for tracking
+* @param empRole Optional employee role for tracking
+*/
+var usePageTimeTracker = (action, empId, empRole) => {
+	const activeTimeRef = useRef(0);
+	const lastVisibleTimeRef = useRef(Date.now());
+	const isVisibleRef = useRef(true);
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		lastVisibleTimeRef.current = Date.now();
+		isVisibleRef.current = document.visibilityState === "visible";
+		const handleVisibilityChange = () => {
+			if (document.visibilityState === "visible") {
+				lastVisibleTimeRef.current = Date.now();
+				isVisibleRef.current = true;
+			} else {
+				if (isVisibleRef.current) activeTimeRef.current += Date.now() - lastVisibleTimeRef.current;
+				isVisibleRef.current = false;
+			}
+		};
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		return () => {
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+			let totalActiveTime = activeTimeRef.current;
+			if (isVisibleRef.current) totalActiveTime += Date.now() - lastVisibleTimeRef.current;
+			const duration = Math.round(totalActiveTime / 1e3);
+			if (duration > DURATION_THRESHOLD) withEvent({
+				Action: action,
+				ActionType: PageVisitAction,
+				EmpId: empId || "UNKNOWN",
+				EmpRole: empRole || "UNKNOWN",
+				Duration: duration
+			});
+		};
+	}, [
+		action,
+		empId,
+		empRole
+	]);
+};
+//#endregion
+export { ActionType, PageVisitAction, connectSocket, disconnectSocket, projectName, socket, useGlobalClickTracker, usePageTimeTracker, withEvent };

package/dist/src/event-bus.d.ts

@@ -0,0 +1,31 @@
+export declare const ActionType: {
+    readonly Button: "Button";
+    readonly Menu: "Menu";
+    readonly Login: "Login";
+    readonly Link: "Link";
+};
+export declare const PageVisitAction = "Page Visit";
+/**
+ * Represents the structure of event data that can be emitted
+ * Can be either a click event (Button/Menu) with a count
+ * or a page visit event with duration in seconds
+ */
+export type EventData = {
+    ActionType: keyof typeof ActionType;
+    Action: string;
+    EmpId: string;
+    EmpRole: string;
+    Count: number;
+} | {
+    ActionType: typeof PageVisitAction;
+    Action: string;
+    EmpId: string;
+    EmpRole: string;
+    Duration: number;
+};
+/**
+ * Emits an event with the provided event data and optionally executes a callback function
+ * @param eventData The event data to be emitted
+ * @param callback Optional callback function to be executed before emitting the event
+ */
+export declare function withEvent(eventData: EventData, callback?: () => void): void;

package/dist/src/hooks.d.ts

@@ -0,0 +1,17 @@
+import { EventData } from './event-bus';
+/**
+ * Hook to track global click events and emit them to the server
+ * Listens for click events on the document and automatically captures button/link clicks
+ * @param empId Optional employee ID for tracking
+ * @param roleId Optional role ID for tracking
+ */
+declare const useGlobalClickTracker: (empId?: string, roleId?: string) => void;
+/**
+ * Hook to track accurate active page visit duration
+ * Uses Page Visibility API to only count time when the tab is actively visible
+ * @param action The action name for the page visit
+ * @param empId Optional employee ID for tracking
+ * @param empRole Optional employee role for tracking
+ */
+declare const usePageTimeTracker: (action: EventData["Action"], empId?: EventData["EmpId"], empRole?: EventData["EmpRole"]) => void;
+export { useGlobalClickTracker, usePageTimeTracker };

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './event-bus';
+export * from './hooks';
+export * from './socket';

package/dist/src/socket.d.ts

@@ -0,0 +1,12 @@
+import { io } from 'socket.io-client';
+export declare let socket: ReturnType<typeof io> | undefined;
+export declare let projectName: string | number;
+/**
+ * Connects to the socket server and emits a connection event
+ * @param socketUrl The URL of the socket server to connect to
+ */
+export declare const connectSocket: (socketUrl: string, project: string) => void;
+/**
+ * Disconnects the socket server and cleans up the instance
+ */
+export declare const disconnectSocket: () => void;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "nova-hooks",
+  "version": "2.0.0",
+  "description": "Nova hooks package",
+  "keywords": [
+    "nova",
+    "hooks"
+  ],
+  "homepage": "https://github.com/mjjabarullah/nova-hooks#readme",
+  "bugs": {
+    "url": "https://github.com/mjjabarullah/nova-hooks/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjjabarullah/nova-hooks.git"
+  },
+  "license": "ISC",
+  "author": "Mohamed Jabarullah",
+  "type": "module",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepare": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.6.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^27.0.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.12",
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/readme.md

@@ -0,0 +1,141 @@
+# nova-hooks
+
+A highly-optimized, **zero-configuration** event tracking utility for capturing user interactions and page visits in React applications. Built with a custom, lightweight `EventBus` and `socket.io-client`.
+
+---
+
+## ✨ Features
+
+- **Zero-Config Tracking:** Automatically captures clicks on buttons, links, and interactive elements without needing manual attributes!
+- **True Page Dwell Time:** Uses the native Page Visibility API to calculate the *actual* active time spent on a page (pauses when the user switches tabs).
+- **Network Optimized:** Employs a built-in 1-second debouncing and click-batching mechanism to minimize network overhead.
+- **Ultra-Lightweight:** Zero dependencies (other than `socket.io-client`). Fully framework-agnostic core logic.
+- **Auto-Enriched Context:** Automatically attaches `PageUrl`, `PageTitle`, `Project`, and `CreatedDate` to every single event payload.
+- **SSR Safe:** Fully compatible with Next.js and Remix.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Install
+
+```bash
+yarn add nova-hooks@https://github.com/mjjabarullah/nova-hooks.git#v2.0.0
+```
+
+```bash
+npm i nova-hooks@https://github.com/mjjabarullah/nova-hooks.git#v2.0.0
+```
+
+### 2. Initialization
+
+> [!IMPORTANT]
+> Ensure the socket connection is established at the root of your application using the `connectSocket` method.
+
+```tsx
+import { connectSocket } from "nova-hooks";
+import { useEffect } from "react";
+
+const App = () => {
+  useEffect(() => {
+    connectSocket(import.meta.env.VITE_APP_SOCKET, "WolfPack");
+  }, []);
+
+  // app code...
+};
+```
+
+---
+
+## 🛠️ Usage Examples
+
+### 1. Zero-Config Global Click Tracking
+Place `useGlobalClickTracker` in your authenticated layout. It will automatically listen to the DOM and seamlessly track clicks on any `<button>`, `<a>`, or `cursor: pointer` element!
+
+```tsx
+import { useGlobalClickTracker } from "nova-hooks";
+
+const ProtectedLayout = ({ children }) => {
+  const { user } = useAuth();
+  
+  // Magic happens here! Tracks all UI clicks across the entire app.
+  useGlobalClickTracker(user?.empId, user?.roleId);
+
+  return <>{children}</>;
+};
+```
+*Note: It will intelligently extract labels from `innerText`, `title`, `aria-label`, or auto-generate a fallback CSS Path!*
+
+### 2. Explicit Tracking (Optional Overrides)
+If you want to override the auto-detected name for a specific button, just attach the `data-nova-*` attributes:
+
+```tsx
+<button
+  data-nova-track-id="Custom Task Action"
+  data-nova-track-type={ActionType.Button}
+>
+  Track Me Specifically
+</button>
+```
+
+### 3. Accurate Page Dwell Time
+Track exactly how long a user actively stares at a specific page/component. The timer pauses if they switch tabs or minimize the browser!
+
+```tsx
+import { usePageTimeTracker } from "nova-hooks";
+
+export const Dashboard = () => {
+  const { user } = useAuth();
+
+  // Tracks active dwell time and emits it automatically when the user leaves the page
+  usePageTimeTracker("Home Dashboard", user?.empId, user?.roleId);
+
+  return <div>Welcome to the Dashboard</div>;
+};
+```
+
+### 4. Manual / Imperative Tracking
+If you need to track events programmatically (like inside an API success callback), use the `withEvent` method:
+
+```tsx
+import { withEvent, ActionType } from "nova-hooks";
+
+const doLogin = () => {
+  api.login()
+    .then(() => {
+      withEvent({
+        Action: "Login Success",
+        ActionType: ActionType.Login,
+        EmpId: "EMP-123",
+        EmpRole: "Admin",
+        Count: 1,
+      });
+    });
+};
+```
+
+---
+
+## 📦 Exports & Types
+
+| Name                    | Type                                                         | Description                                                                                            |
+| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `ActionType`            | `object`                                                     | Predefined enum-like values: `"Button"`, `"Menu"`, `"Login"`, `"Link"`                                 |
+| `PageVisitAction`       | `string`                                                     | Constant string `"Page Visit"` used for tracking page visits                                           |
+| `connectSocket`         | `(socketUrl: string, project: string) => void`               | Connects to the socket server and sets the project name.                                               |
+| `disconnectSocket`      | `() => void`                                                 | Disconnects and cleans up the active socket connection.                                                |
+| `withEvent`             | `(eventData: EventData, callback?: Function) => void`        | Emits a structured event optionally after running a callback.                                          |
+| `useGlobalClickTracker` | `(empId?: string, roleId?: string) => void`                  | React hook to automatically track global click events.                                                 |
+| `usePageTimeTracker`    | `(action: string; empId?: string; empRole?: string) => void` | React hook to track active time spent on a page via the Visibility API.                                |
+
+### EventData Structure
+All events are automatically enriched with `Project`, `PageUrl`, `PageTitle`, and an ISO `CreatedDate`.
+
+| Property     | Type                                                              | Description                                                         |
+| ------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `ActionType` | `keyof typeof ActionType` \| `typeof PageVisitAction`             | Type of the action.                                                 |
+| `Action`     | `string`                                                          | Specific action performed (extracted from DOM or manually set).     |
+| `EmpId`      | `string`                                                          | Unique identifier of the employee.                                  |
+| `EmpRole`    | `string`                                                          | Role of the employee performing the action.                         |
+| `Count`      | `number` _(only when `ActionType` is from `ActionType`)_          | Number of rapid occurrences of the action (batched).                |
+| `Duration`   | `number` _(seconds, only when `ActionType` is `PageVisitAction`)_ | Duration of the *active* visit in seconds.                          |