Revamped the Usermaven SDK codebase

[seeratawan01]

User description

This PR represents a significant refactoring and enhancement of the Usermaven JavaScript SDK. Key changes include:

1. Improved Architecture:

   • Modular structure with clear separation of concerns
   • Enhanced type safety with TypeScript
   • Better code organization for easier maintenance and extensibility

2. Enhanced Features:

   • Robust event tracking with a retry mechanism
   • Improved user and group identification
   • Advanced form tracking capabilities
   • Cross-domain linking support
   • Rage click detection

3. Performance Optimizations:

   • Event batching for reduced network requests
   • Debounced scroll depth tracking
   • Efficient data persistence strategies

4. Privacy and Security:

   • Configurable data sanitization
   • Support for various cookie and IP policies
   • Sensitive data redaction in form submissions

5. Developer Experience:

   • Comprehensive configuration options
   • Improved error handling and logging
   • Better support for both client-side and server-side usage

6. Testing and Quality:

   • Expanded unit test coverage
   • Integration with modern testing tools (Vitest)

7. Build System:

   • Migration to Vite for faster builds and better developer experience
   • Support for multiple output formats (UMD, ES, CJS)
   • Bundle size reduction

---

PR Type

Enhancement, Tests

---

Description

• Implemented UsermavenClient class with enhanced features including event tracking, user identification, and group identification.
• Added AutoCapture class for automatic event capturing and FormTracking class for tracking form submissions.
• Introduced RetryQueue class for event retry logic and RageClick class for detecting rage clicks.
• Implemented various transport classes (XhrTransport, HttpsTransport, FetchTransport, BeaconTransport) for different transport mechanisms.
• Added utility functions for common operations, including cookie management, event handling, and data sanitization.
• Provided unit tests for core functionalities and server-side operations.
• Updated React and Next.js hooks for integration with Usermaven SDK.
• Added example scripts and components for testing and demonstration purposes.

---

Changes walkthrough 📝

	Relevant files
