@scoutline-ai/middleware 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# @scoutline-ai/middleware
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Records how agents use your site. It fails open: if Scoutline is down, misconfigured or slow, your site behaves exactly the same. Sending happens after your response, so it adds no latency.
+
+Set your key as an environment variable:
+
+```sh
+SCOUTLINE_KEY=sl_live_...
+```
+
+## Next.js
+
+Wrap your proxy in `proxy.ts` (`middleware.ts` before Next.js 16). Your existing handler keeps working.
+
+```ts
+import { withScoutline } from "@scoutline-ai/middleware/next";
+
+export default withScoutline(yourProxy); // or withScoutline() if you have none
+
+export const config = {
+  matcher: [
+    {
+      source: "/((?!_next/static|_next/image|favicon.ico).*)",
+      missing: [
+        { type: "header", key: "next-router-prefetch" },
+        { type: "header", key: "purpose", value: "prefetch" },
+      ],
+    },
+  ],
+};
+```
+
+Next.js removes prefetch headers before your proxy runs, so only the matcher can exclude them. The `missing` rule skips your whole proxy for prefetches, so leave it out if your proxy enforces auth. Prefetches then count as `unknown` traffic. They only come from browsers, so crawler and agent counts are unaffected.
+
+Your local and preview deployments can use the same key. Reports only count traffic on your site's domain and its subdomains.
+
+A proxy runs before the page renders, so normal page loads have no status or duration. Scoutline leaves those empty and only records a status when the proxy itself responds, such as a redirect.
+
+## Cloudflare Workers
+
+Pass the key in. Depending on its compatibility date and flags, a Worker may have no `process.env` to read it from.
+
+```ts
+import { env } from "cloudflare:workers";
+import { withScoutline } from "@scoutline-ai/middleware/fetch";
+
+export default { fetch: withScoutline(app.fetch, { key: env.SCOUTLINE_KEY }) };
+```
+
+Use `.dev.vars` locally and `npx wrangler secret put SCOUTLINE_KEY` in production. This sees the full response, so it records status, duration and size.
+
+## Hono and other fetch handlers
+
+```ts
+import { withScoutline } from "@scoutline-ai/middleware/fetch";
+
+export default { fetch: withScoutline(app.fetch) };
+```
+
+This also records status, duration and size. If Hono runs on Workers, pass the key as shown above.
+
+## Express and Fastify
+
+```ts
+import { scoutlineExpress, scoutlineFastify } from "@scoutline-ai/middleware/node";
+
+app.use(scoutlineExpress()); // Express: before your routes and body parsers
+
+app.register(scoutlineFastify); // Fastify
+```
+
+Both see the full response, so they record status, duration and size. Events send every few seconds.
+
+## Browser events
+
+The server sees every request, including crawlers that never run JavaScript. The browser script adds what only a page can see: real status and load time, in-page navigation, clicks and form submits, and errors.
+
+**Cloudflare Workers:** nothing to do. HTML pages get the script automatically.
+
+**Next.js, Hono, Express and Fastify:** add one tag to your root layout or HTML template.
+
+```html
+<script src="/_scoutline/s" defer></script>
+```
+
+The script and its events are served from your own domain by this package, so there is no public key and no third-party request. If your proxy `matcher` is limited to certain paths, include `/_scoutline/:path*`. These routes run before your own proxy, so an auth check won't block them.
+
+It stores nothing and sets no cookies. A page links to its server request through a `Server-Timing` header. Each batch of events is one request to your server, sent when the page closes or after 20 events.
+
+Browser events can be forged, so they are never `verified` and can't confirm an outcome. Reports keep them out of request counts.
+
+## Outcomes
+
+Outcomes are what your server confirms really happened, such as an order or a signup. They are never inferred from a 200.
+
+Create an outcome key on your Install page. It is separate from your middleware key.
+
+```sh
+SCOUTLINE_OUTCOME_KEY=sl_live_...
+```
+
+```ts
+import { createOutcomes } from "@scoutline-ai/middleware/outcomes";
+
+const outcomes = createOutcomes();
+
+// Runs your action, and confirms the outcome only if it succeeds.
+const order = await outcomes.wrap("order.placed", () => placeOrder(cart), (order) => ({
+  id: order.id,
+  taskId,
+  headers: request.headers,
+}));
+
+// Or confirm it yourself.
+await outcomes.confirm("signup.completed", { id: user.id, taskId });
+
+// Record a step on the way, or where it failed.
+await outcomes.record("checkout_attempted", { taskId, errorCategory: "card_declined" });
+```
+
+- **`id`** makes repeats safe: the same id counts once. It is hashed before sending. Without it, every call counts.
+- **`taskId`** is your id for one piece of work, and puts the event on that Workflow timeline.
+- **`headers`** are the incoming request's headers, which record who acted and the trace id.
+
+Nothing here throws, so a Scoutline problem can't fail your action. Each call returns `{ ok: true }` or `{ ok: false, reason }`. Events are sent straight away, at most twice for up to 2 seconds each, so don't await them if your action can't spare that.
+
+## Linking requests to a task
+
+Add your own ids to requests with `context`. Only what you return here is sent.
+
+```ts
+withScoutline(yourProxy, {
+  context: (request) => ({
+    taskId: request.headers.get("x-your-task-id"),
+    resourceId: productIdFrom(request),
+    contentVersion: process.env.VERCEL_GIT_COMMIT_SHA,
+  }),
+});
+```
+
+Requests that share a W3C `traceparent` with an event in the task also appear on its timeline, labelled as linked by trace.
+
+## What is sent
+
+From the server: the method, pathname, user agent, whether a few standard headers were present, and request and trace ids. Images, video, fonts and similar files are recorded for crawlers and agents, and skipped for everyone else, so one page load counts once. From the browser: the pathname, event type, element type such as `button`, status, and load time.
+
+Query strings, cookies, auth headers, bodies, page text and field values are never sent.
+
+**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`.
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `key` | `SCOUTLINE_KEY` | Ingest key |
+| `endpoint` | `SCOUTLINE_ENDPOINT`, then `https://ingest.scoutline.ai` | Collector URL |
+| `sampleUnknown` | `1` | Share of unclassified traffic to send, from 0 to 1 |
+| `ignore` | none | `(pathname) => boolean` to skip a path |
+| `sendClientIp` | `true` | Send the visitor's IP for the country and network lookup. It is never stored |
+| `context` | none | `(request) => ({ taskId, sessionId, resourceId, contentVersion })` adds your own ids |

