Merge pull request #1 from moumen-soliman/1.1.0

Support Server v1.1.0

Author: moumen-soliman

README.md

@@ -12,15 +12,24 @@
 +-----------------+-----------------+-----------------+
 ```
 
-A lightweight JavaScript/TypeScript package for generating hashed fingerprints based on device data. Includes options for customizable device information, IP address integration, and cookie management.
+A lightweight JavaScript/TypeScript package that generates unique hashed fingerprints for devices in both browser and server environments. The library allows customization of what data is included in the fingerprint, with options for saving the hash in cookies, passing headers for server-side use, and providing the user's IP directly.
+
+[**NPM**](https://www.npmjs.com/package/hashed-device-fingerprint-js)
 
 ## Features
-- Device Data Fingerprinting: Collects user agent, screen resolution, platform, and more.
-- SHA-256 Hashing: Uses [js-sha256](https://www.npmjs.com/package/js-sha256) for secure hashing.
-- IP Address Integration: Fetch IP automatically, pass it manually, or disable it entirely.
-- Cookie Management: Optionally save hashed fingerprints in cookies.
-- Fully Configurable: Enable or disable specific device data fields as needed.
-- TypeScript Support: Fully typed for better integration with modern frameworks like Next.js.
+- Generate a unique fingerprint hash based on:
+  - User Agent
+  - Browser/System Language
+  - Screen Resolution (Browser-only)
+  - Platform (e.g., `Win32` or `Linux`)
+  - Hardware Concurrency (Browser-only)
+  - IP Address (with options to pass it manually or fetch automatically)
+- Support for browser and server environments:
+  - **Browser**: Uses `navigator` and `screen` properties.
+  - **Server**: Relies on HTTP headers and server-side properties.
+- Save the hashed fingerprint in a cookie (browser only) with a customizable expiration time.
+- Fully customizable: enable or disable specific data points.
+- Compatible with both `require` (CommonJS) and `import` (ES Modules).
 
 ## Installation
 Install the package using npm:
@@ -30,9 +39,9 @@ npm install hashed-device-fingerprint-js
 ```
 
 ## Usage
-### Basic Usage
+### Default Behavior (Browser)
 
-Generate a hashed fingerprint with all options enabled (default behavior):
+By default, all options are enabled. The library generates a fingerprint hash using all available device data and automatically fetches the user's IP address.
 
 ```typescript
 import { generateHashedFingerprint } from 'hashed-device-fingerprint-js';
@@ -42,6 +51,29 @@ generateHashedFingerprint()
     .catch(error => console.error('Error:', error));
 ```
 
+### Server-Side Usage
+
+In a Server environment, pass HTTP headers to generate a fingerprint. Use the environment option to specify the server-side environment.
+
+```typescript
+const { generateHashedFingerprint } = require('hashed-device-fingerprint-js');
+// import { generateHashedFingerprint } from 'hashed-device-fingerprint-js';
+
+// Example HTTP headers
+const headers = {
+    'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)',
+    'accept-language': 'en-US,en;q=0.9',
+    'x-forwarded-for': '203.0.113.45',
+};
+
+generateHashedFingerprint({
+    environment: 'server',
+    headers,
+})
+    .then(hash => console.log('Fingerprint Hash:', hash))
+    .catch(error => console.error('Error:', error));
+```
+
 ## Custom Options
 Customize the behavior by passing an options object:
 
