@scoutline-ai/middleware 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scoutline
+
+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

@@ -146,6 +146,8 @@ From the server: the method, pathname, user agent, whether a few standard header
 
 Query strings, cookies, auth headers, bodies, page text and field values are never sent.
 
+**Device details** come from the browser's Client Hints and, where your page runs the script, its major OS version, device model, whether it has a touch screen, and a screen size group such as `small`. Exact screen sizes and full versions are not sent, and these details are never combined into an identifier. Safari and Firefox share less, so some fields stay empty rather than guessed.
+
 **The visitor's IP address** is sent to the collector, which uses it to find the country and network, then discards it. It is never stored. Country is where the network is registered, so cloud traffic may not show where the machine really is. Turn this off with `sendClientIp: false`, and country and network stay empty.
 
 The collector classifies each request, so new crawlers are recognised without updating this package. A matching user agent is recorded as `declared`, because any client can send one. Other automation is `inferred`, and everything else is `unknown`. A browser claim that doesn't add up is only `inferred` when two different kinds of evidence agree, such as missing browser headers on a hosting network. This package never reports `verified`.

package/dist/browser-script.d.ts

@@ -1,7 +1,8 @@
 /**
  * Served from the customer's own domain at /_scoutline/s. It stays plain ES5 and
  * dependency free so it can load on any page. It collects no text, field values
- * or query strings, and stores nothing, so no cookie or consent is involved.
- * Everything it sends is an unverified claim and is revalidated in `browser.ts`.
+ * or query strings, and stores nothing. Device details stay coarse, such as a
+ * screen size group, and are never combined into an identifier. Everything it
+ * sends is an unverified claim and is revalidated in `browser.ts`.
  */
