{"_id":"@auralogiclabs/client-uuid-gen","name":"@auralogiclabs/client-uuid-gen","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@auralogiclabs/client-uuid-gen","version":"1.0.0","description":"A robust device UUID generator with enhanced fingerprinting parameters.","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","publishConfig":{"access":"public"},"scripts":{"build":"tsup src/index.ts --format cjs,esm,iife --dts --clean --global-name ClientUUIDGen","test":"vitest run","lint":"eslint src/**","format":"prettier --write src/**"},"keywords":["uuid","device-fingerprint","unique-id","client-id","browser-fingerprint"],"author":{"name":"Amartya Mondal","email":"amartya@auralogiclabs.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/auralogiclabs/client-uuid-gen.git"},"bugs":{"url":"https://github.com/auralogiclabs/client-uuid-gen/issues"},"homepage":"https://github.com/auralogiclabs/client-uuid-gen#readme","dependencies":{"crypto-js":"^4.2.0"},"devDependencies":{"@eslint/js":"^9.0.0","@types/crypto-js":"^4.2.0","@types/node":"^20.0.0","eslint":"^9.0.0","eslint-config-prettier":"^9.0.0","happy-dom":"^20.0.11","prettier":"^3.0.0","tsup":"^8.0.0","typescript":"^5.0.0","typescript-eslint":"^8.0.0","vitest":"^1.0.0"},"gitHead":"b0473f7807744b9bc337b3d0fec741f3bdf870a5","_id":"@auralogiclabs/client-uuid-gen@1.0.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.1","dist":{"integrity":"sha512-W2MMBATfaxebmsRG5XD8LFfX0m90kMX5fehbg1iz+a4K+ffLxLVAx0qarDmkXbrR72m+wa2OMx2XYno6EtKOSg==","shasum":"5bd3e38d9939c611751c9aa45fc5cf9fdc40527f","tarball":"https://registry.npmjs.org/@auralogiclabs/client-uuid-gen/-/client-uuid-gen-1.0.0.tgz","fileCount":8,"unpackedSize":275431,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDzFyaeF5Ev5CbzSBpbifUYtOGrcgh7R7TpD43wENWT4AIgLxFFYYyhV6YM736TnrBFD+L1nM6ypuyeao2Vi4m5r70="}]},"_npmUser":{"name":"atm1504","email":"hello@auralogiclabs.com"},"directories":{},"maintainers":[{"name":"atm1504","email":"hello@auralogiclabs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/client-uuid-gen_1.0.0_1766654587539_0.02555709969388853"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-25T09:23:07.417Z","1.0.0":"2025-12-25T09:23:07.696Z","modified":"2025-12-25T09:23:08.065Z"},"maintainers":[{"name":"atm1504","email":"hello@auralogiclabs.com"}],"description":"A robust device UUID generator with enhanced fingerprinting parameters.","homepage":"https://github.com/auralogiclabs/client-uuid-gen#readme","keywords":["uuid","device-fingerprint","unique-id","client-id","browser-fingerprint"],"repository":{"type":"git","url":"git+https://github.com/auralogiclabs/client-uuid-gen.git"},"author":{"name":"Amartya Mondal","email":"amartya@auralogiclabs.com"},"bugs":{"url":"https://github.com/auralogiclabs/client-uuid-gen/issues"},"license":"MIT","readme":"# @auralogiclabs/client-uuid-gen\n\n[![npm version](https://img.shields.io/npm/v/@auralogiclabs/client-uuid-gen.svg?style=flat-square)](https://www.npmjs.com/package/@auralogiclabs/client-uuid-gen)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![minzipped size](https://img.shields.io/bundlephobia/minzip/@auralogiclabs/client-uuid-gen?style=flat-square)](https://bundlephobia.com/package/@auralogiclabs/client-uuid-gen)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)\n\nA robust, browser-based device UUID generator that creates unique fingerprints using multiple browser attributes including Canvas, WebGL, AudioContext, and LocalStorage estimates.\n\n## Key Benefits\n\n| Feature                | Description                                                                                        |\n| :--------------------- | :------------------------------------------------------------------------------------------------- |\n| 🛡️ **Privacy-First**   | Generates a hash, never stores raw PII. Cookies are NOT used.                                      |\n| 🕵️‍♂️ **Incognito-Proof** | **Stable Mode** (default) ensures the same Device ID is generated in Normal and Incognito windows. |\n| 🚀 **High Entropy**    | Combines 8+ hardware/software signals (Canvas, WebGL, Audio, Storage, etc.) for high uniqueness.   |\n| 📦 **Universal**       | Works everywhere: Browser (ESM/IIFE), Node.js, and Bundlers (Webpack/Vite).                        |\n| 💎 **TypeScript**      | Written in TypeScript with full type definitions included.                                         |\n\n## Browser Support\n\n| Browser           | Version | Status       |\n| :---------------- | :------ | :----------- |\n| **Chrome**        | 60+     | ✅ Supported |\n| **Firefox**       | 60+     | ✅ Supported |\n| **Safari**        | 12+     | ✅ Supported |\n| **Edge**          | 79+     | ✅ Supported |\n| **iOS / Android** | Modern  | ✅ Supported |\n\n## Installation\n\n```bash\nnpm install @auralogiclabs/client-uuid-gen\n```\n\n## Usage\n\n### Basic Usage (ES Modules / TypeScript)\n\n```typescript\nimport { getFingerprint } from '@auralogiclabs/client-uuid-gen';\n\nasync function identifyDevice() {\n  try {\n    // Default: MD5 hash, Stable Mode enabled\n    const deviceId = await getFingerprint();\n    console.log('Device UUID (Stable):', deviceId);\n\n    // Option: SHA-256 hash (64 chars)\n    const deviceIdStrong = await getFingerprint({ algo: 'sha256' });\n    console.log('Device UUID (SHA-256):', deviceIdStrong);\n  } catch (error) {\n    console.error('Failed to generate fingerprint:', error);\n  }\n}\n```\n\n### Stable Fingerprinting (Incognito Mode)\n\nBrowsers often intentionally alter fingerprinting data in Incognito/Private windows to prevent tracking (e.g., hiding real screen height, adding noise to audio signals).\n\n**This library handles this automatically.**\n\n#### Configuration: `enableStableFingerprinting`\n\n- `true` (Default): Treats Normal and Incognito windows as the **SAME** user.\n  - _How?_ It neutralizes unstable components (e.g., ignores screen height, skips audio fingerprinting) to ensure the hash remains consistent.\n- `false`: Treats Normal and Incognito windows as **DIFFERENT** users.\n  - _How?_ It uses all available data, which means the noise injected by the browser will cause the hash to change.\n\n```typescript\n// Treat Incognito as a unique/different user (Strict Mode)\nconst strictId = await getFingerprint({\n  enableStableFingerprinting: false,\n});\n\n// Treat Incognito as the same user (Stable Mode - Default)\nconst stableId = await getFingerprint({\n  enableStableFingerprinting: true,\n});\n```\n\n### Advanced Usage (Class Access)\n\nYou can access the `EnhancedDeviceFingerprint` class directly to inspect individual components.\n\n```typescript\nimport { EnhancedDeviceFingerprint } from '@auralogiclabs/client-uuid-gen';\n\nasync function fullAnalysis() {\n  const fingerprinter = new EnhancedDeviceFingerprint();\n\n  // 1. Generate the hash\n  const uuid = await fingerprinter.get();\n  console.log('UUID:', uuid);\n\n  // 2. Access internal components (populated after get/generateFingerprint)\n  console.log('Detailed Components:', fingerprinter.components);\n  /* Output example:\n  {\n    basic: { userAgent: \"...\", screenResolution: \"1920x(Authored)\", ... },\n    canvas: \"data:image/png;base64,...\",\n    webgl: \"...\",\n    audio: \"audio-omitted-for-stability\",\n    storage: \"...\"\n  }\n  */\n}\n```\n\n### Browser Usage (Script Tag)\n\nFor direct use in the browser without a bundler, use the global build.\n\n```html\n<!-- Load crypto-js dependency (standard hashing support) -->\n<script src=\"https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js\"></script>\n\n<!-- Load the library -->\n<script src=\"https://unpkg.com/@auralogiclabs/client-uuid-gen/dist/index.global.js\"></script>\n\n<script>\n  const { getFingerprint } = window.ClientUUIDGen;\n\n  getFingerprint().then((uuid) => {\n    console.log('Generated UUID:', uuid);\n  });\n</script>\n```\n\n## How It Works\n\nThis library generates a \"fingerprint\" by collecting stable characteristics of the user's browser environment:\n\n1.  **Basic Info:** User Agent, OS, Browser, Device Type, Language, Screen Resolution, Timezone.\n2.  **Canvas Fingerprinting:** Renders a hidden canvas with specific text and colors. Differences in graphics hardware produce unique data URLs.\n3.  **WebGL Fingerprinting:** Queries WebGL vendor and renderer information.\n4.  **Audio Fingerprinting:** Uses an OfflineAudioContext to render a specific oscillator tone. Differences in audio hardware/drivers produce unique signal processing results.\n5.  **Storage Fingerprinting:** Estimates available storage quota to bucket users (e.g., \"fast device with lots of space\" vs \"budget device\").\n\nAll these components are combined into a JSON string and hashed to produce a short, unique identifier.\n\n## Privacy Note\n\nFingerprinting allows identification without cookies. Ensure you comply with **GDPR**, **CCPA**, and other privacy regulations.\n\n- Inform users that device characteristics are being used for identification/fraud prevention.\n- Obtain necessary consents if required in your jurisdiction.\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n\n### Setup\n\n```bash\ngit clone https://github.com/auralogiclabs/client-uuid-gen.git\ncd client-uuid-gen\nnpm install\n```\n\n### Build\n\nGenerates `dist/` folder with CJS, ESM, and IIFE formats.\n\n```bash\nnpm run build\n```\n\n### Test\n\nRuns unit tests using Vitest.\n\n```bash\nnpm test\n```\n\n### Lint & Format\n\n```bash\nnpm run lint\nnpm run format\n```\n\n### Running Example\n\nTo run the example page locally:\n\n> **Important:** Run the server from the **project root**, not inside the `examples/` folder. This ensures the browser can correct access the `dist/` folder.\n\n```bash\n# 1. Build the library first\nnpm run build\n\n# 2. Serve from project root\nnpx serve .\n\n# 3. Visit http://localhost:3000/examples/\n```\n\n|                            Example Output                            |\n| :------------------------------------------------------------------: |\n| <img src=\"assets/example.png\" width=\"800\" alt=\"Example Interface\" /> |\n\n## License\n\nMIT © [Auralogic Labs](https://auralogiclabs.com)\n","readmeFilename":"README.md","_rev":"1-d6356bab441c94d5e35e13ac45b878cd"}