Enhancement	20 files client.ts Implement core client functionality with enhanced features packages/javascript-sdk/src/core/client.ts Introduced UsermavenClient class with enhanced features. Implemented event tracking, user identification, and group identification. Added support for cross-domain linking and rage click detection. Improved persistence and transport mechanisms. +580/-0  autocapture.ts Add AutoCapture class for automatic event tracking              packages/javascript-sdk/src/tracking/autocapture.ts Added AutoCapture class for automatic event capturing. Implemented DOM event handlers for capturing user interactions. Introduced sanitization methods for text and URLs. Enabled configuration for capturing specific elements. +311/-0  form-tracking.ts Implement FormTracking class for form submission tracking packages/javascript-sdk/src/tracking/form-tracking.ts Implemented FormTracking class for tracking form submissions. Added support for tracking field changes. Enhanced form attribute capturing and sanitization. Introduced singleton pattern for FormTracking instance. +67/-38  index.ts Export UsermavenClient and setup initialization functions packages/javascript-sdk/src/index.ts Exported UsermavenClient and related types. Provided initialization functions for client setup. Enabled script-based configuration for client initialization. +166/-0  scroll-depth.ts Refactor ScrollDepth class for improved scroll tracking    packages/javascript-sdk/src/extensions/scroll-depth.ts Refactored ScrollDepth class for tracking scroll depth. Implemented debounced scroll event handling. Enhanced milestone tracking for scroll events. Improved method for calculating scroll depth. +64/-101 common.ts Add utility functions for common operations                            packages/javascript-sdk/src/utils/common.ts Added utility functions for common operations. Implemented deep copy and event registration functions. Enhanced string manipulation and object handling utilities. Introduced window availability check. +51/-9    useUsermaven.ts Update useUsermaven hook for React integration                      packages/react/src/useUsermaven.ts Updated useUsermaven hook for React integration. Enhanced client method callbacks with useCallback. Improved error handling for missing context. Refactored hook to return client methods. +63/-54  cookie.ts Implement CookieManager class for cookie operations            packages/javascript-sdk/src/utils/cookie.ts Implemented CookieManager class for cookie operations. Added methods for setting, getting, and deleting cookies. Enhanced domain extraction and cookie domain handling. Improved cookie security with secure and HttpOnly flags. +104/-0  queue.ts Implement RetryQueue class for event retry logic                  packages/javascript-sdk/src/utils/queue.ts Implemented RetryQueue class for event retry logic. Added support for offline queue persistence. Enhanced batch processing and retry mechanisms. Improved network status handling for queue processing. +123/-0  autocapture-utils.ts Add utility functions for autocapture operations                  packages/javascript-sdk/src/utils/autocapture-utils.ts Added utility functions for autocapture operations. Implemented element and event capturing logic. Enhanced sensitive data detection and exclusion. Improved DOM element property extraction. +29/-19  usePageView.ts Implement usePageView hook for page view tracking                packages/react/src/usePageView.ts Implemented usePageView hook for page view tracking. Added URL change detection and tracking logic. Enhanced callback support for additional tracking options. Improved integration with useUsermaven hook. +72/-18  usePageView.ts Implement usePageView hook for Next.js page view tracking packages/nextjs/src/usePageView.ts Implemented usePageView hook for Next.js page view tracking. Added URL change detection and tracking logic. Enhanced callback support for additional tracking options. Improved integration with useUsermaven hook. +66/-21  useUsermaven.ts Update useUsermaven hook for Next.js integration                  packages/nextjs/src/useUsermaven.ts Updated useUsermaven hook for Next.js integration. Enhanced client method callbacks with useCallback. Improved error handling for missing context. Refactored hook to return client methods. +33/-12  rage-click.ts Implement RageClick class for detecting rage clicks            packages/javascript-sdk/src/extensions/rage-click.ts Implemented RageClick class for detecting rage clicks. Added logic for tracking rapid clicks in a specific area. Enhanced event capturing and threshold configuration. Improved integration with UsermavenClient. +74/-0    helpers.ts Add helper functions for common tasks                                        packages/javascript-sdk/src/utils/helpers.ts Added helper functions for common tasks. Implemented ID generation and email validation. Enhanced debounce function for event handling. Improved query string parsing and UTM parameter extraction. +69/-0    xhr.ts Implement XhrTransport class for XHR-based transport          packages/javascript-sdk/src/transport/xhr.ts Implemented XhrTransport class for XHR-based transport. Added support for custom headers and URL construction. Enhanced error handling and response processing. Improved integration with UsermavenClient. +71/-0    https.ts Implement HttpsTransport class for HTTPS transport              packages/javascript-sdk/src/transport/https.ts Implemented HttpsTransport class for HTTPS transport. Added support for custom headers and URL construction. Enhanced error handling and response processing. Improved integration with UsermavenClient. +71/-0    config.ts Define configuration interface for UsermavenClient              packages/javascript-sdk/src/core/config.ts Defined configuration interface for UsermavenClient. Added default configuration values. Enhanced support for various policies and options. Improved integration with client initialization. +67/-0    fetch.ts Implement FetchTransport class for Fetch API transport      packages/javascript-sdk/src/transport/fetch.ts Implemented FetchTransport class for Fetch API transport. Added support for custom headers and URL construction. Enhanced error handling and response processing. Improved integration with UsermavenClient. +64/-0    beacon.ts Implement BeaconTransport class for Beacon API transport  packages/javascript-sdk/src/transport/beacon.ts Implemented BeaconTransport class for Beacon API transport. Added support for URL construction. Enhanced event queuing and error handling. Improved integration with UsermavenClient. +42/-0
Tests	3 files event-tracking.test.ts Add unit tests for event tracking in UsermavenClient          packages/javascript-sdk/test/unit/core/event-tracking.test.ts Added unit tests for UsermavenClient event tracking. Tested various event types including pageview, scroll, and autocapture. Verified handling of UTM parameters and screen resolutions. Ensured correct user and group identification. +238/-0  client.test.ts Add unit tests for UsermavenClient methods                              packages/javascript-sdk/test/unit/core/client.test.ts Added unit tests for UsermavenClient methods. Tested user identification, event tracking, and group identification. Verified error handling for invalid inputs. Ensured correct state reset functionality. +165/-0  server-side-client.test.ts Add unit tests for server-side UsermavenClient                      packages/javascript-sdk/test/unit/core/server-side-client.test.ts Added unit tests for server-side UsermavenClient. Verified initialization without browser-specific features. Tested event tracking and user identification on server-side. Ensured correct handling of complex payloads. +106/-0
Documentation	2 files page.tsx Add example Next.js page component                                              examples/next-app/src/app/page.tsx Added example Next.js page component. Implemented basic layout and styling. Included links and images for demonstration. Provided instructions for getting started. +94/-0    test.ts Add example script for testing Usermaven SDK                          packages/javascript-sdk/examples/test.ts Added example script for testing Usermaven SDK. Implemented event tracking and user identification tests. Enhanced logging for SDK loading and event sending. Provided DOM event listeners for testing. +30/-0
Additional files (token-limit)	53 files pageviews.ts ...                                                                                                            packages/javascript-sdk/src/tracking/pageviews.ts ... +57/-0    vite.config.ts ...                                                                                                            packages/javascript-sdk/vite.config.ts ... +52/-0    local-storage.ts ...                                                                                                            packages/javascript-sdk/src/persistence/local-storage.ts ... +58/-0    App.tsx ...                                                                                                            examples/react-app/src/App.tsx ... +44/-0    types.ts ...                                                                                                            packages/javascript-sdk/src/core/types.ts ... +48/-0    UsermavenProvider.tsx ...                                                                                                            packages/react/src/UsermavenProvider.tsx ... +14/-10  logger.ts ...                                                                                                            packages/javascript-sdk/src/utils/logger.ts ... +38/-0    layout.tsx ...                                                                                                            examples/next-app/src/app/layout.tsx ... +37/-0    main.tsx ...                                                                                                            examples/react-app/src/main.tsx ... +28/-0    LayoutWrapper.tsx ...                                                                                                            examples/next-app/src/component/client/LayoutWrapper.tsx ... +24/-0    setup.ts ...                                                                                                            packages/javascript-sdk/test/setup.ts ... +27/-0    UsermavenProvider.tsx ...                                                                                                            packages/nextjs/src/UsermavenProvider.tsx ... +3/-3      vitest.config.ts ...                                                                                                            packages/javascript-sdk/vitest.config.ts ... +20/-0    middlewareEnv.ts ...                                                                                                            packages/nextjs/src/middlewareEnv.ts ... +2/-2      memory.ts ...                                                                                                            packages/javascript-sdk/src/persistence/memory.ts ... +25/-0    vitest.d.ts ...                                                                                                            packages/javascript-sdk/test/vitest.d.ts ... +20/-0    vite.config.ts ...                                                                                                            examples/react-app/vite.config.ts ... +7/-0      global.d.ts ...                                                                                                            packages/javascript-sdk/src/global.d.ts ... +7/-0      transport.ts ...                                                                                                            packages/javascript-sdk/src/transport/transport.ts ... +3/-0      vite-env.d.ts ...                                                                                                            examples/react-app/src/vite-env.d.ts ... +1/-0      form-tracking.html ...                                                                                                            packages/javascript-sdk/examples/form-tracking.html ... +110/-0  index.html ...                                                                                                            packages/javascript-sdk/examples/index.html ... +45/-0    index.html ...                                                                                                            examples/react-app/index.html ... +13/-0    mergeFiles.js ...                                                                                                            mergeFiles.js ... +156/-0  mockServer.js ...                                                                                                            packages/javascript-sdk/server/mockServer.js ... +119/-0  copyContents.js ...                                                                                                            scripts/copyContents.js ... +93/-0    eslint.config.js ...                                                                                                            examples/react-app/eslint.config.js ... +28/-0    page.module.css ...                                                                                                            examples/next-app/src/app/page.module.css ... +165/-0  index.css ...                                                                                                            examples/react-app/src/index.css ... +63/-8    App.css ...                                                                                                            examples/react-app/src/App.css ... +42/-0    globals.css ...                                                                                                            examples/next-app/src/app/globals.css ... +42/-0    pnpm-lock.yaml ...                                                                                                            pnpm-lock.yaml ... +5173/-1 README.md ...                                                                                                            packages/javascript-sdk/README.md ... +149/-36 README.md ...                                                                                                            examples/react-app/README.md ... +50/-70  package.json ...                                                                                                            packages/javascript-sdk/package.json ... +44/-46  README.md ...                                                                                                            README.md ... +163/-3  package.json ...                                                                                                            examples/react-app/package.json ... +23/-34  tsconfig.json ...                                                                                                            packages/javascript-sdk/tsconfig.json ... +35/-12  README.md ...                                                                                                            examples/next-app/README.md ... +36/-0    package.json ...                                                                                                            package.json ... +12/-11  README.md ...                                                                                                            packages/nextjs/README.md ... +4/-4      tsconfig.json ...                                                                                                            examples/next-app/tsconfig.json ... +26/-0    tsconfig.app.json ...                                                                                                            examples/react-app/tsconfig.app.json ... +24/-0    package.json ...                                                                                                            examples/next-app/package.json ... +23/-0    tsconfig.node.json ...                                                                                                            examples/react-app/tsconfig.node.json ... +22/-0    README.md ...                                                                                                            packages/react/README.md ... +2/-2      .eslintrc.json ...                                                                                                            packages/javascript-sdk/.eslintrc.json ... +19/-0    package.json ...                                                                                                            packages/react/package.json ... +1/-1      package.json ...                                                                                                            packages/nextjs/package.json ... +1/-1      .prettierrc ...                                                                                                            packages/javascript-sdk/.prettierrc ... +7/-0      tsconfig.json ...                                                                                                            examples/react-app/tsconfig.json ... +7/-0      next.config.mjs ...                                                                                                            examples/next-app/next.config.mjs ... +4/-0      pnpm-workspace.yaml ...                                                                                                            pnpm-workspace.yaml ... +3/-0

