ua-browser 0.1.9 → 1.0.1

package/README.md

@@ -1,206 +1,176 @@
-# uaBrowser - 浏览器检测
+# ua-browser
 
-通过userAgent和浏览器环境变量检测浏览器、系统及设备类型的常用工具
+[![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/)
 
-## 安装
+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.
 
-### npm
+**[📖 Documentation](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[中文](./README.zh-CN.md)**
 
-```sh
-npm i ua-browser
-```
+## Features
 
-### pnpm
+- **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
+# pnpm
 pnpm add ua-browser
+# yarn
+yarn add ua-browser
 ```
 
-### yarn
+## Quick Start
 
-```sh
-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:   'en-US',
+//   platform:   'Win32'
+// }
 ```
 
-## 支持方法
+> Pass a custom UA string: `uaBrowser('Mozilla/5.0 ...')`
+
+## Usage
+
+### Browser
 
 ```typescript
-import { uaBrowser } from 'ua-browser'
-
-/** 浏览器解析 */
-uaBrowser(ua?: string): {
-  version: string;
-  osVersion: string;
-  engine: string;
-  browser: string;
-  os: string;
-  device: string;
-  isWebview: boolean;
-  language: string;
-  platfrom: string;
+import uaBrowser from 'ua-browser'
+
+const { browser, os, device } = uaBrowser()
+
+if (device === 'Mobile') {
+  // redirect to mobile version
 }
 
-/** 检查 `webview` 浏览环境，仅支持 `android` */
-uaBrowser.isWebview(ua: string): boolean
+if (browser === 'Wechat') {
+  // WeChat in-app browser logic
+}
+```
 
-/** 检查微信小程序 */
-uaBrowser.isWechatMiniapp(): boolean
+### Node.js / SSR
 
-/** 浏览器语言 */
-uaBrowser.getLanguage(): string
+Use the pure `parseUA` function with the UA string from the request header:
+
+```typescript
+import { parseUA } from 'ua-browser'
 
-/** 当前版本 */
-uaBrowser.VERSION: string
+const ua = req.headers['user-agent'] ?? ''
+const { browser, os, isBot } = parseUA(ua)
+
+if (isBot) {
+  // block or allow crawlers
+}
 ```
 
-## 浏览器
+### CDN
 
-```typescript
-type browser =
-  | 'Safari'
-  | 'Chrome'
-  | 'IE'
-  | 'Edge'
-  | 'Firefox'
-  | 'Firefox Focus'
-  | 'Chromium'
-  | 'Opera'
-  | 'Vivaldi'
-  | 'Yandex'
-  | 'Arora'
-  | 'Lunascape'
-  | 'QupZilla'
-  | 'Coc Coc'
-  | 'Kindle'
-  | 'Iceweasel'
-  | 'Konqueror'
-  | 'Iceape'
-  | 'SeaMonkey'
-  | 'Epiphany'
-  | '360'
-  | '360EE'
-  | '360SE'
-  | 'UC'
-  | 'QQBrowser'
-  | 'QQ'
-  | 'Baidu'
-  | 'Maxthon'
-  | 'Sogou'
-  | 'Liebao'
-  | '2345Explorer'
-  | '115Browser'
-  | 'TheWorld'
-  | 'XiaoMi'
-  | 'Quark'
-  | 'Qiyu'
-  | 'Wechat'
-  | 'WechatWork'
-  | 'Taobao'
-  | 'Alipay'
-  | 'Weibo'
-  | 'Douban'
-  | 'Suning'
-  | 'iQiYi'
-  | 'DingTalk'
-  | 'Huawei'
-  | 'Vivo'
-  | 'Firefox Nightly'
-  | 'Wechat Miniapp'
+```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
-type engine =
-  | 'Trident'
-  | 'Presto'
-  | 'WebKit'
-  | 'Gecko'
-  | 'KHTML'
-  | 'Blink'
-  | 'EdgeHTML'
+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
+
+### Default export `uaBrowser(ua?)`
+
+Automatically injects the `navigator` context (language, platform, MIME types, etc.) in browser environments.
 
 ```typescript
-type os =
-  | 'Windows'
-  | 'Linux'
-  | 'MacOS'
-  | 'Android'
-  | 'HarmonyOS'
-  | 'Ubuntu'
-  | 'FreeBSD'
-  | 'Debian'
-  | 'Windows Phone'
-  | 'BlackBerry'
-  | 'MeeGo'
-  | 'Symbian'
-  | 'iOS'
-  | 'Chrome OS'
-  | 'WebOS'
+import uaBrowser from 'ua-browser'
+
+uaBrowser()          // reads navigator.userAgent automatically
+uaBrowser(customUA)  // custom UA string, still injects browser context
 ```
 
-## 设备类型
+### Named exports (tree-shakeable)
 
 ```typescript
-type device =
-  | 'Mobile'
-  | 'Tablet'
-  | 'Pc'
+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'
 ```
 
-## 浏览器支持
-
-| 浏览器 | 标识 |
-| :-- | :-- |
-| 苹果系统默认浏览器 | `Safari` |
-| 谷歌浏览器 | `Chrome` |
-| 微软IE浏览器 | `IE` |
-| 微软新一代浏览器 | `Edge` |
-| 火狐浏览器 | `Firefox` |
-| 火狐浏览器 | `Firefox Focus` |
-| 谷歌浏览器开源版 | `Chromium` |
-| Opera浏览器 | `Opera` |
-| Opera联合创始人发布 | `Vivaldi` |
-| 俄罗斯最大搜索引擎Yandex出品 | `Yandex` |
-| 基于webkit和Qt的轻量级浏览器 | `Arora` |
-| 来自日本的三引擎浏览器 | `Lunascape` |
-| 轻量级跨平台浏览器 | `QupZilla` |
-| 越南搜索引擎浏览器 | `Coc Coc` |
-| 亚马逊电子书 | `Kindle` |
-| Firefox浏览器的Debian再发布版 | `Iceweasel` |
-| Konqueror | `Konqueror` |
-| Iceape | `Iceape` |
-| SeaMonkey | `SeaMonkey` |
-| Epiphany | `Epiphany` |
-| 360浏览器(手机版) | `360` |
-| 360安全浏览器 | `360EE` |
-| 360极速浏览器 | `360SE` |
-| UC浏览器 | `UC` |
-| QQ浏览器 | `QQBrowser` |
-| QQ客户端 | `QQ` |
-| 百度浏览器 | `Baidu` |
-| 傲游浏览器 | `Maxthon` |
-| 搜狗浏览器 | `Sogou` |
-| 猎豹浏览器 | `Liebao` |
-| 2345浏览器 | `2345Explorer` |
-| 115浏览器 | `115Browser` |
-| 世界之窗浏览器 | `TheWorld` |
-| 小米浏览器 | `XiaoMi` |
-| 夸克浏览器 | `Quark` |
-| 旗鱼浏览器 | `Qiyu` |
-| 微信手机客户端 | `Wechat` |
-| 企业微信客户端 | `WechatWork` |
-| 淘宝手机客户端 | `Taobao` |
-| 支付宝手机客户端 | `Alipay` |
-| 微博手机客户端 | `Weibo` |
-| 豆瓣手机客户端 | `Douban` |
-| 苏宁易购手机客户端 | `Suning` |
-| 爱奇艺手机客户端 | `iQiYi` |
-| 钉钉手机客户端 | `DingTalk` |
-| 华为浏览器 | `Huawei` |
-| Vivo浏览器 | `Vivo` |
-| Firefox 下一代网络浏览器Nightly | `Firefox Nightly` |
-| 微信小程序 | `Wechat Miniapp` |
+### Return value `EnvOption`
+
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `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](./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