aki-info-detect 2.0.0 → 2.0.2

package/README.md

@@ -6,6 +6,198 @@ A lightweight JavaScript library for detecting device, browser, hardware, and ne
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/aki-info-detect)](https://bundlephobia.com/package/aki-info-detect)
 
+## Introduction
+
+**aki-info-detect** is a modern, lightweight JavaScript library designed to provide comprehensive device, browser, and system information detection for web applications. Built with performance and developer experience in mind, it leverages modern browser APIs including the Client Hints API for accurate hardware detection while maintaining a small footprint (~3.8 kB gzipped).
+
+Whether you need to customize user experiences based on device capabilities, gather analytics data, or implement platform-specific features, aki-info-detect provides a unified, easy-to-use API that works seamlessly across all modern browsers.
+
+### Why aki-info-detect?
+
+- **🎯 Comprehensive Detection**: Get detailed information about browser, OS, CPU, GPU, RAM, network, battery, and more from a single library
+- **⚡ Performance-First**: Minimal bundle size with tree-shakeable exports—import only what you need
+- **🔮 Future-Proof**: Built on modern Web APIs with graceful fallbacks for older browsers
+- **💪 Apple Silicon Ready**: Advanced detection for Apple M-series chips (M1, M2, M3, M4, and beyond)
+- **🔒 Privacy-Conscious**: Implements caching for network requests to minimize external API calls
+- **📦 Zero Dependencies**: No external runtime dependencies—just pure, optimized JavaScript
+- **🎨 Developer-Friendly**: TypeScript declarations included, intuitive API design, comprehensive documentation
+
+## Use Cases
+
+### 1. **Adaptive User Interfaces**
+Dynamically adjust your UI based on device capabilities and screen properties:
+```javascript
+const info = await akiInfoDetect();
+if (info.isMobile) {
+  // Load mobile-optimized components
+  loadMobileUI();
+} else if (info.RAM < 4) {
+  // Use lightweight version for low-memory devices
+  enableLowMemoryMode();
+}
+```
+
+### 2. **Analytics & User Insights**
+Gather detailed technical data to understand your user base:
+```javascript
+const info = await akiInfoDetect();
+analytics.track('page_view', {
+  browser: info.browser,
+  os: info.os.string,
+  device: info.isMobile ? 'mobile' : 'desktop',
+  gpu: info.GPU,
+  country: await info.getCountry()
+});
+```
+
+### 3. **Feature Detection & Progressive Enhancement**
+Enable or disable features based on browser capabilities:
+```javascript
+const info = await akiInfoDetect();
+if (info.browser.includes('Chrome') && parseInt(info.browser.split(' ')[1]) >= 90) {
+  // Enable features requiring Chrome 90+
+  enableAdvancedFeatures();
+}
+```
+
+### 4. **Platform-Specific Optimization**
+Optimize content delivery based on hardware capabilities:
+```javascript
+const info = await akiInfoDetect();
+if (info.CPU === 'Apple Silicon') {
+  // Load optimized assets for Apple Silicon
+  loadWebPImages();
+} else if (info.GPU.includes('NVIDIA')) {
+  // Enable GPU-accelerated features
+  enableHardwareAcceleration();
+}
+```
+
+### 5. **Targeted User Support**
+Provide context-aware help and troubleshooting:
+```javascript
+const info = await akiInfoDetect();
+if (info.browser.includes('Safari') && info.os.name === 'ios') {
+  showMessage('For best experience on iOS Safari, please enable...');
+}
+```
+
+### 6. **Network-Aware Loading**
+Adapt content loading strategies based on connection quality:
+```javascript
+const info = await akiInfoDetect();
+const conn = info.getConnection();
+if (conn.type === '4g' && conn.downlink > 5) {
+  // High-speed connection: load high-quality assets
+  loadHDContent();
+} else {
+  // Optimize for slower connections
+  loadCompressedContent();
+}
+```
+
+## Comparison with Similar Libraries
+
+| Feature | aki-info-detect | Platform.js | UA-Parser.js | Detect.js |
+|---------|----------------|-------------|--------------|-----------|
+| **Bundle Size (gzipped)** | ~3.8 kB | ~2.5 kB | ~9 kB | Varies |
+| **Client Hints API** | ✅ Full Support | ❌ No | ❌ No | ❌ No |
+| **GPU Detection** | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| **Apple Silicon Detection** | ✅ Yes (M1-MX) | ❌ No | ❌ No | ❌ No |
+| **Network Info (IP/ISP)** | ✅ Yes (cached) | ❌ No | ❌ No | ❌ No |
+| **Battery Status** | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| **Geolocation** | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| **Tree-shakeable** | ✅ Yes | ⚠️ Partial | ⚠️ Partial | ⚠️ Partial |
+| **TypeScript** | ✅ Full declarations | ⚠️ Community types | ✅ Yes | ❌ No |
+| **Active Maintenance** | ✅ Yes | ⚠️ Sporadic | ✅ Yes | ❌ Archived |
+| **Modern Build System** | ✅ Vite | ❌ Legacy | ✅ Webpack | ❌ Legacy |
+
+### Key Differentiators
+
+**vs. Platform.js**
+- aki-info-detect is a modern evolution with Client Hints API support for more accurate detection
+- Adds hardware detection (GPU, RAM) and network capabilities not available in Platform.js
+- Built with modern tooling (Vite) for better tree-shaking and optimization
+
+**vs. UA-Parser.js**
+- Lighter bundle size while providing more comprehensive information
+- Includes hardware and network detection beyond just user agent parsing
+- Native async/await support with modern API design
+
+**vs. Detect.js**
+- Active maintenance (Detect.js is archived)
+- Smaller, more focused API surface with better performance
+- Modern Web API integration for enhanced detection capabilities
+
+## Frequently Asked Questions (FAQ)
+
+### General Questions
+
+**Q: What browsers does aki-info-detect support?**  
+A: All modern browsers with ES2020+ support: Chrome/Edge 89+, Firefox 88+, Safari 14+, Opera 76+. Client Hints features work best in Chromium-based browsers.
+
+**Q: Does it work in Node.js or server-side environments?**  
+A: No, aki-info-detect is specifically designed for browser environments. It relies on browser APIs like `navigator`, `screen`, and Web APIs that are not available in Node.js.
+
+**Q: How accurate is the detection?**  
+A: Very accurate for modern browsers that support Client Hints API. For browsers without Client Hints, it falls back to user agent parsing which is still reliable but less detailed. GPU and CPU detection is most accurate in Chromium-based browsers.
+
+**Q: Is user agent string spoofing a concern?**  
+A: While user agents can be spoofed, Client Hints API provides more reliable detection. For critical functionality, always combine with feature detection rather than relying solely on browser/platform detection.
+
+### Privacy & Security
+
+**Q: Does aki-info-detect collect or transmit user data?**  
+A: No. The library only detects information locally in the browser. The optional network info feature (`getNetworkInfo()`) makes a request to a public IP API, but this is only triggered when you explicitly call that method.
+
+**Q: What about user privacy?**  
+A: aki-info-detect is privacy-conscious. Network requests are cached for 1 hour to minimize external API calls, and all detection happens client-side. No data is sent to our servers.
+
+**Q: Is it GDPR compliant?**  
+A: Detection of browser/device information is generally considered functional data necessary for website operation. However, always review your local regulations and privacy policies, especially when using geolocation or storing detected data.
+
+### Technical Questions
+
+**Q: Why do I need to configure server headers?**  
+A: The Client Hints API requires the server to explicitly request detailed information via `Accept-CH` headers. Without these headers, browsers will only provide basic user agent data. This is a browser security feature designed to enhance user privacy.
+
+**Q: Can I use it with React, Vue, or other frameworks?**  
+A: Absolutely! aki-info-detect is framework-agnostic. See the React Hook and Vue Composable examples in the documentation for integration patterns.
+
+**Q: How do I reduce bundle size further?**  
+A: Use tree-shakeable imports to include only the functions you need:
+```javascript
+import { detectBrowser, detectOS } from 'aki-info-detect';
+```
+
+**Q: Does it support TypeScript?**  
+A: Yes, full TypeScript declarations are included in the package.
+
+**Q: How often is the network information cached?**  
+A: Network info (IP, ISP, country) is cached for 1 hour by default. You can force a refresh by passing `true` to `getNetworkInfo(true)`.
+
+### Troubleshooting
+
+**Q: Why am I getting generic hardware info?**  
+A: Make sure your server is configured to send the required `Accept-CH` headers. Without these headers, detailed Client Hints data won't be available.
+
+**Q: Why is GPU detection returning "Unknown"?**  
+A: GPU detection works best in Chromium browsers with Client Hints. Safari and Firefox have limited support. Also, some browsers may restrict this information for privacy reasons.
+
+**Q: The library says "Unknown" for many fields. What's wrong?**  
+A: Check browser console for errors, ensure you're using a supported browser version, and verify that your server is sending proper Client Hints headers (see Server Configuration section).
+
+### Usage & Development
+
+**Q: Can I contribute to the project?**  
+A: Yes! Contributions are welcome. Please check the GitHub repository for contribution guidelines.
+
+**Q: How do I report a bug or request a feature?**  
+A: Open an issue on the [GitHub repository](https://github.com/lacvietanh/akiInfoDetect.js/issues) with details about the bug or feature request.
+
+**Q: Is there a demo I can try?**  
+A: Yes! Visit the [live demo](https://akiinfodetect-js.pages.dev/) to see the library in action.
+
 ## Features
 
 - 🌐 **Browser Detection** — Name, version, rendering engine

package/dist/aki-info-detect.js

@@ -1,8 +1,8 @@
 /*!
- * aki-info-detect v2.0.0
+ * aki-info-detect v2.0.2
  * (c) 2025 lacvietanh
  * Released under the MIT License
- * https://github.com/lacvietanh/akiInfoDetect.js
+ * https://akiinfodetect-js.pages.dev/
  */
 function parseUserAgent(ua = navigator.userAgent) {
   let os = null;

package/dist/aki-info-detect.umd.cjs

@@ -1,9 +1,9 @@
 !function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).akiInfoDetect={})}(this,function(e){"use strict";
 /*!
- * aki-info-detect v2.0.0
+ * aki-info-detect v2.0.2
  * (c) 2025 lacvietanh
  * Released under the MIT License
- * https://github.com/lacvietanh/akiInfoDetect.js
+ * https://akiinfodetect-js.pages.dev/
  */function t(e=navigator.userAgent){let t=null,n="",r="",i="",o="";const a=[{test:/Edg(?:e)?\//,name:"Edge",regex:/Edg(?:e)?\/([\d.]+)/},{test:/OPR\/|Opera\//,name:"Opera",regex:/(?:OPR|Opera)\/([\d.]+)/},{test:/Firefox\//,name:"Firefox",regex:/Firefox\/([\d.]+)/,exclude:/Seamonkey/},{test:/Chrome\//,name:"Chrome",regex:/Chrome\/([\d.]+)/,exclude:/Edge|Edg|OPR|Opera/},{test:/Safari\//,name:"Safari",regex:/Version\/([\d.]+)/,exclude:/Chrome|Edge|Edg|OPR|Opera/},{test:/MSIE|Trident/,name:"IE",regex:/(?:MSIE |rv:)([\d.]+)/}];for(const{test:c,name:u,regex:l,exclude:d}of a)if(c.test(e)&&(!d||!d.test(e))){n=u;const t=e.match(l);r=(null==t?void 0:t[1])||"";break}const s=[{test:/Windows/,parse:()=>{const t=e.match(/Windows NT ([\d.]+)/),n=(null==t?void 0:t[1])||"",r={"10.0":"10",6.3:"8.1",6.2:"8",6.1:"7","6.0":"Vista",5.1:"XP"}[n]||n;return{family:`Windows ${r}`,version:r,architecture:/WOW64|Win64|x64/.test(e)?64:32}}},{test:/Mac OS X/,parse:()=>{var t;const n=e.match(/Mac OS X ([\d_.]+)/),r=(null==(t=null==n?void 0:n[1])?void 0:t.replace(/_/g,"."))||"";return{family:`macOS ${r}`,version:r,architecture:64}}},{test:/Android/,parse:()=>{const t=e.match(/Android ([\d.]+)/),n=(null==t?void 0:t[1])||"";return{family:`Android ${n}`,version:n,architecture:64}}},{test:/iPhone|iPad|iPod/,parse:()=>{var t;const n=e.match(/OS ([\d_]+)/),r=(null==(t=null==n?void 0:n[1])?void 0:t.replace(/_/g,"."))||"";return{family:`iOS ${r}`,version:r,architecture:64}}},{test:/Linux/,parse:()=>({family:"Linux",version:"",architecture:/x86_64|amd64/.test(e)?64:32})}];for(const{test:c,parse:u}of s)if(c.test(e)){t=u();break}if(/iPhone/.test(e))i="iPhone",o="Apple";else if(/iPad/.test(e))i="iPad",o="Apple";else if(/Android/.test(e)){const t=e.match(/Android[^;]+;\s*([^;)]+)/);if(t){i=t[1].trim();const e=i.match(/^(Samsung|LG|Motorola|HTC|Huawei|Xiaomi|OnePlus|Google|Sony|OPPO|Vivo|Realme)/i);o=(null==e?void 0:e[1])||""}}return{name:n,version:r,product:i,manufacturer:o,os:t,layout:/AppleWebKit/.test(e)?"WebKit":/Gecko\//.test(e)?"Gecko":/Trident/.test(e)?"Trident":""}}async function n(){var e;if(!(null==(e=navigator.userAgentData)?void 0:e.getHighEntropyValues))return{};try{return await navigator.userAgentData.getHighEntropyValues(["platform","platformVersion","architecture","model","mobile","bitness","brands","fullVersionList"])}catch{return{}}}function r(){try{const e=document.createElement("canvas"),t=e.getContext("webgl")||e.getContext("experimental-webgl");if(!t)return"No WebGL support";const n=t.getExtension("WEBGL_debug_renderer_info");return n?t.getParameter(n.UNMASKED_RENDERER_WEBGL)||"Unknown GPU":"GPU info restricted"}catch{return"GPU detection failed"}}const i={IP:"",ISP:"",country:"",lastUpdated:0,TTL:36e5};async function o(e,t=2500){const n=new AbortController,r=setTimeout(()=>n.abort(),t);try{const t=await fetch(e,{signal:n.signal});return clearTimeout(r),t.ok?await t.json():null}catch{return clearTimeout(r),null}}async function a(e=!1){if(!e&&i.IP&&Date.now()-i.lastUpdated<i.TTL)return{IP:i.IP,ISP:i.ISP,country:i.country};const t=[{url:"https://ipinfo.io/json",parse:e=>({IP:e.ip,ISP:e.org||"",country:e.country||""})},{url:"https://ipwhois.app/json/",parse:e=>({IP:e.ip,ISP:e.isp||"",country:e.country_code||""})},{url:"https://api.ipify.org?format=json",parse:e=>({IP:e.ip,ISP:"",country:""})}];for(const{url:n,parse:r}of t){const e=await o(n);if(e){const t=r(e);if(t.IP)return i.IP=t.IP,i.ISP=t.ISP||i.ISP,i.country=t.country||i.country,i.lastUpdated=Date.now(),t}}return{IP:i.IP,ISP:i.ISP,country:i.country}}async function s(e=!1){return(await a(e)).IP}async function c(e=!1){return(await a(e)).ISP}async function u(e=!1){return(await a(e)).country}function l(){const e=navigator.connection||navigator.mozConnection||navigator.webkitConnection;return e?{type:e.type||"unknown",effectiveType:e.effectiveType||"unknown",downlink:e.downlink||0,rtt:e.rtt||0,saveData:e.saveData||!1}:null}function d(e={timeout:1e4,enableHighAccuracy:!1}){return new Promise(t=>{navigator.geolocation?navigator.geolocation.getCurrentPosition(e=>t({latitude:e.coords.latitude,longitude:e.coords.longitude,accuracy:e.coords.accuracy,timestamp:e.timestamp}),()=>t(null),e):t(null)})}const g=i;function m(){var e;const{screen:t}=window;return{width:t.width,height:t.height,availWidth:t.availWidth,availHeight:t.availHeight,colorDepth:t.colorDepth,pixelRatio:window.devicePixelRatio||1,orientation:(null==(e=t.orientation)?void 0:e.type)||(window.innerWidth>window.innerHeight?"landscape-primary":"portrait-primary")}}async function p(){if(!("getBattery"in navigator))return{isCharging:!1,level:0,chargingTime:1/0,dischargingTime:1/0};try{const e=await navigator.getBattery();return{isCharging:e.charging,level:Math.round(100*e.level),chargingTime:e.chargingTime,dischargingTime:e.dischargingTime}}catch{return{isCharging:!1,level:0,chargingTime:1/0,dischargingTime:1/0}}}
 /**
    * @fileoverview aki-info-detect - Browser information detection library