nova-hooks 2.0.3 → 2.0.8

package/dist/index.cjs.js

@@ -2,11 +2,23 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let socket_io_client = require("socket.io-client");
 let react = require("react");
 //#region src/socket.ts
+/** 
+* Singleton instance of the Socket.IO client.
+* Kept global to ensure only one connection exists per application lifecycle.
+*/
 var socket;
+/**
+* The global identifier for the current application/project.
+* Attached to all emitted events to segregate data in the backend dashboard.
+*/
 var projectName;
 /**
-* Connects to the socket server and emits a connection event
-* @param socketUrl The URL of the socket server to connect to
+* Initializes and establishes a real-time connection to the Nova socket server.
+* This should typically be called once at the root of the application (e.g., App.tsx).
+* 
+* @param socketUrl The absolute URL of the socket server to connect to
+* @param project The unique identifier or name of the consuming application
+* @throws {Error} If the socketUrl or project name is missing or empty
 */
 var connectSocket = (socketUrl, project) => {
 	if (!socketUrl || socketUrl.trim() === "") throw new Error("Socket URL is required to connect.");
@@ -22,7 +34,8 @@ var connectSocket = (socketUrl, project) => {
 	});
 };
 /**
-* Disconnects the socket server and cleans up the instance
+* Gracefully disconnects the active socket connection and completely 
+* destroys the local instance, freeing up resources.
 */
 var disconnectSocket = () => {
 	if (socket) {
@@ -32,27 +45,53 @@ var disconnectSocket = () => {
 };
 //#endregion
 //#region src/event-bus.ts
+/**
+* A lightweight custom event emitter implementation.
+* Created to avoid bundling the bulky Node.js 'events' package.
+*/
 var SimpleEventEmitter = class {
 	listeners = {};
+	/**
+	* Registers a listener callback for a specific event.
+	* @param event The name of the event to listen for
+	* @param callback The function to execute when the event is emitted
+	*/
 	on(event, callback) {
 		if (!this.listeners[event]) this.listeners[event] = [];
 		this.listeners[event].push(callback);
 	}
+	/**
+	* Emits an event, triggering all registered listeners synchronously.
+	* @param event The name of the event to emit
+	* @param data The payload to pass to the listener callbacks
+	*/
 	emit(event, data) {
 		if (this.listeners[event]) this.listeners[event].forEach((cb) => cb(data));
 	}
 };
+/**
+* Predefined set of UI element types that can be tracked.
+* Used to categorize standard user click interactions.
+*/
 var ActionType = {
 	Button: "Button",
 	Menu: "Menu",
 	Login: "Login",
 	Link: "Link"
 };
+/**
+* Constant identifier representing a page dwell time tracking event.
+*/
 var PageVisitAction = "Page Visit";
+/** Internal event identifier used for routing payloads within the EventBus */
 var APP_EVENT = "APP_EVENT";
+/** The singleton instance of the event bus */
 var eventBus = new SimpleEventEmitter();
+/** The socket event name used when streaming data to the backend */
 var NOVA_USER_ACTIVITY_EVENT = "nova-user-activity";
+/** Map storing aggregated, debounced click events keyed by their unique signature */
 var pendingClicks = /* @__PURE__ */ new Map();
+/** Reference to the active batching debounce timer */
 var batchTimer = null;
 /**
 * Event listener for APP_EVENT that processes and enriches event data
@@ -104,6 +143,12 @@ function withEvent(eventData, callback) {
 }
 //#endregion
 //#region src/hooks.ts
+/**
+* Helper utility to generate a unique CSS selector path for an HTML element.
+* Used as a fallback identifier when a clicked element lacks semantic text or explicit tracking IDs.
+* @param el The HTML element to generate a path for
+* @returns A string representing the CSS selector path (e.g., 'div.container > button#submit')
+*/
 var getCssPath = (el) => {
 	const path = [];
 	let current = el;
@@ -120,10 +165,13 @@ var getCssPath = (el) => {
 	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
+* React hook to track global click events and automatically emit them to the server.
+* Attaches a single event listener to the document (event delegation) to capture clicks.
+* It intelligently identifies interactive elements (buttons, links, pointer cursors) and
+* extracts their labels or generates a CSS path fallback if no label is found.
+* 
+* @param empId Optional employee ID for tracking identity
+* @param roleId Optional role ID for tracking authorization/role
 */
 var useGlobalClickTracker = (empId, roleId) => {
 	(0, react.useEffect)(() => {
@@ -165,13 +213,19 @@ var useGlobalClickTracker = (empId, roleId) => {
 		};
 	}, [empId, roleId]);
 };
+/** 
+* Minimum active dwell time (in seconds) required before a page visit event is considered valid and emitted.
+*/
 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
+* React hook to track accurate active page visit duration.
+* Utilizes the native Page Visibility API to pause the timer when the user switches tabs
+* or minimizes the browser, ensuring only actual active dwell time is recorded.
+* Emits the payload automatically when the component unmounts.
+* 
+* @param action The specific action name or page identifier for the visit
+* @param empId Optional employee ID for tracking identity
+* @param empRole Optional employee role for tracking authorization/role
 */
 var usePageTimeTracker = (action, empId, empRole) => {
 	const activeTimeRef = (0, react.useRef)(0);

package/dist/index.es.js

@@ -1,11 +1,23 @@
 import { io } from "socket.io-client";
 import { useEffect, useRef } from "react";
 //#region src/socket.ts
+/** 
+* Singleton instance of the Socket.IO client.
+* Kept global to ensure only one connection exists per application lifecycle.
+*/
 var socket;
+/**
+* The global identifier for the current application/project.
+* Attached to all emitted events to segregate data in the backend dashboard.
+*/
 var projectName;
 /**
-* Connects to the socket server and emits a connection event
-* @param socketUrl The URL of the socket server to connect to
+* Initializes and establishes a real-time connection to the Nova socket server.
+* This should typically be called once at the root of the application (e.g., App.tsx).
+* 
+* @param socketUrl The absolute URL of the socket server to connect to
+* @param project The unique identifier or name of the consuming application
+* @throws {Error} If the socketUrl or project name is missing or empty
 */
 var connectSocket = (socketUrl, project) => {
 	if (!socketUrl || socketUrl.trim() === "") throw new Error("Socket URL is required to connect.");
@@ -21,7 +33,8 @@ var connectSocket = (socketUrl, project) => {
 	});
 };
 /**
-* Disconnects the socket server and cleans up the instance
+* Gracefully disconnects the active socket connection and completely 
+* destroys the local instance, freeing up resources.
 */
 var disconnectSocket = () => {
 	if (socket) {
@@ -31,27 +44,53 @@ var disconnectSocket = () => {
 };
 //#endregion
 //#region src/event-bus.ts
+/**
+* A lightweight custom event emitter implementation.
+* Created to avoid bundling the bulky Node.js 'events' package.
+*/
 var SimpleEventEmitter = class {
 	listeners = {};
+	/**
+	* Registers a listener callback for a specific event.
+	* @param event The name of the event to listen for
+	* @param callback The function to execute when the event is emitted
+	*/
 	on(event, callback) {
 		if (!this.listeners[event]) this.listeners[event] = [];
 		this.listeners[event].push(callback);
 	}
+	/**
+	* Emits an event, triggering all registered listeners synchronously.
+	* @param event The name of the event to emit
+	* @param data The payload to pass to the listener callbacks
+	*/
 	emit(event, data) {
 		if (this.listeners[event]) this.listeners[event].forEach((cb) => cb(data));
 	}
 };
+/**
+* Predefined set of UI element types that can be tracked.
+* Used to categorize standard user click interactions.
+*/
 var ActionType = {
 	Button: "Button",
 	Menu: "Menu",
 	Login: "Login",
 	Link: "Link"
 };
+/**
+* Constant identifier representing a page dwell time tracking event.
+*/
 var PageVisitAction = "Page Visit";
+/** Internal event identifier used for routing payloads within the EventBus */
 var APP_EVENT = "APP_EVENT";
+/** The singleton instance of the event bus */
 var eventBus = new SimpleEventEmitter();
+/** The socket event name used when streaming data to the backend */
 var NOVA_USER_ACTIVITY_EVENT = "nova-user-activity";
+/** Map storing aggregated, debounced click events keyed by their unique signature */
 var pendingClicks = /* @__PURE__ */ new Map();
+/** Reference to the active batching debounce timer */
 var batchTimer = null;
 /**
 * Event listener for APP_EVENT that processes and enriches event data
@@ -103,6 +142,12 @@ function withEvent(eventData, callback) {
 }
 //#endregion
 //#region src/hooks.ts
+/**
+* Helper utility to generate a unique CSS selector path for an HTML element.
+* Used as a fallback identifier when a clicked element lacks semantic text or explicit tracking IDs.
+* @param el The HTML element to generate a path for
+* @returns A string representing the CSS selector path (e.g., 'div.container > button#submit')
+*/
 var getCssPath = (el) => {
 	const path = [];
 	let current = el;
@@ -119,10 +164,13 @@ var getCssPath = (el) => {
 	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
+* React hook to track global click events and automatically emit them to the server.
+* Attaches a single event listener to the document (event delegation) to capture clicks.
+* It intelligently identifies interactive elements (buttons, links, pointer cursors) and
+* extracts their labels or generates a CSS path fallback if no label is found.
+* 
+* @param empId Optional employee ID for tracking identity
+* @param roleId Optional role ID for tracking authorization/role
 */
 var useGlobalClickTracker = (empId, roleId) => {
 	useEffect(() => {
@@ -164,13 +212,19 @@ var useGlobalClickTracker = (empId, roleId) => {
 		};
 	}, [empId, roleId]);
 };
+/** 
+* Minimum active dwell time (in seconds) required before a page visit event is considered valid and emitted.
+*/
 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
+* React hook to track accurate active page visit duration.
+* Utilizes the native Page Visibility API to pause the timer when the user switches tabs
+* or minimizes the browser, ensuring only actual active dwell time is recorded.
+* Emits the payload automatically when the component unmounts.
+* 
+* @param action The specific action name or page identifier for the visit
+* @param empId Optional employee ID for tracking identity
+* @param empRole Optional employee role for tracking authorization/role
 */
 var usePageTimeTracker = (action, empId, empRole) => {
 	const activeTimeRef = useRef(0);

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

@@ -1,9 +1,16 @@
+/**
+ * Predefined set of UI element types that can be tracked.
+ * Used to categorize standard user click interactions.
+ */
 export declare const ActionType: {
     readonly Button: "Button";
     readonly Menu: "Menu";
     readonly Login: "Login";
     readonly Link: "Link";
 };
+/**
+ * Constant identifier representing a page dwell time tracking event.
+ */
 export declare const PageVisitAction = "Page Visit";
 /**
  * Represents the structure of event data that can be emitted

package/dist/src/hooks.d.ts

@@ -1,17 +1,23 @@
 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
+ * React hook to track global click events and automatically emit them to the server.
+ * Attaches a single event listener to the document (event delegation) to capture clicks.
+ * It intelligently identifies interactive elements (buttons, links, pointer cursors) and
+ * extracts their labels or generates a CSS path fallback if no label is found.
+ *
+ * @param empId Optional employee ID for tracking identity
+ * @param roleId Optional role ID for tracking authorization/role
  */
 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
+ * React hook to track accurate active page visit duration.
+ * Utilizes the native Page Visibility API to pause the timer when the user switches tabs
+ * or minimizes the browser, ensuring only actual active dwell time is recorded.
+ * Emits the payload automatically when the component unmounts.
+ *
+ * @param action The specific action name or page identifier for the visit
+ * @param empId Optional employee ID for tracking identity
+ * @param empRole Optional employee role for tracking authorization/role
  */
 declare const usePageTimeTracker: (action: EventData["Action"], empId?: EventData["EmpId"], empRole?: EventData["EmpRole"]) => void;
 export { useGlobalClickTracker, usePageTimeTracker };

package/dist/src/socket.d.ts

@@ -1,12 +1,25 @@
 import { io } from 'socket.io-client';
+/**
+ * Singleton instance of the Socket.IO client.
+ * Kept global to ensure only one connection exists per application lifecycle.
+ */
 export declare let socket: ReturnType<typeof io> | undefined;
+/**
+ * The global identifier for the current application/project.
+ * Attached to all emitted events to segregate data in the backend dashboard.
+ */
 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
+ * Initializes and establishes a real-time connection to the Nova socket server.
+ * This should typically be called once at the root of the application (e.g., App.tsx).
+ *
+ * @param socketUrl The absolute URL of the socket server to connect to
+ * @param project The unique identifier or name of the consuming application
+ * @throws {Error} If the socketUrl or project name is missing or empty
  */
 export declare const connectSocket: (socketUrl: string, project: string) => void;
 /**
- * Disconnects the socket server and cleans up the instance
+ * Gracefully disconnects the active socket connection and completely
+ * destroys the local instance, freeing up resources.
  */
 export declare const disconnectSocket: () => void;

package/package.json

@@ -1,52 +1,52 @@
-{
-  "name": "nova-hooks",
-  "version": "2.0.3",
-  "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": "MIT",
-  "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"
-  }
-}
+{
+  "name": "nova-hooks",
+  "version": "2.0.8",
+  "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": "MIT",
+  "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

@@ -1,146 +1,146 @@
-# 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
-```
-
-```bash
-npm i nova-hooks
-```
-
-### 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.                      |
+# 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
+```
+
+```bash
+npm i nova-hooks
+```
+
+### 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.                      |