@desert-ant-labs/desert-ant-web 0.1.0 → 0.2.0

package/README.md

@@ -19,6 +19,10 @@ usage.recordCall();         // once per inference; rides the session's load even
 
 - One `load` per device per session (30-min idle timeout); the server dedups by
   device per month and sums `callCount` across events.
+- Auto-collects low-entropy device context (`locale`, `osName`, `osVersion`,
+  `browserName`, `browserVersion`, `formFactor`) from User-Agent Client Hints /
+  the UA string — no high-entropy hints, no permission prompt. Pass `appVersion`
+  via `context` (it can't be auto-detected).
 - Zero dependencies, best-effort, never throws into the host.
 - `initUsage({ key?, endpoint?, callCount?, context?, disabled? })` — `endpoint`
   overrides the default (e.g. staging). `@desert-ant-labs/desert-ant-web/core`

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 export declare const SDK_NAME = "desert-ant-web";
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.2.0";
 export declare const DAY_MS: number;
 export declare const WEB_SESSION_MS: number;
 export type LoadContext = Record<string, unknown>;

package/dist/core.js

@@ -10,7 +10,7 @@
 // across events, so emitting an extra `load` never over-bills and a session's
 // calls can be split across several events and still add up.
 export const SDK_NAME = "desert-ant-web";
-export const SDK_VERSION = "0.1.0"; // keep in sync with package.json
+export const SDK_VERSION = "0.2.0"; // keep in sync with package.json
 // Re-emit windows. A node/mobile install is persistent, so a device re-emits at
 // most once a DAY. Web is session-shaped and its identity is ephemeral, so it
 // re-emits per SESSION — a new session being the first activity after this much

package/dist/device.d.ts

@@ -0,0 +1,10 @@
+export interface DeviceContext {
+    osName?: string;
+    osVersion?: string;
+    browserName?: string;
+    browserVersion?: string;
+    formFactor?: "desktop" | "mobile";
+}
+/** Device context, computed once — it's stable for the page's lifetime. */
+export declare function deviceContext(): DeviceContext;
+export declare function parseUserAgent(ua: string): DeviceContext;

package/dist/device.js

@@ -0,0 +1,119 @@
+// Low-entropy device context for web `load` events.
+//
+// Populated from User-Agent Client Hints where available (Chromium) and a
+// minimal `navigator.userAgent` parse everywhere else. Both are already
+// broadcast on every HTTP request the browser makes, so reading them client-side
+// adds no fingerprinting entropy beyond what the server already sees. We
+// deliberately never request *high-entropy* hints (exact OS version, device
+// model): that keeps MAD's "count devices, not users" stance and avoids a
+// permission-worthy surface. Consequences, by design:
+//   - `osVersion` is coarse (UA reduction freezes it — e.g. macOS reports 10.15.7).
+//   - `deviceModel` is omitted on web (browsers don't expose it low-entropy).
+//   - `formFactor` is `desktop` | `mobile` only (tablet needs a high-entropy hint).
+const major = (version) => version.split(".")[0];
+/** Device context, computed once — it's stable for the page's lifetime. */
+export function deviceContext() {
+    if (typeof navigator === "undefined")
+        return {};
+    const nav = navigator;
+    const ua = typeof nav.userAgent === "string" ? nav.userAgent : "";
+    // Base from the UA string (works in every browser, incl. Safari/Firefox which
+    // have no Client Hints), then refine with structured hints where present.
+    const ctx = parseUserAgent(ua);
+    const uaData = nav.userAgentData;
+    if (uaData) {
+        if (uaData.platform)
+            ctx.osName = normalizeOsName(uaData.platform);
+        if (typeof uaData.mobile === "boolean") {
+            ctx.formFactor = uaData.mobile ? "mobile" : "desktop";
+        }
+        const brand = uaData.brands ? pickBrand(uaData.brands) : undefined;
+        if (brand) {
+            ctx.browserName = brand.name;
+            ctx.browserVersion = major(brand.version);
+        }
+        // osVersion stays from the UA parse on purpose: the precise value lives in
+        // the high-entropy `platformVersion` hint, which we don't request.
+    }
+    return ctx;
+}
+// Choose the meaningful browser brand from the Client Hints list: drop the
+// "greased" decoy entries (random tokens the spec injects, e.g. "Not/A)Brand")
+// and prefer a specific vendor brand over the generic "Chromium" engine brand.
+function pickBrand(brands) {
+    const real = brands.filter((b) => !/not.?a.?brand/i.test(b.brand));
+    if (!real.length)
+        return undefined;
+    const pick = real.find((b) => b.brand !== "Chromium") ?? real[0];
+    return { name: pick.brand, version: pick.version };
+}
+// userAgentData.platform values ("Chrome OS"/"Chromium OS") → our UA-parse form.
+function normalizeOsName(platform) {
+    return /^chrom(e|ium) os$/i.test(platform) ? "ChromeOS" : platform;
+}
+// Windows kernel version → marketing name (the UA never carries "11").
+const WINDOWS_NAMES = {
+    "10.0": "10",
+    "6.3": "8.1",
+    "6.2": "8",
+    "6.1": "7",
+};
+// Exported for unit testing; prefer `deviceContext()` at call sites.
+export function parseUserAgent(ua) {
+    const ctx = {};
+    let m;
+    // OS name + (coarse) version. iOS/Android still carry a real version; Windows
+    // and macOS are frozen by UA reduction.
+    if ((m = ua.match(/Windows NT ([\d.]+)/))) {
+        ctx.osName = "Windows";
+        ctx.osVersion = WINDOWS_NAMES[m[1]] ?? m[1];
+    }
+    else if ((m = ua.match(/(?:iPhone OS|CPU OS) (\d+[_\d]*)/))) {
+        ctx.osName = "iOS";
+        ctx.osVersion = m[1].replace(/_/g, ".");
+    }
+    else if ((m = ua.match(/Mac OS X (\d+[_\d]*)/))) {
+        ctx.osName = "macOS";
+        ctx.osVersion = m[1].replace(/_/g, ".");
+    }
+    else if ((m = ua.match(/Android (\d+[.\d]*)/))) {
+        ctx.osName = "Android";
+        ctx.osVersion = m[1];
+    }
+    else if (/CrOS/.test(ua)) {
+        ctx.osName = "ChromeOS";
+    }
+    else if (/Linux/.test(ua)) {
+        ctx.osName = "Linux";
+    }
+    // Browser. Order matters: Edge/Opera masquerade with a "Chrome/" token, and
+    // Chrome's UA also contains "Safari", so check the specific brands first.
+    if ((m = ua.match(/Edg(?:e|A|iOS)?\/([\d.]+)/))) {
+        ctx.browserName = "Microsoft Edge";
+        ctx.browserVersion = major(m[1]);
+    }
+    else if ((m = ua.match(/(?:OPR|Opera)\/([\d.]+)/))) {
+        ctx.browserName = "Opera";
+        ctx.browserVersion = major(m[1]);
+    }
+    else if ((m = ua.match(/Firefox\/([\d.]+)/))) {
+        ctx.browserName = "Firefox";
+        ctx.browserVersion = major(m[1]);
+    }
+    else if ((m = ua.match(/Chrome\/([\d.]+)/))) {
+        ctx.browserName = "Chrome";
+        ctx.browserVersion = major(m[1]);
+    }
+    else if ((m = ua.match(/Version\/([\d.]+).*Safari/))) {
+        ctx.browserName = "Safari";
+        ctx.browserVersion = major(m[1]);
+    }
+    else if (/Safari\//.test(ua)) {
+        ctx.browserName = "Safari";
+    }
+    // Form factor: low-entropy phone-vs-not. Tablets read as desktop here (a
+    // high-entropy hint would be needed to split them out), matching our stance.
+    if (ua)
+        ctx.formFactor = /Mobi|iPhone|iPod/.test(ua) ? "mobile" : "desktop";
+    return ctx;
+}

package/dist/index.browser.d.ts

@@ -8,7 +8,12 @@ export interface UsageConfig {
     endpoint?: string;
     /** Authoritative call count, read at emit time. Alternative to recordCall(). */
     callCount?: () => number;
-    /** Extra context merged onto each load (appVersion, etc.). */
+    /**
+     * Extra context merged onto each load and wins over auto-collected fields.
+     * The SDK already fills in low-entropy device context (locale, osName,
+     * osVersion, browserName, browserVersion, formFactor); pass `appVersion` (your
+     * site's release string) here — it can't be detected automatically.
+     */
     context?: LoadContext | (() => LoadContext | undefined);
     /** Disable entirely (returns an inert client). */
     disabled?: boolean;

package/dist/index.browser.js

@@ -1,6 +1,7 @@
 // Browser entry. Batteries-included: wires the localStorage identity, the
 // beacon/fetch transport, and the page lifecycle into the core client.
 import { createClient, WEB_SESSION_MS } from "./core.js";
+import { deviceContext } from "./device.js";
 import { getDeviceId, loadState, saveState } from "./identity.js";
 import { makeSend } from "./transport.js";
 export { DAY_MS, WEB_SESSION_MS, createClient, uuid } from "./core.js";
@@ -42,9 +43,15 @@ export function initUsage(config = {}) {
     return client;
 }
 function contextProvider(c) {
+    // Auto-collected, low-entropy device context — computed once, stable for the
+    // page. Host-supplied context (e.g. appVersion) is merged on top and wins.
     const base = {};
     if (typeof navigator !== "undefined" && navigator.language)
         base.locale = navigator.language;
+    for (const [k, v] of Object.entries(deviceContext())) {
+        if (v !== undefined)
+            base[k] = v;
+    }
     if (typeof c === "function")
         return () => merge(base, c());
     if (c)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desert-ant-labs/desert-ant-web",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Internal shared browser/JS code for Desert Ant on-device SDKs (currently: usage reporting — active-device 'load' events to the ingestion API).",
   "type": "module",
   "main": "./dist/index.node.js",