ua-browser 1.0.0 → 1.0.1

package/README.md

@@ -1,27 +1,39 @@
-# uaBrowser - 浏览器检测
+# ua-browser
 
-通过 User Agent 和浏览器环境变量检测浏览器、系统及设备类型，支持 Node.js 环境，零依赖。
+[![npm version](https://img.shields.io/npm/v/ua-browser?color=cb3837)](https://www.npmjs.com/package/ua-browser)
+[![npm downloads](https://img.shields.io/npm/dm/ua-browser)](https://www.npmjs.com/package/ua-browser)
+[![license](https://img.shields.io/npm/l/ua-browser)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6)](https://www.typescriptlang.org/)
 
-**[📖 文档](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)**
+Detect browser, OS, device type, rendering engine, CPU architecture, bots, and headless browsers from User Agent strings. Zero dependencies. Works in both browser and Node.js environments.
 
-## 安装
+**[📖 Documentation](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[中文](./README.zh-CN.md)**
+
+## Features
+
+- **Comprehensive detection** — browser, OS, engine, device type (Mobile / Tablet / TV / PC), CPU arch, bots, headless browsers
+- **AI bot recognition** — built-in support for GPTBot, ClaudeBot, PerplexityBot, CCBot and more
+- **Zero dependencies** — no runtime dependencies, tiny bundle size after gzip
+- **Pure function** — `parseUA()` has no global state, works seamlessly with SSR / Node.js
+- **TypeScript** — full type definitions with precise literal union types (`BrowserName`, `OsName`, etc.)
+- **Tree-shakeable** — import only what you need
+
+## Installation
 
 ```sh
 npm i ua-browser
-# or
+# pnpm
 pnpm add ua-browser
-# or
+# yarn
 yarn add ua-browser
 ```
 
-## 快速开始
+## Quick Start
 
 ```typescript
 import uaBrowser from 'ua-browser'
 
 const info = uaBrowser()
-// 或传入自定义 UA 字符串
-const info = uaBrowser('Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...')
 
 console.log(info)
 // {
@@ -36,47 +48,129 @@ console.log(info)
 //   isHeadless: false,
 //   isBot:      false,
 //   botName:    'unknown',
-//   language:   'zh-CN',
+//   language:   'en-US',
 //   platform:   'Win32'
 // }
 ```
 
-## 命名导出（tree-shakeable）
+> Pass a custom UA string: `uaBrowser('Mozilla/5.0 ...')`
+
+## Usage
+
+### Browser
 
 ```typescript
-import {
-  parseUA,          // 纯函数，可注入环境上下文
-  isWebview,        // 检测 Android Webview
-  isWechatMiniapp,  // 检测微信小程序
-  getLanguage,      // 获取浏览器语言
-  getWindowsVersion,// 异步获取 Windows 11/10 版本
-  detectBot,        // 单独使用爬虫检测
-  detectArch,       // 单独使用架构检测
-  detectHeadless,   // 单独使用无头浏览器检测
-  VERSION           // 当前版本号
-} from 'ua-browser'
+import uaBrowser from 'ua-browser'
+
+const { browser, os, device } = uaBrowser()
+
+if (device === 'Mobile') {
+  // redirect to mobile version
+}
+
+if (browser === 'Wechat') {
+  // WeChat in-app browser logic
+}
+```
+
+### Node.js / SSR
+
+Use the pure `parseUA` function with the UA string from the request header:
+
+```typescript
+import { parseUA } from 'ua-browser'
+
+const ua = req.headers['user-agent'] ?? ''
+const { browser, os, isBot } = parseUA(ua)
+
+if (isBot) {
+  // block or allow crawlers
+}
+```
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ua-browser/dist/index.min.js"></script>
+<script>
+  const { browser, os } = uaBrowser()
+</script>
+```
+
+### Accurate Windows 10 / 11 Detection
+
+Windows 10 and 11 share the same UA string. Use the Client Hints API to distinguish them:
+
+```typescript
+import { parseUA, getWindowsVersion, getNavContext } from 'ua-browser'
+
+const nav = getNavContext()
+const windowsVersion = await getWindowsVersion(nav)
+const result = parseUA(navigator.userAgent, { nav, windowsVersion })
+
+console.log(result.osVersion) // '10' or '11'
 ```
 
 ## API
 
-### `uaBrowser(ua?: string): EnvOption`
+### Default export `uaBrowser(ua?)`
+
+Automatically injects the `navigator` context (language, platform, MIME types, etc.) in browser environments.
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+uaBrowser()          // reads navigator.userAgent automatically
+uaBrowser(customUA)  // custom UA string, still injects browser context
+```
+
+### Named exports (tree-shakeable)
+
+```typescript
+import {
+  parseUA,           // pure function, ideal for SSR / Node.js
+  getNavContext,     // read current browser navigator context
+  getWindowsVersion, // async: accurately distinguish Windows 10 / 11
+  getLanguage,       // extract browser language from NavContext
+  isWebview,         // detect Android Webview (UA contains "; wv")
+  isWechatMiniapp,   // detect WeChat Mini Program environment
+  detectBot,         // standalone bot detection
+  detectArch,        // standalone CPU architecture detection
+  detectHeadless,    // standalone headless browser detection
+  VERSION,           // current library version
+} from 'ua-browser'
+```
 
-| 字段 | 类型 | 说明 |
+### Return value `EnvOption`
+
+| Field | Type | Description |
 | :-- | :-- | :-- |
-| `browser` | `BrowserName` | 浏览器名称 |
-| `version` | `string` | 浏览器版本 |
-| `engine` | `EngineName` | 渲染内核 |
-| `os` | `OsName` | 操作系统 |
-| `osVersion` | `string` | 系统版本 |
-| `device` | `DeviceName` | 设备类型 |
-| `arch` | `ArchName` | CPU 架构 |
-| `isWebview` | `boolean` | 是否为 Android Webview |
-| `isHeadless` | `boolean` | 是否为无头/自动化浏览器 |
-| `isBot` | `boolean` | 是否为爬虫/机器人 |
-| `botName` | `BotName` | 爬虫名称 |
-| `language` | `string` | 浏览器语言 |
-| `platform` | `string` | 平台信息 |
+| `browser` | `BrowserName` | Browser name |
+| `version` | `string` | Browser version |
+| `engine` | `EngineName` | Rendering engine |
+| `os` | `OsName` | Operating system |
+| `osVersion` | `string` | OS version |
+| `device` | `DeviceName` | Device type: `Mobile` \| `Tablet` \| `TV` \| `PC` |
+| `arch` | `ArchName` | CPU architecture |
+| `isWebview` | `boolean` | Whether running in Android Webview |
+| `isHeadless` | `boolean` | Whether running in a headless / automated browser |
+| `isBot` | `boolean` | Whether the UA belongs to a bot / crawler |
+| `botName` | `BotName` | Bot name |
+| `language` | `string` | Browser language, e.g. `en-US` |
+| `platform` | `string` | Platform identifier, e.g. `Win32` |
+
+> All fields return `'unknown'` when undetected — never an empty string or `null`.
+
+## Supported
+
+Over 60 browsers, 17 operating systems, and 19 bot rules built in. See the **[full support list](https://yangtianxia.github.io/ua-browser/guide/support-list)**.
+
+Highlights:
+- **Browsers** — Chrome, Safari, Firefox, Edge, Samsung Internet, UC, WeChat, DingTalk, TikTok and more
+- **OS** — Windows, macOS, Android, iOS, HarmonyOS, Tizen, KaiOS and more
+- **AI bots** — GPTBot, ClaudeBot, PerplexityBot, CCBot and more
+- **Devices** — Mobile, Tablet, TV (Samsung Smart TV, HbbTV), PC
 
 ## License
 
-MIT
+[MIT](./LICENSE) © yangtianxia

package/README.zh-CN.md

@@ -0,0 +1,176 @@
+# ua-browser
+
+[![npm version](https://img.shields.io/npm/v/ua-browser?color=cb3837)](https://www.npmjs.com/package/ua-browser)
+[![npm downloads](https://img.shields.io/npm/dm/ua-browser)](https://www.npmjs.com/package/ua-browser)
+[![license](https://img.shields.io/npm/l/ua-browser)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6)](https://www.typescriptlang.org/)
+
+通过 User Agent 检测浏览器、操作系统、设备类型、渲染内核、CPU 架构、爬虫及无头浏览器。零依赖，支持浏览器与 Node.js 双环境。
+
+**[📖 文档](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[English](./README.md)**
+
+## 特性
+
+- **全面检测** — 浏览器、OS、渲染内核、设备类型（Mobile / Tablet / TV / PC）、CPU 架构、爬虫、无头浏览器
+- **AI 爬虫识别** — 内置 GPTBot、ClaudeBot、PerplexityBot 等主流 AI 抓取机器人
+- **零依赖** — 无任何运行时依赖，gzip 后体积极小
+- **纯函数** — `parseUA()` 无全局状态，天然支持 SSR / Node.js
+- **TypeScript** — 完整类型定义，`BrowserName`、`OsName` 等均为精确字面量联合类型
+- **Tree-shakeable** — 所有功能按需导入，不引入多余代码
+
+## 安装
+
+```sh
+npm i ua-browser
+# pnpm
+pnpm add ua-browser
+# yarn
+yarn add ua-browser
+```
+
+## 快速上手
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+const info = uaBrowser()
+
+console.log(info)
+// {
+//   browser:    'Chrome',
+//   version:    '124.0.0.0',
+//   engine:     'Blink',
+//   os:         'Windows',
+//   osVersion:  '10',
+//   device:     'PC',
+//   arch:       'x86_64',
+//   isWebview:  false,
+//   isHeadless: false,
+//   isBot:      false,
+//   botName:    'unknown',
+//   language:   'zh-CN',
+//   platform:   'Win32'
+// }
+```
+
+> 传入自定义 UA 字符串：`uaBrowser('Mozilla/5.0 ...')`
+
+## 使用
+
+### 浏览器环境
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+const { browser, os, device } = uaBrowser()
+
+if (device === 'Mobile') {
+  // 跳转移动版
+}
+
+if (browser === 'Wechat') {
+  // 微信内置浏览器逻辑
+}
+```
+
+### Node.js / SSR
+
+使用 `parseUA` 纯函数，传入请求头中的 UA 字符串：
+
+```typescript
+import { parseUA } from 'ua-browser'
+
+const ua = req.headers['user-agent'] ?? ''
+const { browser, os, isBot } = parseUA(ua)
+
+if (isBot) {
+  // 拦截或放行爬虫
+}
+```
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ua-browser/dist/index.min.js"></script>
+<script>
+  const { browser, os } = uaBrowser()
+</script>
+```
+
+### 精确区分 Windows 10 / 11
+
+Windows 10 和 11 的 UA 字符串相同，需借助 Client Hints API 异步获取：
+
+```typescript
+import { parseUA, getWindowsVersion, getNavContext } from 'ua-browser'
+
+const nav = getNavContext()
+const windowsVersion = await getWindowsVersion(nav)
+const result = parseUA(navigator.userAgent, { nav, windowsVersion })
+
+console.log(result.osVersion) // '10' 或 '11'
+```
+
+## API
+
+### 默认导出 `uaBrowser(ua?)`
+
+在浏览器环境中自动注入 `navigator` 上下文（语言、平台、MIME 类型等）。
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+uaBrowser()           // 自动读取 navigator.userAgent
+uaBrowser(customUA)   // 传入自定义 UA，仍注入当前浏览器上下文
+```
+
+### 命名导出（按需引入）
+
+```typescript
+import {
+  parseUA,           // 纯函数，适合 SSR / Node.js
+  getNavContext,     // 读取当前浏览器 navigator 上下文
+  getWindowsVersion, // 异步精确区分 Windows 10 / 11
+  getLanguage,       // 从 NavContext 获取浏览器语言
+  isWebview,         // 检测 Android Webview（UA 含 "; wv"）
+  isWechatMiniapp,   // 检测微信小程序运行环境
+  detectBot,         // 独立爬虫检测
+  detectArch,        // 独立 CPU 架构检测
+  detectHeadless,    // 独立无头浏览器检测
+  VERSION,           // 当前版本号
+} from 'ua-browser'
+```
+
+### 返回值 `EnvOption`
+
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `browser` | `BrowserName` | 浏览器名称 |
+| `version` | `string` | 浏览器版本 |
+| `engine` | `EngineName` | 渲染内核 |
+| `os` | `OsName` | 操作系统 |
+| `osVersion` | `string` | 系统版本 |
+| `device` | `DeviceName` | 设备类型：`Mobile` \| `Tablet` \| `TV` \| `PC` |
+| `arch` | `ArchName` | CPU 架构 |
+| `isWebview` | `boolean` | 是否为 Android Webview |
+| `isHeadless` | `boolean` | 是否为无头 / 自动化浏览器 |
+| `isBot` | `boolean` | 是否为爬虫 / 机器人 |
+| `botName` | `BotName` | 爬虫名称 |
+| `language` | `string` | 浏览器语言，如 `zh-CN` |
+| `platform` | `string` | 平台标识，如 `Win32` |
+
+> 所有字段在无法识别时统一返回 `'unknown'`，不返回空字符串或 `null`。
+
+## 支持范围
+
+内置超过 60 种浏览器、17 种操作系统、19 种爬虫规则，详见 **[内置支持列表](https://yangtianxia.github.io/ua-browser/guide/support-list)**。
+
+部分覆盖：
+- **浏览器** — Chrome、Safari、Firefox、Edge、Samsung Internet、UC、微信、钉钉、抖音等
+- **操作系统** — Windows、macOS、Android、iOS、HarmonyOS、Tizen、KaiOS 等
+- **AI 爬虫** — GPTBot、ClaudeBot、PerplexityBot、CCBot 等
+- **设备** — Mobile、Tablet、TV（含三星 Smart TV、HbbTV 标准）、PC
+
+## License
+
+[MIT](./LICENSE) © yangtianxia

package/dist/index.cjs

@@ -4,7 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 // package.json
 var package_default = {
-  version: "1.0.0"};
+  version: "1.0.1"};
 
 // src/constants/browsers.ts
 var BROWSER_DEFS = [
@@ -19,6 +19,9 @@ var BROWSER_DEFS = [
   { name: "Opera", priority: 70, detect: /(Opera|OPR|OPT)/, versionPattern: [/Opera\/([\d.]+)/, /OPR\/([\d.]+)/, /OPT\/([\d.]+)/] },
   { name: "Vivaldi", priority: 80, detect: /Vivaldi/, versionPattern: /Vivaldi\/([\d.]+)/ },
   { name: "Yandex", priority: 90, detect: /YaBrowser/, versionPattern: /YaBrowser\/([\d.]+)/ },
+  { name: "Samsung Internet", priority: 92, detect: /SamsungBrowser/, versionPattern: /SamsungBrowser\/([\d.]+)/ },
+  { name: "DuckDuckGo", priority: 94, detect: /DuckDuckGo\//, versionPattern: /DuckDuckGo\/([\d.]+)/ },
+  { name: "Puffin", priority: 96, detect: /Puffin\//, versionPattern: /Puffin\/([\d.]+)/ },
   { name: "Arora", priority: 100, detect: /Arora/, versionPattern: /Arora\/([\d.]+)/ },
   { name: "Lunascape", priority: 110, detect: /Lunascape/, versionPattern: /Lunascape[\s]([\d.]+)/ },
   { name: "QupZilla", priority: 120, detect: /QupZilla/, versionPattern: /QupZilla[\s]([\d.]+)/ },
@@ -200,6 +203,7 @@ var OS_DEFS = [
   { name: "Ubuntu", detect: /Ubuntu/, versionPattern: null },
   { name: "Chrome OS", detect: /CrOS/, versionPattern: null },
   { name: "Linux", detect: /(Linux|X11)/, versionPattern: null },
+  { name: "Tizen", detect: /Tizen/, versionPattern: /Tizen ([\d.]+)/ },
   { name: "iOS", detect: /like Mac OS X/, versionPattern: /OS ([\d_]+) like/ },
   { name: "MacOS", detect: /Macintosh/, versionPattern: /Mac OS X -?([\d_.]+)/ },
   {
@@ -209,6 +213,7 @@ var OS_DEFS = [
     versionLookup: { "10": "2" }
   },
   { name: "Android", detect: /(Android|Adr)/, versionPattern: /(?:Android|Adr) ([\d.]+)/ },
+  { name: "KaiOS", detect: /KAIOS/, versionPattern: /KAIOS\/([\d.]+)/ },
   {
     name: "Windows",
     detect: /Windows/,
@@ -246,7 +251,8 @@ function detectOs(ua, windowsVersion) {
         if (mapped !== null) {
           osVersion = mapped;
         } else if (matchedDef.name === "Windows") {
-          osVersion = parseInt(normalised, 10).toString();
+          const n = parseInt(normalised, 10);
+          osVersion = isNaN(n) ? "unknown" : n.toString();
         }
       } else {
         osVersion = normalised;
@@ -261,18 +267,24 @@ function detectOs(ua, windowsVersion) {
 
 // src/constants/devices.ts
 var DEVICE_DEFS = [
-  { name: "Mobile", detect: /(Mobi|iPh|480)/ },
-  { name: "Tablet", detect: /(Tablet|Pad|Nexus 7)/ }
+  { name: "Mobile", detect: /(Mobi|iPh)/ },
+  { name: "Tablet", detect: /(Tablet|Pad)/ }
 ];
 
 // src/detectors/device.ts
 function detectDevice(ua, nav) {
+  if (/(SMART-TV|HbbTV|SmartTV|TV Safari|Android TV|GoogleTV)/.test(ua)) {
+    return "TV";
+  }
   if ((nav == null ? void 0 : nav.platform) === "MacIntel" && nav.maxTouchPoints > 1) {
     return "Tablet";
   }
   if (/iPad/.test(ua)) {
     return "Tablet";
   }
+  if (/Android/.test(ua) && !/Mobile/.test(ua)) {
+    return "Tablet";
+  }
   for (const def of DEVICE_DEFS) {
     if (def.detect.test(ua)) {
       return def.name;
@@ -303,6 +315,12 @@ var BOT_DEFS = [
   { name: "SemrushBot", detect: /SemrushBot/ },
   { name: "AhrefsBot", detect: /AhrefsBot/ },
   { name: "MJ12bot", detect: /MJ12bot/ },
+  // AI / LLM crawlers
+  { name: "GPTBot", detect: /GPTBot/ },
+  { name: "ClaudeBot", detect: /ClaudeBot/ },
+  { name: "PerplexityBot", detect: /PerplexityBot/ },
+  { name: "CCBot", detect: /CCBot/ },
+  { name: "AdsBot", detect: /AdsBot-Google/ },
   // Generic catch-all (must be last)
   { name: "GenericBot", detect: /(bot|crawler|spider|crawling|scraper)/i }
 ];
@@ -336,7 +354,7 @@ function detectArch(ua) {
 }
 
 // src/detectors/headless.ts
-var HEADLESS_PATTERN = /(HeadlessChrome|Headless|PhantomJS|Electron\/|Playwright)/;
+var HEADLESS_PATTERN = /(HeadlessChrome|Headless|PhantomJS|Electron\/|Playwright|jsdom\/|Selenium)/;
 function detectHeadless(ua) {
   return HEADLESS_PATTERN.test(ua);
 }
@@ -365,7 +383,7 @@ function getLanguage(nav) {
 
 // src/parse.ts
 function parseUA(ua, options = {}) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+  var _a, _b, _c, _d, _e;
   const { nav, windowsVersion } = options;
   const { browser: rawBrowser, version: rawVersion } = detectBrowser(ua);
   const { os, osVersion } = detectOs(ua, windowsVersion);
@@ -379,7 +397,8 @@ function parseUA(ua, options = {}) {
   let version = rawVersion;
   if (nav) {
     const chromeGlobal = typeof chrome !== "undefined" ? chrome : void 0;
-    const chromeMajor = parseInt((_c = ((_b = /Chrome\/([\d]+)/.exec(ua)) != null ? _b : [])[1]) != null ? _c : "0", 10);
+    const chromeMatch = /Chrome\/([\d]+)/.exec(ua);
+    const chromeMajor = chromeMatch ? parseInt(chromeMatch[1], 10) : 0;
     if (chromeGlobal) {
       if (chromeGlobal.adblock2345 || chromeGlobal.common2345) {
         browser = "2345Explorer";
@@ -395,7 +414,8 @@ function parseUA(ua, options = {}) {
           }
         }
         if (is360) {
-          if (getMimeType(nav, "application/gameplugin") || !((_d = nav.connection) == null ? void 0 : _d.saveData)) {
+          const saveDataEnabled = ((_b = nav.connection) == null ? void 0 : _b.saveData) === true;
+          if (getMimeType(nav, "application/gameplugin") || !saveDataEnabled) {
             browser = "360SE";
           } else {
             browser = "360EE";
@@ -407,7 +427,8 @@ function parseUA(ua, options = {}) {
   }
   if (browser === "Baidu" && /(Opera|OPR|OPT)/.test(ua)) {
     browser = "Opera";
-    version = (_j = (_i = (_g = ((_e = /OPR\/([\d.]+)/.exec(ua)) != null ? _e : [])[1]) != null ? _g : ((_f = /OPT\/([\d.]+)/.exec(ua)) != null ? _f : [])[1]) != null ? _i : ((_h = /Opera\/([\d.]+)/.exec(ua)) != null ? _h : [])[1]) != null ? _j : "unknown";
+    const opVer = (_d = (_c = /OPR\/([\d.]+)/.exec(ua)) != null ? _c : /OPT\/([\d.]+)/.exec(ua)) != null ? _d : /Opera\/([\d.]+)/.exec(ua);
+    version = (_e = opVer == null ? void 0 : opVer[1]) != null ? _e : "unknown";
   }
   if (browser === "Chrome" && /\S+Browser\//.test(ua)) {
     const m = /(\S+Browser)\/([\d.]+)/.exec(ua);
@@ -452,13 +473,13 @@ function parseUA(ua, options = {}) {
 
 // src/utils/windows-version.ts
 async function getWindowsVersion(nav) {
-  var _a, _b;
+  var _a;
   if (!nav.userAgentData || nav.userAgentData.platform !== "Windows") {
     return null;
   }
   try {
     const data = await nav.userAgentData.getHighEntropyValues(["platformVersion"]);
-    const major = parseInt((_b = (_a = data["platformVersion"]) == null ? void 0 : _a.split(".")[0]) != null ? _b : "0", 10);
+    const major = parseInt(((_a = data["platformVersion"]) == null ? void 0 : _a.split(".")[0]) || "0", 10);
     return major >= 13 ? "11" : "10";
   } catch (e) {
     return null;