@@ -61,54 +93,6 @@ generateHashedFingerprint({
     .catch(error => console.error('Error:', error));
 ```
 
-## Options
-
-- `saveToCookie`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Save the generated hash in a cookie.
-
-- `cookieExpiryDays`
-  - Type: `number`
-  - Default: `7`
-  - Description: Number of days before the cookie expires.
-
-- `useUserAgent`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Include the browser's user agent string in the fingerprint.
-
-- `useLanguage`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Include the browser's language setting in the fingerprint.
-
-- `useScreenResolution`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Include the screen's resolution and color depth in the fingerprint.
-
-- `usePlatform`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Include platform information (e.g., "Win32", "MacIntel").
-
-- `useConcurrency`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Include the number of logical processors.
-
-- `useIP`
-  - Type: `boolean`
-  - Default: `true`
-  - Description: Fetch and include the user's IP address.
-
-- `userIP`
-  - Type: `string`
-  - Default: `null`
-  - Description: Provide an IP address manually (overrides API fetch).
-
-
 ## IP Address Handling
 The IP address is included in the fingerprint based on these rules:
 
@@ -140,6 +124,39 @@ generateHashedFingerprint({ userIP: '203.0.113.45' })
     .catch(error => console.error('Error:', error));
 ```
 
+### Server API
+```javascript
+const { generateHashedFingerprint } = require('hashed-device-fingerprint-js');
+
+// Basic route
+app.get('/hash', async (req, res) => {
+    // Define headers for fingerprint generation
+    const headers = {
+        'user-agent': req.headers['user-agent'] || 'Unknown',
+        'accept-language': req.headers['accept-language'] || 'Unknown',
+        'x-forwarded-for': req.headers['x-forwarded-for'] || req.connection.remoteAddress || 'Unknown',
+    };
+
+    try {
+        // Generate the fingerprint hash
+        const hash = await generateHashedFingerprint({
+            environment: 'server',
+            headers,
+        });
+
+        // Log the hash
+        console.log('Generated Hash:', hash);
+
+        // Send the hash as the response
+        res.send({ hash });
+    } catch (error) {
+        // Handle errors
+        console.error('Error generating fingerprint:', error);
+        res.status(500).send({ error: 'Failed to generate fingerprint' });
+    }
+});
+```
+
 ## TypeScript Support
 The package includes TypeScript type definitions for all options and methods. Here’s a quick example:
 
@@ -172,8 +189,74 @@ generateHashedFingerprint()
     });
 ```
 
+## Options
+
+- `saveToCookie`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Save the generated hash in a cookie.
+
+- `cookieExpiryDays`
+  - Type: `number`
+  - Default: `7`
+  - Description: Number of days before the cookie expires.
+
+- `useUserAgent`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Include the browser's user agent string in the fingerprint.
+
+- `useLanguage`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Include the browser's language setting in the fingerprint.
+
+- `useScreenResolution`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Include the screen's resolution and color depth in the fingerprint.
+
+- `usePlatform`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Include platform information (e.g., "Win32", "MacIntel").
+
+- `useConcurrency`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Include the number of logical processors.
+
+- `useIP`
+  - Type: `boolean`
+  - Default: `true`
+  - Description: Fetch and include the user's IP address.
+
+- `userIP`
+  - Type: `string`
+  - Default: `null`
+  - Description: Provide an IP address manually (overrides API fetch).
+
+- `headers`
+  - Type: `Record<string, string[]>`
+  - Default: `{}`
+  - Description: HTTP headers for server-side fingerprinting.
+
+- `environment`
+  - Type: `'browser' | 'server'`
+  - Default: `Auto-detected`
+  - Description: Specify the environment explicitly (e.g., `'browser'` or `'server'`).
+
 ## License
 This package is licensed under the [MIT License](https://opensource.org/license/mit/).
 
 ## Contributing
-Contributions are welcome! Feel free to submit issues or pull requests.
+- Fork the repository.
+- Create a new branch: git checkout -b feature-name.
+- Commit your changes: git commit -m 'Add feature'.
+- Push to the branch: git push origin feature-name.
+- Submit a pull request.
+
+## Support
+If you encounter any issues or have questions, feel free to open an issue on [**Repo Issues**](https://github.com/moumen-soliman/hashed-device-fingerprint-js/issues).
+
+Happy coding! 🚀

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hashed-device-fingerprint-js",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "homepage": "https://moumen-soliman.github.io/hashed-device-fingerprint-docs/",
   "description": "A lightweight library for generating hashed fingerprints based on selected device data.",
   "main": "dist/index.min.js",
@@ -33,6 +33,7 @@
     "js-sha256": "^0.11.0"
   },
   "devDependencies": {
+    "@types/node": "^22.9.0",
     "esbuild": "^0.24.0",
     "typescript": "^5.6.3"
   },