package/dist/browser-script.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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`.
+ */
+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})();";

package/dist/browser-script.js

@@ -0,0 +1,63 @@
+/**
+ * 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`.
+ */
+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;
+  function serverId(){
+    var timing=nav&&nav.serverTiming;
+    for(var i=0;timing&&i<timing.length;i++){
+      if(timing[i].name==="scoutline")return timing[i].description;
+    }
+  }
+  function send(){
+    if(!queue.length)return;
+    var now=Date.now(),events=[];
+    for(var i=0;i<queue.length;i++){
+      var e=queue[i];e.ageMs=now-e.at;delete e.at;events.push(e);
+    }
+    queue=[];
+    var body=JSON.stringify({automated:automated,events:events});
+    if(!navigator.sendBeacon||!navigator.sendBeacon(ENDPOINT,body)){
+      fetch(ENDPOINT,{method:"POST",body:body,keepalive:true})["catch"](function(){});
+    }
+  }
+  function add(type,extra){
+    var e=extra||{};e.type=type;e.path=location.pathname;e.at=Date.now();
+    queue.push(e);
+    if(queue.length>=MAX)send();
+  }
+  function firstView(){
+    add("page_view",{
+      parent:serverId(),
+      status:nav&&nav.responseStatus?nav.responseStatus:undefined,
+      durationMs:nav&&nav.duration?Math.round(nav.duration):undefined
+    });
+  }
+  function changed(){
+    if(location.pathname===path)return;
+    path=location.pathname;add("page_view");
+  }
+  ["pushState","replaceState"].forEach(function(name){
+    var original=history[name];
+    history[name]=function(){var r=original.apply(this,arguments);changed();return r;};
+  });
+  addEventListener("popstate",changed);
+  document.addEventListener("click",function(event){
+    var t=event.target&&event.target.closest&&event.target.closest("a,button,[role=button],input[type=submit]");
+    if(t)add("click",{element:t.tagName.toLowerCase()});
+  },true);
+  document.addEventListener("submit",function(){add("form_submit");},true);
+  addEventListener("error",function(event){if(event.message)add("error");});
+  addEventListener("unhandledrejection",function(){add("error");});
+  addEventListener("pagehide",send);
+  document.addEventListener("visibilitychange",function(){
+    if(document.visibilityState==="hidden")send();
+  });
+  if(document.readyState==="complete")setTimeout(firstView);
+  else addEventListener("load",function(){setTimeout(firstView);});
+})();`;

package/dist/browser.d.ts

@@ -0,0 +1,33 @@
+import type { Actor } from "./classify.js";
+export declare const SCRIPT_PATH = "/_scoutline/s";
+export declare const EVENTS_PATH = "/_scoutline/e";
+export declare const BROWSER_CLASSIFIER_VERSION = "browser-0.1";
+/**
+ * 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
+ * these events stay low trust however they arrive.
+ */
+export declare function isSameOrigin(headers: Headers): boolean;
+/**
+ * Rebuilds each event from an allowlist, so unexpected fields are dropped. The
+ * `browser:` action prefix keeps these out of request counts, because a page
+ * load also produces a server event, and Googlebot runs this script too.
+ */
+export declare function toBrowserEvent(raw: unknown, actor: Actor, now: number, sampleRate: number): {
+    eventId: `${string}-${string}-${string}-${string}-${string}`;
+    occurredAt: number;
+    family: string;
+    actor: Actor;
+    action: string;
+    url: string;
+    interface: string;
+    parentActionId: string | undefined;
+    status: number | undefined;
+    durationMs: number | undefined;
+    sampleRate: number;
+    classifierVersion: string;
+} | null;
+export declare function parseBrowserBody(text: string): {
+    automated: boolean;
+    events: unknown[];
+} | null;

package/dist/browser.js

@@ -0,0 +1,101 @@
+export const SCRIPT_PATH = "/_scoutline/s";
+export const EVENTS_PATH = "/_scoutline/e";
+export const BROWSER_CLASSIFIER_VERSION = "browser-0.1";
+const MAX_BODY_CHARS = 16 * 1024;
+const MAX_EVENTS = 20;
+const MAX_AGE_MS = 10 * 60 * 1000;
+const MAX_PATH_CHARS = 2048;
+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}$/;
+/**
+ * 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
+ * these events stay low trust however they arrive.
+ */
+export function isSameOrigin(headers) {
+    const site = headers.get("sec-fetch-site");
+    if (site && site !== "same-origin")
+        return false;
+    const origin = headers.get("origin");
+    if (!origin)
+        return site === "same-origin";
+    const host = headers.get("x-forwarded-host") ?? headers.get("host");
+    try {
+        return new URL(origin).host === host;
+    }
+    catch {
+        return false;
+    }
+}
+function wholeNumber(value, max) {
+    return typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 0 &&
+        value <= max
+        ? value
+        : undefined;
+}
+function pathOf(value) {
+    if (typeof value !== "string" || value.length > MAX_PATH_CHARS)
+        return null;
+    try {
+        return new URL(value, "https://redacted.invalid").pathname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rebuilds each event from an allowlist, so unexpected fields are dropped. The
+ * `browser:` action prefix keeps these out of request counts, because a page
+ * load also produces a server event, and Googlebot runs this script too.
+ */
+export function toBrowserEvent(raw, actor, now, sampleRate) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const event = raw;
+    if (typeof event.type !== "string" || !TYPES.has(event.type))
+        return null;
+    const url = pathOf(event.path);
+    if (url === null)
+        return null;
+    const element = typeof event.element === "string" && ELEMENTS.has(event.element)
+        ? `:${event.element}`
+        : "";
+    const parent = typeof event.parent === "string" && SERVER_ID.test(event.parent)
+        ? event.parent
+        : undefined;
+    return {
+        eventId: crypto.randomUUID(),
+        occurredAt: now - (wholeNumber(event.ageMs, MAX_AGE_MS) ?? 0),
+        family: "resource_access",
+        actor,
+        action: `browser:${event.type}${element}`,
+        url,
+        interface: "web",
+        parentActionId: parent,
+        status: wholeNumber(event.status, 599),
+        durationMs: wholeNumber(event.durationMs, MAX_DURATION_MS),
+        sampleRate,
+        classifierVersion: BROWSER_CLASSIFIER_VERSION,
+    };
+}
+export function parseBrowserBody(text) {
+    if (text.length > MAX_BODY_CHARS)
+        return null;
+    try {
+        const body = JSON.parse(text);
+        if (!Array.isArray(body.events) || body.events.length > MAX_EVENTS) {
+            return null;
+        }
+        return {
+            automated: body.automated === true,
+            events: body.events,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/classify.d.ts

@@ -0,0 +1,11 @@
+export declare const CLASSIFIER_VERSION = "sdk-ua-0.1";
+type Purpose = "indexing" | "research";
+type Mode = "api" | "browser";
+export type Actor = {
+    class: "declared" | "inferred" | "unknown";
+    operator?: string;
+    purpose?: Purpose;
+    mode?: Mode;
+};
+export declare function classify(userAgent: string | null): Actor;
+export {};

package/dist/classify.js

@@ -0,0 +1,48 @@
+export const CLASSIFIER_VERSION = "sdk-ua-0.1";
+/**
+ * Published user agent tokens. A match is only a declaration, since any client
+ * can send these strings, so this never returns `verified`.
+ */
+const DECLARED = [
+    ["GPTBot", "OpenAI", "indexing"],
+    ["OAI-SearchBot", "OpenAI", "indexing"],
+    ["ChatGPT-User", "OpenAI", "research"],
+    ["ClaudeBot", "Anthropic", "indexing"],
+    ["Claude-SearchBot", "Anthropic", "indexing"],
+    ["Claude-User", "Anthropic", "research"],
+    ["PerplexityBot", "Perplexity", "indexing"],
+    ["Perplexity-User", "Perplexity", "research"],
+    ["Googlebot", "Google", "indexing"],
+    ["GoogleOther", "Google", "indexing"],
+    ["Google-CloudVertexBot", "Google", "indexing"],
+    ["bingbot", "Microsoft", "indexing"],
+    ["Applebot", "Apple", "indexing"],
+    ["Amazonbot", "Amazon", "indexing"],
+    ["meta-externalagent", "Meta", "indexing"],
+    ["meta-externalfetcher", "Meta", "research"],
+    ["Bytespider", "ByteDance", "indexing"],
+    ["CCBot", "Common Crawl", "indexing"],
+    ["cohere-ai", "Cohere", "indexing"],
+    ["MistralAI-User", "Mistral", "research"],
+    ["DuckAssistBot", "DuckDuckGo", "research"],
+    ["DuckDuckBot", "DuckDuckGo", "indexing"],
+];
+const AUTOMATED_BROWSER = /headless|playwright|puppeteer|selenium|phantomjs/i;
+const AUTOMATED_CLIENT = /bot\b|crawl|spider|scrape|curl\/|wget\/|python-requests|python-httpx|aiohttp|go-http-client|okhttp|axios\/|node-fetch|undici/i;
+export function classify(userAgent) {
+    if (!userAgent)
+        return { class: "unknown" };
+    const lower = userAgent.toLowerCase();
+    for (const [token, operator, purpose] of DECLARED) {
+        if (lower.includes(token.toLowerCase())) {
+            return { class: "declared", operator, purpose, mode: "api" };
+        }
+    }
+    if (AUTOMATED_BROWSER.test(userAgent)) {
+        return { class: "inferred", mode: "browser" };
+    }
+    if (AUTOMATED_CLIENT.test(userAgent)) {
+        return { class: "inferred", mode: "api" };
+    }
+    return { class: "unknown" };
+}

package/dist/client-ip.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Adapted from get-client-ip.ts in OpenPanel's Express SDK. The header order
+ * here puts platform-set headers first.
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 OpenPanel
+ *
+ * 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.
+ */
+/** Node reports an IPv4 client as `::ffff:1.2.3.4` on a dual-stack socket. */
+export declare function withoutIpv4Prefix(ip: string): string;
+export declare function usableIp(value: string | null | undefined): string | undefined;
+/** The first public address a proxy reported for the visitor. */
+export declare function clientIpFromHeaders(headers: Headers): string | undefined;

package/dist/client-ip.js

@@ -0,0 +1,83 @@
+/**
+ * Adapted from get-client-ip.ts in OpenPanel's Express SDK. The header order
+ * here puts platform-set headers first.
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 OpenPanel
+ *
+ * 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.
+ */
+const HEADER_ORDER = [
+    "cf-connecting-ip",
+    "x-vercel-forwarded-for",
+    "true-client-ip",
+    "x-real-ip",
+    "x-forwarded-for",
+    "fastly-client-ip",
+    "x-cluster-client-ip",
+    "x-appengine-user-ip",
+    "do-connecting-ip",
+    "x-nf-client-connection-ip",
+    "forwarded",
+];
+const IPV4 = /^(\d{1,3}\.){3}\d{1,3}$/;
+const IPV6 = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
+/** Node reports an IPv4 client as `::ffff:1.2.3.4` on a dual-stack socket. */
+export function withoutIpv4Prefix(ip) {
+    return ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip;
+}
+function isPublicIp(address) {
+    const ip = withoutIpv4Prefix(address);
+    if (ip === "::1")
+        return false;
+    if (/^(fc|fd|fe8|fe9|fea|feb)/i.test(ip) && ip.includes(":"))
+        return false;
+    if (/^(127|10)\./.test(ip))
+        return false;
+    if (ip.startsWith("192.168.") || ip.startsWith("169.254."))
+        return false;
+    if (ip.startsWith("172.")) {
+        const second = Number.parseInt(ip.split(".")[1] ?? "0", 10);
+        if (second >= 16 && second <= 31)
+            return false;
+    }
+    return true;
+}
+export function usableIp(value) {
+    const ip = value ? withoutIpv4Prefix(value.trim()) : "";
+    if (!(IPV4.test(ip) || IPV6.test(ip)))
+        return undefined;
+    return isPublicIp(ip) ? ip : undefined;
+}
+/** The first public address a proxy reported for the visitor. */
+export function clientIpFromHeaders(headers) {
+    for (const name of HEADER_ORDER) {
+        const value = headers.get(name);
+        if (!value)
+            continue;
+        const candidate = name === "forwarded"
+            ? /for="?\[?([^\]",;]+)/i.exec(value)?.[1]
+            : value.split(",")[0];
+        const ip = usableIp(candidate);
+        if (ip)
+            return ip;
+    }
+    return undefined;
+}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_ENDPOINT = "https://ingest.scoutline.ai";
+export declare function env(name: string): string | undefined;

package/dist/config.js

@@ -0,0 +1,4 @@
+export const DEFAULT_ENDPOINT = "https://ingest.scoutline.ai";
+export function env(name) {
+    return typeof process === "undefined" ? undefined : process?.env?.[name];
+}

package/dist/fetch.d.ts

@@ -0,0 +1,13 @@
+import { type ScoutlineOptions } from "./index.js";
+/**
+ * Wraps any fetch-style handler, such as a Cloudflare Worker or Hono's
+ * `app.fetch`. It sees the whole response, so status and duration are real.
+ * Bytes stay empty when the response has no Content-Length. On Cloudflare it
+ * also adds the browser script to HTML pages, so no code change is needed.
+ *
+ *   export default { fetch: withScoutline(app.fetch) };
+ *
+ * Workers should pass `{ key: env.SCOUTLINE_KEY }` from `cloudflare:workers`,
+ * because older compatibility dates have no `process.env` to read it from.
+ */
+export declare function withScoutline<Args extends unknown[]>(handler: (request: Request, ...args: Args) => Response | Promise<Response>, options?: ScoutlineOptions): (request: Request, ...args: Args) => Promise<Response>;

package/dist/fetch.js

@@ -0,0 +1,77 @@
+import { SCRIPT_PATH } from "./browser.js";
+import { createScoutline, isDocumentRequest, serverTiming, } from "./index.js";
+const SCRIPT_TAG = `<script src="${SCRIPT_PATH}" defer></script>`;
+function forPage(response, eventId) {
+    if (!response.headers.get("content-type")?.includes("text/html")) {
+        return response;
+    }
+    const page = new Response(response.body, response);
+    if (eventId)
+        page.headers.append("Server-Timing", serverTiming(eventId));
+    if (typeof HTMLRewriter === "undefined")
+        return page;
+    return new HTMLRewriter()
+        .on("head", {
+        element(head) {
+            head.append(SCRIPT_TAG, { html: true });
+        },
+    })
+        .transform(page);
+}
+function contentLength(response) {
+    const value = Number(response.headers.get("content-length"));
+    return response.headers.has("content-length") && Number.isFinite(value)
+        ? value
+        : null;
+}
+/**
+ * Wraps any fetch-style handler, such as a Cloudflare Worker or Hono's
+ * `app.fetch`. It sees the whole response, so status and duration are real.
+ * Bytes stay empty when the response has no Content-Length. On Cloudflare it
+ * also adds the browser script to HTML pages, so no code change is needed.
+ *
+ *   export default { fetch: withScoutline(app.fetch) };
+ *
+ * Workers should pass `{ key: env.SCOUTLINE_KEY }` from `cloudflare:workers`,
+ * because older compatibility dates have no `process.env` to read it from.
+ */
+export function withScoutline(handler, options) {
+    const scoutline = createScoutline(options);
+    return async function scoutlineFetch(request, ...args) {
+        const context = args.find((arg) => typeof arg?.waitUntil === "function");
+        const own = scoutline.handle(request);
+        if (own) {
+            const answer = await own;
+            context?.waitUntil(scoutline.flush());
+            return answer;
+        }
+        const started = Date.now();
+        const finish = (status, bytes) => {
+            const eventId = scoutline.observe(request, {
+                status,
+                bytes,
+                durationMs: Date.now() - started,
+                cacheStatus: null,
+            });
+            context?.waitUntil(scoutline.flush());
+            return eventId;
+        };
+        let response;
+        try {
+            response = await handler(request, ...args);
+        }
+        catch (error) {
+            finish(null, null);
+            throw error;
+        }
+        const eventId = finish(response.status, contentLength(response));
+        if (!isDocumentRequest(request))
+            return response;
+        try {
+            return forPage(response, eventId);
+        }
+        catch {
+            return response;
+        }
+    };
+}