---

💡 PR-Agent usage: Comment /help "your question" on any pull request to receive relevant information

[github-actions[bot]]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🏅 Score: 72

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Possible Bug The `mergeConfig` method might cause a stack overflow if there are circular references in the configuration objects. This method uses recursion without handling circular references, which can lead to infinite recursion. Performance Issue The `trackInternal` method is called within a loop in the `RetryQueue` class, which could lead to performance issues if the queue is large. This method sends network requests and should be optimized for batch processing. Code Smell The `id` method in `UsermavenClient` class has a boolean parameter `doNotSendEvent` which leads to multiple responsibilities within the method. Consider splitting this method into two separate methods to handle identification and event sending distinctly.

Code feedback:

---

relevant file	packages/javascript-sdk/src/core/client.ts
suggestion	Consider adding error handling for JSON parsing in the `mergeConfig` method to catch and handle potential exceptions that can arise from malformed input. [important]
relevant line	const cleanConfig = JSON.parse(JSON.stringify(config));

---

relevant file	packages/javascript-sdk/src/core/client.ts
suggestion	To improve the performance of the `trackInternal` method, consider implementing a batching mechanism that aggregates events and sends them in bulk rather than one at a time. This can reduce the number of network requests and improve the efficiency of data transmission. [important]
relevant line	this.trackInternal(typeName, payload, directSend);

