nova-hooks 2.0.7 → 2.0.9

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,6 +1,6 @@
 {
   "name": "nova-hooks",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "Nova hooks package",
   "keywords": [
     "nova",

package/readme.md

@@ -1,5 +1,10 @@
 # nova-hooks
 
+[![npm version](https://img.shields.io/npm/v/nova-hooks.svg?style=flat-square)](https://www.npmjs.com/package/nova-hooks)
+[![npm downloads](https://img.shields.io/npm/dm/nova-hooks.svg?style=flat-square)](https://www.npmjs.com/package/nova-hooks)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Socket Badge](https://badge.socket.dev/npm/package/nova-hooks/2.0.7)](https://badge.socket.dev/npm/package/nova-hooks/2.0.7)
+
 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`.
 
 ---