-export declare const BROWSER_SCRIPT = "(function(){\n  var ENDPOINT=\"/_scoutline/e\",MAX=20,queue=[],path=location.pathname;\n  var nav=performance.getEntriesByType?performance.getEntriesByType(\"navigation\")[0]:null;\n  var automated=navigator.webdriver===true;\n  function serverId(){\n    var timing=nav&&nav.serverTiming;\n    for(var i=0;timing&&i<timing.length;i++){\n      if(timing[i].name===\"scoutline\")return timing[i].description;\n    }\n  }\n  function send(){\n    if(!queue.length)return;\n    var now=Date.now(),events=[];\n    for(var i=0;i<queue.length;i++){\n      var e=queue[i];e.ageMs=now-e.at;delete e.at;events.push(e);\n    }\n    queue=[];\n    var body=JSON.stringify({automated:automated,events:events});\n    if(!navigator.sendBeacon||!navigator.sendBeacon(ENDPOINT,body)){\n      fetch(ENDPOINT,{method:\"POST\",body:body,keepalive:true})[\"catch\"](function(){});\n    }\n  }\n  function add(type,extra){\n    var e=extra||{};e.type=type;e.path=location.pathname;e.at=Date.now();\n    queue.push(e);\n    if(queue.length>=MAX)send();\n  }\n  function firstView(){\n    add(\"page_view\",{\n      parent:serverId(),\n      status:nav&&nav.responseStatus?nav.responseStatus:undefined,\n      durationMs:nav&&nav.duration?Math.round(nav.duration):undefined\n    });\n  }\n  function changed(){\n    if(location.pathname===path)return;\n    path=location.pathname;add(\"page_view\");\n  }\n  [\"pushState\",\"replaceState\"].forEach(function(name){\n    var original=history[name];\n    history[name]=function(){var r=original.apply(this,arguments);changed();return r;};\n  });\n  addEventListener(\"popstate\",changed);\n  document.addEventListener(\"click\",function(event){\n    var t=event.target&&event.target.closest&&event.target.closest(\"a,button,[role=button],input[type=submit]\");\n    if(t)add(\"click\",{element:t.tagName.toLowerCase()});\n  },true);\n  document.addEventListener(\"submit\",function(){add(\"form_submit\");},true);\n  addEventListener(\"error\",function(event){if(event.message)add(\"error\");});\n  addEventListener(\"unhandledrejection\",function(){add(\"error\");});\n  addEventListener(\"pagehide\",send);\n  document.addEventListener(\"visibilitychange\",function(){\n    if(document.visibilityState===\"hidden\")send();\n  });\n  if(document.readyState===\"complete\")setTimeout(firstView);\n  else addEventListener(\"load\",function(){setTimeout(firstView);});\n})();";
+export declare const BROWSER_SCRIPT = "(function(){\n  var ENDPOINT=\"/_scoutline/e\",MAX=20,queue=[],path=location.pathname;\n  var nav=performance.getEntriesByType?performance.getEntriesByType(\"navigation\")[0]:null;\n  var automated=navigator.webdriver===true;\n  var device={touch:navigator.maxTouchPoints>0};\n  var shortSide=window.screen?Math.min(screen.width,screen.height):0;\n  if(shortSide)device.screen=shortSide<600?\"small\":shortSide<900?\"medium\":\"large\";\n  if(window.matchMedia)device.coarsePointer=matchMedia(\"(pointer:coarse)\").matches;\n  var agent=navigator.userAgentData;\n  if(agent&&agent.getHighEntropyValues){\n    agent.getHighEntropyValues([\"platformVersion\",\"model\"]).then(function(values){\n      device.platform=agent.platform;device.mobile=agent.mobile;\n      device.platformVersion=values.platformVersion;device.model=values.model;\n    })[\"catch\"](function(){});\n  }\n  function serverId(){\n    var timing=nav&&nav.serverTiming;\n    for(var i=0;timing&&i<timing.length;i++){\n      if(timing[i].name===\"scoutline\")return timing[i].description;\n    }\n  }\n  function send(){\n    if(!queue.length)return;\n    var now=Date.now(),events=[];\n    for(var i=0;i<queue.length;i++){\n      var e=queue[i];e.ageMs=now-e.at;delete e.at;events.push(e);\n    }\n    queue=[];\n    var body=JSON.stringify({automated:automated,device:device,events:events});\n    if(!navigator.sendBeacon||!navigator.sendBeacon(ENDPOINT,body)){\n      fetch(ENDPOINT,{method:\"POST\",body:body,keepalive:true})[\"catch\"](function(){});\n    }\n  }\n  function add(type,extra){\n    var e=extra||{};e.type=type;e.path=location.pathname;e.at=Date.now();\n    queue.push(e);\n    if(queue.length>=MAX)send();\n  }\n  function firstView(){\n    add(\"page_view\",{\n      parent:serverId(),\n      status:nav&&nav.responseStatus?nav.responseStatus:undefined,\n      durationMs:nav&&nav.duration?Math.round(nav.duration):undefined\n    });\n  }\n  function changed(){\n    if(location.pathname===path)return;\n    path=location.pathname;add(\"page_view\");\n  }\n  [\"pushState\",\"replaceState\"].forEach(function(name){\n    var original=history[name];\n    history[name]=function(){var r=original.apply(this,arguments);changed();return r;};\n  });\n  addEventListener(\"popstate\",changed);\n  document.addEventListener(\"click\",function(event){\n    var t=event.target&&event.target.closest&&event.target.closest(\"a,button,[role=button],input[type=submit]\");\n    if(t)add(\"click\",{element:t.tagName.toLowerCase()});\n  },true);\n  document.addEventListener(\"submit\",function(){add(\"form_submit\");},true);\n  addEventListener(\"error\",function(event){if(event.message)add(\"error\");});\n  addEventListener(\"unhandledrejection\",function(){add(\"error\");});\n  addEventListener(\"pagehide\",send);\n  document.addEventListener(\"visibilitychange\",function(){\n    if(document.visibilityState===\"hidden\")send();\n  });\n  if(document.readyState===\"complete\")setTimeout(firstView);\n  else addEventListener(\"load\",function(){setTimeout(firstView);});\n})();";

package/dist/browser-script.js