---

relevant file	packages/javascript-sdk/src/core/client.ts
suggestion	Refactor the `id` method by creating a separate method for sending the identification event. This separation of concerns can make the code cleaner and easier to maintain. [important]
relevant line	if (!doNotSendEvent) {

---

[github-actions[bot]]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Score
Possible bug	Ensure all used functions are properly imported or defined to avoid runtime errors ___ **Ensure that the isElementNode function is imported or defined in the current or a globally accessible scope, as it is used to check if el is an element node.** [packages/javascript-sdk/src/utils/autocapture-utils.ts [171-172]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-3421105f040b57611a61997529e3c66ca2a0ee572e2ff04008bd6bea93aa71a3R171-R172) ```diff +import { isElementNode } from 'path/to/module'; +... if (!el || !isElementNode(el)) { return false; } ``` Suggestion importance[1-10]: 9 Why: The suggestion addresses a potential bug by ensuring that the `isElementNode` function is imported or defined, which is crucial for preventing runtime errors when the function is called.	9
	Enhance robustness by ensuring that objects and properties exist before accessing them ___ **Consider checking for the existence of window and document before accessing window.document.createElement to prevent potential reference errors in non-browser environments.** [packages/javascript-sdk/src/utils/common.ts [316-318]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-43df5b60f1b780217be1dab54c8a87a626c72a97751bab7dcced7f4693fb56a9R316-R318) ```diff return typeof window !== 'undefined' && - window.document !== undefined && - window.document.createElement !== undefined; + typeof window.document !== 'undefined' && + typeof window.document.createElement === 'function'; ``` Suggestion importance[1-10]: 8 Why: The suggestion improves the robustness of the code by ensuring that `window` and `document` are defined before accessing their properties, which is important for preventing reference errors in non-browser environments.	8
	Add checks for required HTML attributes to prevent runtime errors ___ **Consider checking for the presence of required attributes like data-key and data-tracking-host in the HTMLScriptElement before using them to prevent runtime errors.** [packages/javascript-sdk/src/index.ts [27-29]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-02046ed2ea7c73d60e8f714d301b8e29ef6141c1b53d9f8504cd73f187a55050R27-R29) ```diff -key: script.getAttribute('data-key') || undefined, -trackingHost: script.getAttribute('data-tracking-host') || 'https://events.usermaven.com', +key: script.getAttribute('data-key') || throw new Error('data-key attribute is required'), +trackingHost: script.getAttribute('data-tracking-host') || throw new Error('data-tracking-host attribute is required'), ``` Suggestion importance[1-10]: 3 Why: The suggestion to check for required HTML attributes before using them is reasonable, but the proposed syntax is incorrect. The use of `throw` in a logical expression is not valid, reducing the effectiveness of the suggestion.	3
	Validate the API key in the configuration to ensure it is not null or empty ___ **Ensure that the key attribute in the config object is validated for non-null and non-empty values to prevent runtime errors when the API key is required for operations.** [packages/javascript-sdk/src/index.ts [9-12]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-02046ed2ea7c73d60e8f714d301b8e29ef6141c1b53d9f8504cd73f187a55050R9-R12) ```diff const cleanConfig = JSON.parse(JSON.stringify(config)); +if (!cleanConfig.key) { + throw new Error('API key cannot be null or empty.'); +} const camelCaseConfig = convertKeysToCamelCase(cleanConfig); const mergedConfig: Config = { ...defaultConfig, ...camelCaseConfig } as Config; ``` Suggestion importance[1-10]: 2 Why: The suggestion to validate the API key for null or empty values is redundant because the existing code already throws an error if the key is not present. The improvement is minimal and doesn't significantly enhance the existing validation logic.	2
Enhancement	Implement error handling for JSON parsing to manage exceptions from malformed configurations ___ **Add error handling for JSON parsing to catch and manage potential exceptions from malformed input configurations.** [packages/javascript-sdk/src/index.ts [10]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-02046ed2ea7c73d60e8f714d301b8e29ef6141c1b53d9f8504cd73f187a55050R10-R10) ```diff -const cleanConfig = JSON.parse(JSON.stringify(config)); +let cleanConfig; +try { + cleanConfig = JSON.parse(JSON.stringify(config)); +} catch (error) { + throw new Error('Failed to parse configuration: ' + error.message); +} ``` Suggestion importance[1-10]: 7 Why: Adding error handling for JSON parsing is a valuable enhancement that can prevent runtime errors due to malformed configurations. This improves the robustness of the code by providing clear error messages when parsing fails.	7
	Use native JavaScript methods for better performance and standard practices ___ **Use Array.isArray(obj) directly instead of a custom function to check if obj is an array, as it is more standard and performant.** [packages/javascript-sdk/src/utils/common.ts [19-20]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-43df5b60f1b780217be1dab54c8a87a626c72a97751bab7dcced7f4693fb56a9R19-R20) ```diff function (obj: any): obj is any[] { - return toString.call(obj) === '[object Array]' + return Array.isArray(obj); } ``` Suggestion importance[1-10]: 7 Why: The suggestion to use `Array.isArray(obj)` instead of a custom function aligns with standard practices and improves performance, making it a beneficial enhancement.	7
	Replace JSON stringify/parse with a deep cloning function to handle complex object types more reliably ___ **Use a more robust method for deep cloning the config object to avoid potential issues with JSON stringify/parse, such as losing methods or handling of special types like Date or undefined.** [packages/javascript-sdk/src/index.ts [10]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-02046ed2ea7c73d60e8f714d301b8e29ef6141c1b53d9f8504cd73f187a55050R10-R10) ```diff -const cleanConfig = JSON.parse(JSON.stringify(config)); +const cleanConfig = deepClone(config); ``` Suggestion importance[1-10]: 6 Why: Using a more robust deep cloning method can prevent issues related to JSON stringify/parse limitations, such as handling special types like Date or undefined. This suggestion improves the reliability of the code when dealing with complex objects.	6
	Improve the alt attribute for the Vite logo to enhance accessibility ___ **Consider using a more descriptive alt attribute for the Vite logo to enhance accessibility.** [examples/react-app/src/App.tsx [18-19]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-cd61ef28fd5f5a4c0f4337eada1961a24ff1187484b001c36e07575aeef0e234R18-R19) ```diff - + ``` Suggestion importance[1-10]: 5 Why: The suggestion to use a more descriptive `alt` attribute for the Vite logo is valid and enhances accessibility. It provides a clearer description of the image, which can be beneficial for users relying on screen readers.	5
Possible issue	Verify and test font file paths to ensure proper loading and rendering ___ **Ensure that the font files are correctly loaded by verifying the paths and testing across different browsers to avoid issues with font rendering.** [examples/next-app/src/app/layout.tsx [7-16]](https://github.com/usermaven/usermaven-js/pull/99/files#diff-11f17983113855f424000e9b0d58f859395eb340ff1ab567a144e3a3b17b7c6cR7-R16) ```diff +const geistSans = localFont({ + src: "./fonts/GeistVF.woff", + variable: "--font-geist-sans", + weight: "100 900", +}); +const geistMono = localFont({ + src: "./fonts/GeistMonoVF.woff", + variable: "--font-geist-mono", + weight: "100 900", +}); - ``` Suggestion importance[1-10]: 3 Why: The suggestion to verify and test font file paths is valid but not actionable as it only advises on testing without providing specific code changes. It is a general recommendation rather than a direct code improvement.	3