@davaux/user-agent 0.8.0

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- pka-generated -->
+# @davaux/user-agent
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.521Z
+
+## Overview
+
+User-Agent parsing middleware for Davaux
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+
+## Project Structure
+
+```
+├── CLAUDE.md
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (2)
+- `CLAUDE.md`
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@types/node, davaux, typescript
+
+
+
+
+
+
+
+
+
+## Exported Symbols
+
+**`src/index.ts`**
+`userAgent`, `UserAgent`
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @davaux/user-agent
+
+User-Agent parsing middleware for Davaux. Exposes structured device, browser, and OS information as `ctx.state.userAgent`.
+
+## Installation
+
+```bash
+npm install @davaux/user-agent
+```
+
+## Setup
+
+```ts
+// src/routes/_global.ts  (or _middleware.ts for a subtree)
+import { userAgent } from '@davaux/user-agent'
+export default userAgent()
+```
+
+## Usage
+
+```ts
+export default definePage((ctx) => {
+  const { isMobile, browserName, osName, isBot } = ctx.state.userAgent
+  return <p>Hello from {browserName} on {osName}</p>
+})
+```
+
+## `UserAgent` fields
+
+| Field | Type | Description |
+|---|---|---|
+| `raw` | `string` | Raw `User-Agent` header value |
+| `isMobile` | `boolean` | Mobile device (excludes tablets) |
+| `isTablet` | `boolean` | Tablet (iPad, or Android without Mobile token) |
+| `isDesktop` | `boolean` | Desktop/laptop (not bot, mobile, or tablet) |
+| `isBot` | `boolean` | Known bot, crawler, or non-browser client |
+| `botName` | `string?` | Bot name when `isBot` is true, e.g. `'Googlebot'`, `'curl'` |
+| `deviceType` | `'mobile' \| 'tablet' \| 'desktop' \| 'bot' \| 'unknown'` | Normalized device category |
+| `browserName` | `string?` | e.g. `'Chrome'`, `'Firefox'`, `'Safari'`, `'Edge'` |
+| `browserVersion` | `string?` | e.g. `'120.0.6099.130'` |
+| `osName` | `string?` | e.g. `'Windows'`, `'macOS'`, `'Android'`, `'iOS'` |
+| `osVersion` | `string?` | e.g. `'10'`, `'15.7'` |
+| `engine` | `string?` | e.g. `'Blink'`, `'Gecko'`, `'WebKit'` |
+| `partial` | `boolean` | `true` when signals are conflicting or insufficient to trust fully |
+
+## Documentation
+
+[davaux.codeberg.page/docs/user-agent](https://davaux.codeberg.page/docs/user-agent)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@davaux/user-agent",
+  "version": "0.8.0",
+  "description": "User-Agent parsing middleware for Davaux",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "davaux": ">=0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,306 @@
+import type { MiddlewareFn } from 'davaux'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface UserAgent {
+  /** Raw `User-Agent` header value. Empty string when the header is absent. */
+  raw: string
+  /** `true` when the UA contains mobile device indicators (excludes tablets). */
+  isMobile: boolean
+  /** `true` when the UA matches a tablet (iPad, Android without Mobile token). */
+  isTablet: boolean
+  /** `true` when the client is a desktop/laptop (not bot, not mobile, not tablet). */
+  isDesktop: boolean
+  /** `true` when the UA matches a known bot, crawler, or non-browser client. */
+  isBot: boolean
+  /** Bot name when `isBot` is true, e.g. `'Googlebot'`, `'curl'`. */
+  botName?: string
+  /** Normalized device category. */
+  deviceType: 'mobile' | 'tablet' | 'desktop' | 'bot' | 'unknown'
+  /** Browser family, e.g. `'Chrome'`, `'Firefox'`, `'Safari'`, `'Edge'`. */
+  browserName?: string
+  /** Browser version string, e.g. `'120.0.6099.130'`. */
+  browserVersion?: string
+  /** OS family, e.g. `'Windows'`, `'macOS'`, `'Android'`, `'iOS'`, `'Linux'`. */
+  osName?: string
+  /** OS version string, e.g. `'10'`, `'15.7'`, `'13'`. */
+  osVersion?: string
+  /** Rendering engine, e.g. `'Blink'`, `'Gecko'`, `'WebKit'`, `'Trident'`. */
+  engine?: string
+  /**
+   * `true` when signals are conflicting or insufficient to fully trust the result.
+   * Examples: a non-browser runtime running on a mobile/tablet OS (e.g. Dalvik on
+   * Android), or a Mozilla-prefixed UA with no detectable browser or OS (e.g. a
+   * gaming console with an unrecognised browser engine).
+   */
+  partial: boolean
+}
+
+declare module 'davaux' {
+  interface State {
+    userAgent: UserAgent
+  }
+}
+
+// ─── Bot detection ────────────────────────────────────────────────────────────
+
+// Named patterns match in any UA format, including browser-disguised bots.
+const BOT_PATTERNS: Array<[RegExp, string]> = [
+  [/Googlebot/i, 'Googlebot'],
+  [/Bingbot/i, 'Bingbot'],
+  [/DuckDuckBot/i, 'DuckDuckBot'],
+  [/Yahoo! Slurp/i, 'Yahoo Slurp'],
+  [/Baiduspider/i, 'Baiduspider'],
+  [/YandexBot/i, 'YandexBot'],
+  [/Sogou/i, 'Sogou'],
+  [/facebookexternalhit/i, 'FacebookBot'],
+  [/Twitterbot/i, 'Twitterbot'],
+  [/Applebot/i, 'Applebot'],
+  [/AdsBot-Google/i, 'AdsBot-Google'],
+  [/SemrushBot/i, 'SemrushBot'],
+  [/AhrefsBot/i, 'AhrefsBot'],
+  [/MJ12bot/i, 'MJ12bot'],
+  [/DotBot/i, 'DotBot'],
+  [/Screaming Frog/i, 'Screaming Frog'],
+  [/Scrapy/i, 'Scrapy'],
+  [/curl\//i, 'curl'],
+  [/wget\//i, 'wget'],
+  [/python-requests/i, 'python-requests'],
+  [/Python-urllib/i, 'Python-urllib'],
+  [/Go-http-client/i, 'Go HTTP'],
+  [/Java\/\d/i, 'Java'],
+  [/libwww-perl/i, 'libwww-perl'],
+]
+
+function detectBot(ua: string): { isBot: boolean; botName?: string } {
+  // Named patterns first — work regardless of Mozilla prefix.
+  for (const [pattern, name] of BOT_PATTERNS) {
+    if (pattern.test(ua)) return { isBot: true, botName: name }
+  }
+
+  // Non-browser clients never start with Mozilla/.
+  if (ua && !/^Mozilla\//i.test(ua)) {
+    // Try Name/Version token (covers most HTTP libs, CMSes, app runtimes).
+    // Allow commas so tokens like "AppleTV14,1" are captured whole.
+    const m = /^([\w][\w.,+-]*)\//.exec(ua)
+    if (m) return { isBot: true, botName: m[1] }
+    // No version token — extract service name before a generic bot keyword.
+    // e.g. "Traackr.com Bot" → "Traackr.com"
+    const k = /^(.*?)\s+(?:bot|crawler|spider)\b/i.exec(ua)
+    if (k) return { isBot: true, botName: k[1].trim() || 'Unknown' }
+    return { isBot: true, botName: 'Unknown' }
+  }
+
+  // Mozilla-prefixed bots: URL reference gives a better name than generic keywords.
+  // Real browsers never embed a URL in their UA string.
+  if (/https?:\/\//i.test(ua)) {
+    const m = /\(compatible;\s*([\w][\w. +-]*)\//.exec(ua)
+    return { isBot: true, botName: m ? m[1].trim() : 'Unknown' }
+  }
+
+  // Last resort: generic keyword match for Mozilla-prefixed unknown bots.
+  if (/\b(?:bot|crawler|spider)\b/i.test(ua)) return { isBot: true, botName: 'Unknown' }
+
+  return { isBot: false }
+}
+
+// ─── Device detection ─────────────────────────────────────────────────────────
+
+function detectTablet(ua: string): boolean {
+  if (/iPad/i.test(ua)) return true
+  // Android tablets omit "Mobile" from their UA string.
+  if (/Android/i.test(ua) && !/Mobile/i.test(ua)) return true
+  return false
+}
+
+function detectMobile(ua: string): boolean {
+  return /Mobi|Android|iPhone|iPod|Windows Phone|BlackBerry|IEMobile/i.test(ua)
+}
+
+// ─── Browser detection ────────────────────────────────────────────────────────
+
+function extractVersion(ua: string, token: string): string | undefined {
+  const m = new RegExp(`${token}/([\\d._]+)`, 'i').exec(ua)
+  return m ? m[1].replace(/_/g, '.') : undefined
+}
+
+interface BrowserResult {
+  browserName?: string
+  browserVersion?: string
+  engine?: string
+}
+
+function detectBrowser(ua: string): BrowserResult {
+  // Samsung Browser embeds Chrome in its UA — check first.
+  if (/SamsungBrowser\//i.test(ua)) {
+    return {
+      browserName: 'Samsung Browser',
+      browserVersion: extractVersion(ua, 'SamsungBrowser'),
+      engine: 'Blink',
+    }
+  }
+  // Chromium-based Edge ("Edg/") ships alongside Chrome token — check before Chrome.
+  if (/Edg\/\d/i.test(ua)) {
+    return { browserName: 'Edge', browserVersion: extractVersion(ua, 'Edg'), engine: 'Blink' }
+  }
+  // Legacy EdgeHTML-based Edge.
+  if (/Edge\/\d/i.test(ua)) {
+    return { browserName: 'Edge', browserVersion: extractVersion(ua, 'Edge'), engine: 'EdgeHTML' }
+  }
+  // Opera (Chromium-based, "OPR/").
+  if (/OPR\/\d/i.test(ua)) {
+    return { browserName: 'Opera', browserVersion: extractVersion(ua, 'OPR'), engine: 'Blink' }
+  }
+  // Chromium (open-source build, distinct from Google Chrome).
+  if (/Chromium\/\d/i.test(ua)) {
+    return {
+      browserName: 'Chromium',
+      browserVersion: extractVersion(ua, 'Chromium'),
+      engine: 'Blink',
+    }
+  }
+  // Google Chrome.
+  if (/Chrome\/\d/i.test(ua)) {
+    return { browserName: 'Chrome', browserVersion: extractVersion(ua, 'Chrome'), engine: 'Blink' }
+  }
+  // Firefox.
+  if (/Firefox\/\d/i.test(ua)) {
+    return {
+      browserName: 'Firefox',
+      browserVersion: extractVersion(ua, 'Firefox'),
+      engine: 'Gecko',
+    }
+  }
+  // Safari — must come after Chrome/Chromium since their UAs also contain "Safari".
+  if (/Safari\/\d/i.test(ua)) {
+    return {
+      browserName: 'Safari',
+      // "Version/x.x" carries the human-readable Safari version; fall back to Safari token.
+      browserVersion: extractVersion(ua, 'Version') ?? extractVersion(ua, 'Safari'),
+      engine: 'WebKit',
+    }
+  }
+  // Internet Explorer 11 (Trident/7 with rv: version).
+  if (/Trident\/\d/i.test(ua)) {
+    const m = /rv:([\d.]+)/.exec(ua)
+    return { browserName: 'Internet Explorer', browserVersion: m?.[1], engine: 'Trident' }
+  }
+  // Internet Explorer ≤ 10.
+  const ieMatch = /MSIE\s([\d.]+)/i.exec(ua)
+  if (ieMatch) {
+    return { browserName: 'Internet Explorer', browserVersion: ieMatch[1], engine: 'Trident' }
+  }
+  return {}
+}
+
+// ─── OS detection ─────────────────────────────────────────────────────────────
+
+const WINDOWS_NT_VERSIONS: Record<string, string> = {
+  '10.0': '10',
+  '6.3': '8.1',
+  '6.2': '8',
+  '6.1': '7',
+  '6.0': 'Vista',
+  '5.2': 'XP',
+  '5.1': 'XP',
+  '5.0': '2000',
+}
+
+interface OSResult {
+  osName?: string
+  osVersion?: string
+}
+
+function detectOS(ua: string): OSResult {
+  // Windows Phone must be checked before Windows NT.
+  let m = /Windows Phone(?:\s+OS)?\s+([\d.]+)/i.exec(ua)
+  if (m) return { osName: 'Windows Phone', osVersion: m[1] }
+
+  // Android (appears on both mobile and tablet UAs).
+  m = /Android\s+([\d.]+)/i.exec(ua)
+  if (m) return { osName: 'Android', osVersion: m[1] }
+
+  // iOS — covers iPhone, iPad (iPadOS ≥ 13 drops "iPhone" token), and iPod.
+  m = /(?:iPhone|iPad|iPod)[^)]*OS\s+([\d_]+)/i.exec(ua)
+  if (m) return { osName: 'iOS', osVersion: m[1].replace(/_/g, '.') }
+
+  // macOS / OS X.
+  m = /Mac OS X\s+([\d_.]+)/i.exec(ua)
+  if (m) return { osName: 'macOS', osVersion: m[1].replace(/_/g, '.') }
+
+  // Windows NT.
+  m = /Windows NT\s+([\d.]+)/i.exec(ua)
+  if (m) return { osName: 'Windows', osVersion: WINDOWS_NT_VERSIONS[m[1]] ?? m[1] }
+
+  if (/CrOS/i.test(ua)) return { osName: 'Chrome OS' }
+  if (/Linux/i.test(ua)) return { osName: 'Linux' }
+
+  return {}
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+function parse(raw: string): UserAgent {
+  const { isBot, botName } = detectBot(raw)
+  // Suppress device-type signals when isBot — they become noise, not signal.
+  const isTablet = !isBot && detectTablet(raw)
+  const isMobile = !isBot && !isTablet && detectMobile(raw)
+  const isDesktop = !isBot && !isTablet && !isMobile
+
+  let deviceType: UserAgent['deviceType']
+  if (isBot) deviceType = 'bot'
+  else if (isTablet) deviceType = 'tablet'
+  else if (isMobile) deviceType = 'mobile'
+  else if (raw) deviceType = 'desktop'
+  else deviceType = 'unknown'
+
+  const { browserName, browserVersion, engine } = detectBrowser(raw)
+  const { osName, osVersion } = detectOS(raw)
+
+  // Partial: non-browser runtime on a device we can identify (conflicting signals),
+  // or a browser UA with no detectable browser or OS (unrecognised device).
+  const partial =
+    (isBot && /Android|iPhone|iPad|iPod/i.test(raw)) ||
+    (!isBot && !browserName && !osName && raw.length > 0)
+
+  return {
+    raw,
+    isMobile,
+    isTablet,
+    isDesktop,
+    isBot,
+    botName,
+    deviceType,
+    browserName,
+    browserVersion,
+    engine,
+    osName,
+    osVersion,
+    partial,
+  }
+}
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+/**
+ * Parses the `User-Agent` request header and exposes structured data as
+ * `ctx.state.userAgent`. When the header is absent, `raw` is an empty string
+ * and all other fields are `undefined` / `false`.
+ *
+ * ```ts
+ * import { userAgent } from '@davaux/user-agent'
+ *
+ * // _global.ts or _middleware.ts
+ * export default userAgent()
+ *
+ * // A route handler:
+ * const { isMobile, isBot, browserName, osName } = ctx.state.userAgent
+ * ```
+ */
+export function userAgent(): MiddlewareFn {
+  return async (ctx, next) => {
+    const raw = (ctx.req.headers['user-agent'] as string | undefined) ?? ''
+    ctx.state.userAgent = parse(raw)
+    await next()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}