@@ -1,13 +1,25 @@
 /**
  * Served from the customer's own domain at /_scoutline/s. It stays plain ES5 and
  * dependency free so it can load on any page. It collects no text, field values
- * or query strings, and stores nothing, so no cookie or consent is involved.
- * Everything it sends is an unverified claim and is revalidated in `browser.ts`.
+ * or query strings, and stores nothing. Device details stay coarse, such as a
+ * screen size group, and are never combined into an identifier. Everything it
+ * sends is an unverified claim and is revalidated in `browser.ts`.
  */
 export const BROWSER_SCRIPT = `(function(){
   var ENDPOINT="/_scoutline/e",MAX=20,queue=[],path=location.pathname;
   var nav=performance.getEntriesByType?performance.getEntriesByType("navigation")[0]:null;
   var automated=navigator.webdriver===true;
+  var device={touch:navigator.maxTouchPoints>0};
+  var shortSide=window.screen?Math.min(screen.width,screen.height):0;
+  if(shortSide)device.screen=shortSide<600?"small":shortSide<900?"medium":"large";
+  if(window.matchMedia)device.coarsePointer=matchMedia("(pointer:coarse)").matches;
+  var agent=navigator.userAgentData;
+  if(agent&&agent.getHighEntropyValues){
+    agent.getHighEntropyValues(["platformVersion","model"]).then(function(values){
+      device.platform=agent.platform;device.mobile=agent.mobile;
+      device.platformVersion=values.platformVersion;device.model=values.model;
+    })["catch"](function(){});
+  }
   function serverId(){
     var timing=nav&&nav.serverTiming;
     for(var i=0;timing&&i<timing.length;i++){
@@ -21,7 +33,7 @@ export const BROWSER_SCRIPT = `(function(){
       var e=queue[i];e.ageMs=now-e.at;delete e.at;events.push(e);
     }
     queue=[];
-    var body=JSON.stringify({automated:automated,events:events});
+    var body=JSON.stringify({automated:automated,device:device,events:events});
     if(!navigator.sendBeacon||!navigator.sendBeacon(ENDPOINT,body)){
       fetch(ENDPOINT,{method:"POST",body:body,keepalive:true})["catch"](function(){});
     }

package/dist/browser.d.ts

@@ -29,5 +29,14 @@ export declare function toBrowserEvent(raw: unknown, actor: Actor, now: number,
 } | null;
 export declare function parseBrowserBody(text: string): {
     automated: boolean;
+    device: {
+        touch: boolean | undefined;
+        coarsePointer: boolean | undefined;
+        mobile: boolean | undefined;
+        screen: string | undefined;
+        platform: string | undefined;
+        platformVersion: string | undefined;
+        model: string | undefined;
+    } | undefined;
     events: unknown[];
 } | null;

package/dist/browser.js

@@ -9,6 +9,10 @@ const MAX_DURATION_MS = 60 * 60 * 1000;
 const TYPES = new Set(["page_view", "click", "form_submit", "error"]);
 const ELEMENTS = new Set(["a", "button", "input", "div", "span"]);
 const SERVER_ID = /^[0-9a-f-]{36}$/;
+const SCREENS = new Set(["small", "medium", "large"]);
+const MAX_MODEL_CHARS = 64;
+const PLATFORM = /^[A-Za-z][A-Za-z0-9 ]{0,31}$/;
+const MODEL = /^[\w .()+-]+$/;
 /**
  * Anything in the page can be forged, so only a same-origin browser request is
  * accepted. This keeps out other sites, not a determined client, which is why
@@ -82,6 +86,31 @@ export function toBrowserEvent(raw, actor, now, sampleRate) {
         classifierVersion: BROWSER_CLASSIFIER_VERSION,
     };
 }
+/** Forged values can only mislabel the page that sent them. */
+function deviceOf(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { coarsePointer, mobile, model, platform, platformVersion, screen, touch } = raw;
+    const major = typeof platformVersion === "string"
+        ? /^\d{1,4}/.exec(platformVersion)?.[0]
+        : undefined;
+    return {
+        touch: typeof touch === "boolean" ? touch : undefined,
+        coarsePointer: typeof coarsePointer === "boolean" ? coarsePointer : undefined,
+        mobile: typeof mobile === "boolean" ? mobile : undefined,
+        screen: typeof screen === "string" && SCREENS.has(screen) ? screen : undefined,
+        platform: typeof platform === "string" && PLATFORM.test(platform)
+            ? platform
+            : undefined,
+        // The major version is enough, and the rest narrows down one machine.
+        platformVersion: major,
+        model: typeof model === "string" &&
+            model.length <= MAX_MODEL_CHARS &&
+            MODEL.test(model)
+            ? model
+            : undefined,
+    };
+}
 export function parseBrowserBody(text) {
     if (text.length > MAX_BODY_CHARS)
         return null;
@@ -92,6 +121,7 @@ export function parseBrowserBody(text) {
         }
         return {
             automated: body.automated === true,
+            device: deviceOf(body.device),
             events: body.events,
         };
     }

package/dist/index.d.ts

@@ -61,9 +61,10 @@ export declare function hostFromHeaders(headers: Headers): string | null;
 /** The site's hostname. */
 export declare function hostOf(request: Request): string | undefined;
 /**
- * What the collector needs to classify a request. Only whether these headers
- * exist is sent, never their values, and rules live there so they can change
- * without a new release of this package.
+ * What the collector needs to classify a request and name its device. The
+ * three Client Hints are the browser's own low-detail summary. For the others,
+ * only whether a header exists is sent. Rules live on the collector, so they can
+ * change without a new release of this package.
  */
 export declare function requestFacts(headers: Headers, options: {
     sendClientIp?: boolean;
@@ -71,6 +72,11 @@ export declare function requestFacts(headers: Headers, options: {
 }): {
     userAgent: string | undefined;
     clientIp: string | undefined;
+    clientHints: {
+        brands: string | undefined;
+        mobile: string | undefined;
+        platform: string | undefined;
+    };
     requestShape: {
         clientHints: boolean;
         fetchMetadata: boolean;

package/dist/index.js

@@ -14,6 +14,7 @@ const RATE_LIMITED_BACKOFF_MS = 60 * 1000;
 const MAX_FIELD_CHARS = 128;
 const MAX_URL_CHARS = 2048;
 const MAX_USER_AGENT_CHARS = 512;
+const MAX_HINT_CHARS = 256;
 /** Caps browser events per server instance, so a page can't flood the queue. */
 const MAX_BROWSER_EVENTS_PER_MINUTE = 2000;
 const SCRIPT_CACHE_SECONDS = 3600;
@@ -69,9 +70,10 @@ export function hostOf(request) {
     return limited(host.toLowerCase(), 255);
 }
 /**
- * What the collector needs to classify a request. Only whether these headers
- * exist is sent, never their values, and rules live there so they can change
- * without a new release of this package.
+ * What the collector needs to classify a request and name its device. The
+ * three Client Hints are the browser's own low-detail summary. For the others,
+ * only whether a header exists is sent. Rules live on the collector, so they can
+ * change without a new release of this package.
  */
 export function requestFacts(headers, options) {
     return {
@@ -79,6 +81,11 @@ export function requestFacts(headers, options) {
         clientIp: options.sendClientIp === false
             ? undefined
             : (options.clientIp ?? clientIpFromHeaders(headers)),
+        clientHints: {
+            brands: limited(headers.get("sec-ch-ua"), MAX_HINT_CHARS),
+            mobile: limited(headers.get("sec-ch-ua-mobile"), MAX_HINT_CHARS),
+            platform: limited(headers.get("sec-ch-ua-platform"), MAX_HINT_CHARS),
+        },
         requestShape: {
             clientHints: headers.has("sec-ch-ua"),
             fetchMetadata: headers.has("sec-fetch-mode") || headers.has("sec-fetch-site"),
@@ -305,8 +312,15 @@ export function createScoutline(options = {}) {
             });
             for (const raw of body.events) {
                 const event = toBrowserEvent(raw, actor, now, sampled ? sampleUnknown : 1);
-                if (event)
-                    enqueue({ ...event, ...facts, host: hostOf(request) });
+                if (!event)
+                    continue;
+                const device = event.action === "browser:page_view" ? body.device : null;
+                enqueue({
+                    ...event,
+                    ...facts,
+                    host: hostOf(request),
+                    device: device ?? undefined,
+                });
             }
             return emptyResponse(204);
         }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@scoutline-ai/middleware",
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "license": "MIT",
   "description": "In-path agent observation for Scoutline. Fails open and adds no work to the hot path.",
   "type": "module",
   "files": [