@devtune/ai-traffic 0.1.2 → 0.2.0

package/README.md

@@ -1,8 +1,6 @@
 # @devtune/ai-traffic
 
-`@devtune/ai-traffic` is the filtered edge-push sensor for DevTune AI Traffic. It matches incoming requests against DevTune's AI bot registry and forwards only matching machine hits to DevTune's ingest endpoint.
-
-Cloudflare-proxied sites should prefer the Cloudflare pull integration when available. For Vercel and self-hosted sites, this package keeps volume low by filtering at your edge instead of shipping full request logs.
+Measure which AI crawlers visit your site with a dependency-free sensor that filters at the edge and forwards only matched machine traffic to DevTune.
 
 ## Install
 
@@ -10,118 +8,196 @@ Cloudflare-proxied sites should prefer the Cloudflare pull integration when avai
 pnpm add @devtune/ai-traffic
 ```
 
-Set your project-scoped server-side ingest key:
+Create a project-scoped server-side ingest key and expose it only to your server runtime:
 
 ```bash
 DEVTUNE_AI_TRAFFIC_INGEST_KEY=dt_ingest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
-## Next.js Proxy / Middleware
+## Quickstarts
+
+### Next.js
 
-For Next.js 16, add `proxy.ts` and export `proxy()`. For older Next.js projects, use the same body from `middleware.ts` and export `middleware()` instead.
+For Next.js 16, add `proxy.ts`. For older Next.js projects, use the same body in `middleware.ts` and export `middleware()` instead.
 
 ```ts
 // proxy.ts
-import { createDevTuneAiTraffic } from "@devtune/ai-traffic";
+import { createDevTuneAiTrafficMiddleware } from "@devtune/ai-traffic";
 import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
 
-const aiTraffic = createDevTuneAiTraffic({
+const trackAiTraffic = createDevTuneAiTrafficMiddleware({
   ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
-  batchSize: 1,
-  defaultStatus: null,
-  flushIntervalMs: 0,
-  waitUntilRegistryRefresh: false,
 });
 
 export function proxy(request: NextRequest, event: NextFetchEvent) {
-  const response = NextResponse.next();
-
-  aiTraffic.trackRequest(request, event);
+  trackAiTraffic(request, event);
 
-  return response;
+  return NextResponse.next();
 }
 ```
 
-Use `defaultStatus: null` for pass-through proxy or middleware requests. Next.js proxy cannot observe the final status after route resolution, so this records the AI bot hit without guessing that every pass-through is a 200. Use `batchSize: 1` and `flushIntervalMs: 0` in middleware so Vercel does not hold middleware duration open for a delayed batch timer. Use `waitUntilRegistryRefresh: false` in middleware so hourly registry refreshes do not contribute to `waitUntil` duration. The package still schedules matched ingest work through `event.waitUntil()` when available, so the request path can return immediately after matching. Ordinary browser user agents are ignored before registry refresh work is scheduled.
-
-When your proxy or middleware returns a response directly, pass that exact status:
+### Express
 
 ```ts
-export function proxy(request: NextRequest, event: NextFetchEvent) {
-  const response = new Response("Forbidden", { status: 403 });
+import express from "express";
+import { createDevTuneAiTrafficExpressMiddleware } from "@devtune/ai-traffic/express";
 
-  aiTraffic.trackRequest(request, event, response.status);
+const app = express();
 
-  return response;
-}
+app.use(
+  createDevTuneAiTrafficExpressMiddleware({
+    ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
+  }),
+);
 ```
 
-If you only need a minimal best-effort hook, the middleware helper is also available:
+The middleware calls `next()` immediately and records the actual response status after Express emits `finish`.
+
+### Node HTTP
 
 ```ts
-import { createDevTuneAiTrafficMiddleware } from "@devtune/ai-traffic";
-import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
+import { createServer } from "node:http";
 
-const trackAiTraffic = createDevTuneAiTrafficMiddleware({
+import { createDevTuneAiTrafficNodeHandler } from "@devtune/ai-traffic/node";
+
+const trackAiTraffic = createDevTuneAiTrafficNodeHandler({
   ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
 });
 
-export function proxy(request: NextRequest, event: NextFetchEvent) {
-  trackAiTraffic(request, event);
+createServer((request, response) => {
+  trackAiTraffic(request, response);
 
-  return NextResponse.next();
-}
+  response.statusCode = 200;
+  response.end("ok");
+}).listen(3000);
 ```
 
-The middleware helper applies the middleware-safe defaults shown above: unknown pass-through status, immediate single-hit sends, and registry refreshes that are not attached to `waitUntil`. The package does not import `next/server`; it uses the standard request shape and the `waitUntil` method that Next.js passes to proxy and middleware functions.
+The hook records the final `response.statusCode` without blocking or changing the response.
+
+## Privacy by Design
 
-## Status Capture
+The sensor filters requests where your application runs. It uses a cheap user-agent hint before consulting the AI bot registry, and only matched machine hits are eligible to be forwarded. It uses no cookies, no fingerprinting, and no full request logs.
 
-Next.js proxy and middleware can report statuses they return directly, such as redirects, denials, and configured misses. They still cannot observe the final page response status after Next.js route resolution, so pass-through requests should use `defaultStatus: null` unless you intentionally want a best-effort default. When status is unknown, DevTune still counts the matched machine hit and treats status-specific reporting as unavailable for that event.
+For a matched crawler, DevTune receives only:
+
+- `path`
+- origin plus path, with query parameters removed
+- user agent
+- response status when the adapter can know it
+- timestamp
 
-Use the route wrapper where you own the handler response and need exact status capture:
+Request bodies, cookies, IP addresses, unrelated headers, and query-derived identifiers are not sent.
+
+## Detect Without Sending
+
+The standalone classifiers need no ingest key and never make a network request or push data to DevTune:
 
 ```ts
-// app/api/example/route.ts
-import { withDevTuneAiTrafficRoute } from "@devtune/ai-traffic";
-
-export const GET = withDevTuneAiTrafficRoute(
-  async function GET() {
-    return Response.json({ ok: true }, { status: 200 });
-  },
-  {
-    ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
-  },
-);
+import { detectAiCrawler, detectAiReferrer } from "@devtune/ai-traffic";
+
+const crawler = detectAiCrawler(request);
+const referrer = detectAiReferrer(request);
+```
+
+Each function also accepts the relevant string directly: a user-agent for `detectAiCrawler()` or a referrer URL for `detectAiReferrer()`.
+
+`detectAiCrawler()` returns the matched bot registry entry or `null`:
+
+```ts
+type AiCrawlerDetection = {
+  uaPattern: string;
+  llmPlatform: string;
+  botClass: "training_crawler" | "index_bot" | "answer_fetcher" | "acting_agent";
+  label: string;
+  status?: "active" | "retired";
+  asnHints?: number[] | null;
+  notes?: string | null;
+};
 ```
 
-For known misses in middleware, mark them explicitly:
+`detectAiReferrer()` returns the matched referrer registry entry or `null`:
+
+```ts
+type AiReferrerDetection = {
+  hostname: string;
+  llmPlatform: string;
+  label: string;
+};
+```
+
+Both use bundled registry snapshots by default, so they work offline and in CI. Pass `registryEntries` as the second argument when you need to classify against a pinned or private registry:
+
+```ts
+const match = detectAiCrawler(userAgent, {
+  registryEntries: myRegistryEntries,
+});
+```
+
+## Machine Traffic and Human Referrals
+
+The sensor deliberately measures machine traffic only. DevTune gets human visits from AI products through its GA4 integration, where sessions, engagement, and conversions provide a richer picture than middleware referrer matching. The referrer detector is available for local classification, but the sensor adapters never forward human referral visits.
+
+## Production Notes
+
+### Batching and Runtime Lifetime
+
+The default client configuration sends up to 10 matched events per unchanged ingest payload, with a 250 ms flush window for low-volume traffic. Set `batchSize: 1` and `flushIntervalMs: 0` to opt out and send each matched event immediately.
+
+Express and Node servers are long-lived enough to benefit directly from the default. Next.js proxy and middleware pass the delayed send to `event.waitUntil()` when available, which prevents the response from waiting but may keep the middleware invocation alive for the short flush window. Use the explicit opt-out in short-lived runtimes that cannot reliably preserve delayed work, or when minimizing middleware duration matters more than request coalescing:
 
 ```ts
 const trackAiTraffic = createDevTuneAiTrafficMiddleware({
   ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
-  notFoundPathPatterns: [/^\/docs\/removed\//],
+  batchSize: 1,
+  flushIntervalMs: 0,
 });
 ```
 
-## What Gets Sent
+The middleware helper leaves registry refresh work outside `waitUntil` by default. Ordinary browser user agents are rejected before refresh or ingest work is scheduled.
 
-For matched AI bot requests only, the package sends:
+### Status Semantics
 
-- `path`
-- `url`
-- `ua`
-- `status` when known
-- `ts`
+Express and Node adapters observe the completed response and report its actual status. Next.js proxy and middleware cannot observe the final route status after pass-through, so the convenience middleware omits status instead of guessing a 200.
+
+When a Next.js proxy returns a response directly, use the client and pass the known status:
+
+```ts
+import { createDevTuneAiTraffic } from "@devtune/ai-traffic";
+import type { NextFetchEvent, NextRequest } from "next/server";
 
-It sends the batch to `https://devtune.ai/api/v1/llm-traffic/ingest` with `Authorization: Bearer <ingest key>`. It does not send cookies, request bodies, query-derived user identifiers, IP addresses, headers other than the user agent, or DevTune's client-side snippet key.
+const aiTraffic = createDevTuneAiTraffic({
+  ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
+  defaultStatus: null,
+});
 
-## Registry Cache
+export function proxy(request: NextRequest, event: NextFetchEvent) {
+  const response = new Response("Forbidden", { status: 403 });
 
-The package fetches `https://devtune.ai/api/v1/llm-traffic/registry`, caches the active registry for about an hour, and uses `ETag` revalidation. If the registry cannot be fetched, it falls back to a bundled snapshot so known AI bots still match.
+  aiTraffic.trackRequest(request, event, response.status);
+
+  return response;
+}
+```
 
-User-agent matching is a v1 signal. Some agents spoof ordinary browsers or need ASN/TLS hints, so counts are floors rather than exact bot truth. Cloudflare pull should be used when available because Cloudflare can combine request, bot-score, and network-level signals.
+Use `withDevTuneAiTrafficRoute()` where you own a Fetch-compatible route handler and want its exact response status captured automatically. `notFoundPathPatterns` and `statusResolver` remain available for applications that can provide additional status knowledge.
+
+### Registry Refresh and Fallback
+
+Clients start with the bundled AI bot snapshot, refresh from `https://devtune.ai/api/v1/llm-traffic/registry`, cache active entries for about an hour, and use `ETag` revalidation. Failed refreshes are guarded and sampled; they never fail the application response, and the bundled snapshot remains usable.
+
+User-agent matching is a conservative signal. Some agents spoof ordinary browsers or require network-level signals, so reported counts are a floor rather than exact bot truth. Cloudflare-proxied sites should prefer DevTune's Cloudflare pull integration when available because it can combine request, bot-score, and network signals without running middleware.
+
+### Forwarded Origins
+
+Express and Node adapters build event URLs from the request protocol and host, preferring the first value in standard `X-Forwarded-Proto` and `X-Forwarded-Host` chains. Only accept those headers from a trusted proxy. If they are unavailable or not trustworthy in your deployment, pass a fixed `origin`:
+
+```ts
+const trackAiTraffic = createDevTuneAiTrafficNodeHandler({
+  ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
+  origin: "https://www.example.com",
+});
+```
 
-## Vercel Pull Status
+### Failure Behavior
 
-Vercel Observability exposes bot and AI-crawler insights in the dashboard query builder, but the public Observability REST API currently covers Observability Plus project settings rather than event reads. Until Vercel ships a supported Observability read/query API, this middleware is the Vercel path.
+Registry refresh and ingest sends are fire-and-forget and guarded. Network failures may drop telemetry, but they do not block, throw into, or alter the customer response. The ingest endpoint and batched wire format are unchanged.

package/dist/cjs/client.js

@@ -0,0 +1,407 @@
+"use strict";
+/**
+ * ABOUTME: Implements the DevTune AI Traffic edge-push client.
+ * Handles registry refresh, AI bot matching, batched ingest beacons, and route wrappers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevTuneAiTrafficClient = exports.DEFAULT_REGISTRY_URL = exports.DEFAULT_INGEST_ENDPOINT = void 0;
+exports.createDevTuneAiTraffic = createDevTuneAiTraffic;
+exports.createDevTuneAiTrafficMiddleware = createDevTuneAiTrafficMiddleware;
+exports.mightBeAiBotUserAgent = mightBeAiBotUserAgent;
+exports.withDevTuneAiTrafficRoute = withDevTuneAiTrafficRoute;
+const registry_js_1 = require("./registry.js");
+exports.DEFAULT_INGEST_ENDPOINT = "https://devtune.ai/api/v1/llm-traffic/ingest";
+exports.DEFAULT_REGISTRY_URL = "https://devtune.ai/api/v1/llm-traffic/registry";
+const DEFAULT_REGISTRY_REVALIDATE_MS = 60 * 60 * 1000;
+const DEFAULT_WAIT_UNTIL_REGISTRY_REFRESH = true;
+const DEFAULT_BATCH_SIZE = 10;
+const DEFAULT_FLUSH_INTERVAL_MS = 250;
+const DEFAULT_STATUS = 200;
+const MAX_INGEST_BATCH_SIZE = 100;
+const MAX_EVENT_PATH_LENGTH = 2048;
+const MAX_EVENT_UA_LENGTH = 2048;
+const MAX_EVENT_URL_LENGTH = 4096;
+const AI_BOT_USER_AGENT_HINTS = [
+    "-ai",
+    "ai-",
+    "agent",
+    "anthropic",
+    "bot",
+    "bytespider",
+    "claude",
+    "cohere",
+    "crawler",
+    "fetch",
+    "google-",
+    "gpt",
+    "meta-external",
+    "mistral",
+    "notebooklm",
+    "oai-",
+    "openai",
+    "perplexity",
+    "quora",
+    "spider",
+    "xai",
+];
+class DevTuneAiTrafficClient {
+    options;
+    endpoint;
+    registryUrl;
+    registryRevalidateMs;
+    waitUntilRegistryRefresh;
+    batchSize;
+    flushIntervalMs;
+    defaultStatus;
+    fetchImpl;
+    logger;
+    now;
+    random;
+    errorSampleRate;
+    registry;
+    refreshPromise = null;
+    flushPromise = null;
+    delayedFlushPromise = null;
+    queue = [];
+    constructor(options) {
+        this.options = options;
+        if (!options.ingestKey) {
+            throw new Error("DevTune AI Traffic ingestKey is required");
+        }
+        this.endpoint = options.endpoint ?? exports.DEFAULT_INGEST_ENDPOINT;
+        this.registryUrl = options.registryUrl ?? exports.DEFAULT_REGISTRY_URL;
+        this.registryRevalidateMs = options.registryRevalidateMs ?? DEFAULT_REGISTRY_REVALIDATE_MS;
+        this.waitUntilRegistryRefresh =
+            options.waitUntilRegistryRefresh ?? DEFAULT_WAIT_UNTIL_REGISTRY_REFRESH;
+        this.batchSize = clampInteger(options.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_INGEST_BATCH_SIZE);
+        this.flushIntervalMs = clampInteger(options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS, 0, 60_000);
+        this.defaultStatus =
+            options.defaultStatus === null
+                ? null
+                : normalizeStatus(options.defaultStatus ?? DEFAULT_STATUS, DEFAULT_STATUS);
+        this.fetchImpl = options.fetch ?? fetch;
+        this.logger = options.logger ?? null;
+        this.now = options.now ?? (() => new Date());
+        this.random = options.random ?? Math.random;
+        this.errorSampleRate = clampNumber(options.errorSampleRate ?? 0.01, 0, 1);
+        const fallbackEntries = (0, registry_js_1.compileAiBotRegistryEntries)(registry_js_1.FALLBACK_AI_BOT_REGISTRY_ENTRIES);
+        const fallbackPrefilter = createRegistryPrefilter(fallbackEntries);
+        this.registry = {
+            entries: fallbackEntries,
+            etag: null,
+            fetchedAt: 0,
+            ...fallbackPrefilter,
+            version: "bundled",
+        };
+    }
+    mightTrackRequest(request) {
+        const userAgent = request.headers.get("user-agent");
+        if (!userAgent) {
+            return false;
+        }
+        if (mightBeAiBotUserAgent(userAgent) || this.registry.requiresFullPrefilterScan) {
+            return true;
+        }
+        const normalized = userAgent.toLowerCase();
+        return this.registry.userAgentHints.some((hint) => normalized.includes(hint));
+    }
+    trackRequest(request, waitUntilContext, responseStatus) {
+        if (!this.mightTrackRequest(request)) {
+            return null;
+        }
+        const userAgent = request.headers.get("user-agent");
+        if (!userAgent) {
+            return null;
+        }
+        const entry = (0, registry_js_1.matchAiBotRegistryEntry)(userAgent, this.registry.entries);
+        if (!entry) {
+            if (mightBeAiBotUserAgent(userAgent)) {
+                this.refreshRegistryIfStale(waitUntilContext);
+            }
+            return null;
+        }
+        this.refreshRegistryIfStale(waitUntilContext);
+        const event = this.createEvent(request, userAgent, responseStatus);
+        if (!event) {
+            return null;
+        }
+        this.enqueue(event, waitUntilContext);
+        return {
+            entry,
+            event,
+        };
+    }
+    async refreshRegistry() {
+        const headers = {
+            accept: "application/json",
+        };
+        if (this.registry.etag) {
+            headers["if-none-match"] = this.registry.etag;
+        }
+        const response = await this.fetchImpl(this.registryUrl, {
+            headers,
+            method: "GET",
+        });
+        if (response.status === 304) {
+            this.registry = {
+                ...this.registry,
+                fetchedAt: Date.now(),
+            };
+            return;
+        }
+        if (!response.ok) {
+            throw new Error(`Registry request failed with status ${response.status}`);
+        }
+        const payload = (0, registry_js_1.parseAiBotRegistryPayload)(await response.json());
+        if (!payload) {
+            throw new Error("Registry response was not a valid DevTune registry");
+        }
+        const entries = (0, registry_js_1.compileAiBotRegistryEntries)(payload.entries);
+        this.registry = {
+            entries,
+            etag: response.headers.get("etag") ?? `"${payload.version}"`,
+            fetchedAt: Date.now(),
+            ...createRegistryPrefilter(entries),
+            version: payload.version,
+        };
+    }
+    async flush() {
+        if (this.flushPromise) {
+            return this.flushPromise;
+        }
+        this.flushPromise = this.flushQueuedEvents().finally(() => {
+            this.flushPromise = null;
+        });
+        return this.flushPromise;
+    }
+    refreshRegistryIfStale(waitUntilContext) {
+        if (this.refreshPromise) {
+            return;
+        }
+        if (Date.now() - this.registry.fetchedAt < this.registryRevalidateMs) {
+            return;
+        }
+        this.refreshPromise = this.refreshRegistry()
+            .catch((error) => {
+            this.registry = {
+                ...this.registry,
+                fetchedAt: Date.now(),
+            };
+            this.sampleWarn("Failed to refresh DevTune AI bot registry", { error });
+        })
+            .finally(() => {
+            this.refreshPromise = null;
+        });
+        scheduleBackground(this.refreshPromise, this.waitUntilRegistryRefresh ? waitUntilContext : undefined);
+    }
+    createEvent(request, userAgent, responseStatus) {
+        const url = parseRequestUrl(request.url);
+        if (!url) {
+            return null;
+        }
+        const pathname = truncateString(url.pathname || "/", MAX_EVENT_PATH_LENGTH);
+        const status = this.resolveStatus(request, pathname, responseStatus);
+        return {
+            path: pathname,
+            url: truncateString(`${url.origin}${pathname}`, MAX_EVENT_URL_LENGTH),
+            ua: truncateString(userAgent, MAX_EVENT_UA_LENGTH),
+            ...(status === null ? {} : { status }),
+            ts: this.now().toISOString(),
+        };
+    }
+    resolveStatus(request, pathname, responseStatus) {
+        if (responseStatus === null) {
+            return null;
+        }
+        const explicitStatus = normalizeStatus(responseStatus, null);
+        if (explicitStatus !== null) {
+            return explicitStatus;
+        }
+        const resolverStatus = this.options.statusResolver?.(request);
+        if (resolverStatus === null) {
+            return null;
+        }
+        const resolvedStatus = normalizeStatus(resolverStatus, null);
+        if (resolvedStatus !== null) {
+            return resolvedStatus;
+        }
+        if (this.matchesNotFoundPath(pathname)) {
+            return 404;
+        }
+        return this.defaultStatus;
+    }
+    matchesNotFoundPath(pathname) {
+        for (const pattern of this.options.notFoundPathPatterns ?? []) {
+            if (typeof pattern === "string") {
+                if (pattern === pathname) {
+                    return true;
+                }
+                continue;
+            }
+            pattern.lastIndex = 0;
+            if (pattern.test(pathname)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    enqueue(event, waitUntilContext) {
+        this.queue.push(event);
+        if (this.queue.length >= this.batchSize) {
+            scheduleBackground(this.flush(), waitUntilContext);
+            return;
+        }
+        if (this.delayedFlushPromise) {
+            scheduleBackground(this.delayedFlushPromise, waitUntilContext);
+            return;
+        }
+        this.delayedFlushPromise = delay(this.flushIntervalMs)
+            .then(() => this.flush())
+            .finally(() => {
+            this.delayedFlushPromise = null;
+        });
+        scheduleBackground(this.delayedFlushPromise, waitUntilContext);
+    }
+    async flushQueuedEvents() {
+        while (this.queue.length > 0) {
+            const batch = this.queue.splice(0, MAX_INGEST_BATCH_SIZE);
+            try {
+                const response = await this.fetchImpl(this.endpoint, {
+                    body: JSON.stringify({ events: batch }),
+                    headers: {
+                        authorization: `Bearer ${this.options.ingestKey}`,
+                        "content-type": "application/json",
+                    },
+                    keepalive: true,
+                    method: "POST",
+                });
+                if (!response.ok) {
+                    this.sampleWarn("DevTune AI Traffic ingest request failed", {
+                        status: response.status,
+                    });
+                }
+            }
+            catch (error) {
+                this.sampleWarn("DevTune AI Traffic ingest request failed", { error });
+            }
+        }
+    }
+    sampleWarn(message, context) {
+        if (this.errorSampleRate === 0 || this.random() > this.errorSampleRate) {
+            return;
+        }
+        this.logger?.warn(message, context);
+    }
+}
+exports.DevTuneAiTrafficClient = DevTuneAiTrafficClient;
+function createDevTuneAiTraffic(options) {
+    return new DevTuneAiTrafficClient(options);
+}
+function createDevTuneAiTrafficMiddleware(options) {
+    const client = createDevTuneAiTraffic({
+        ...options,
+        defaultStatus: options.defaultStatus ?? null,
+        waitUntilRegistryRefresh: options.waitUntilRegistryRefresh ?? false,
+    });
+    return function devTuneAiTrafficMiddleware(request, event) {
+        client.trackRequest(request, event);
+    };
+}
+function mightBeAiBotUserAgent(userAgent) {
+    if (!userAgent) {
+        return false;
+    }
+    const normalized = userAgent.toLowerCase();
+    return AI_BOT_USER_AGENT_HINTS.some((hint) => normalized.includes(hint));
+}
+function withDevTuneAiTrafficRoute(handler, options) {
+    const client = createDevTuneAiTraffic(options);
+    return async function devTuneAiTrafficRoute(request, context) {
+        const response = await handler(request, context);
+        const waitUntilContext = getWaitUntilContext(context);
+        client.trackRequest(request, waitUntilContext, response.status);
+        return response;
+    };
+}
+function scheduleBackground(promise, waitUntilContext) {
+    const guardedPromise = promise.catch(() => undefined);
+    if (waitUntilContext) {
+        waitUntilContext.waitUntil(guardedPromise);
+        return;
+    }
+    void guardedPromise;
+}
+function getWaitUntilContext(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const waitUntil = value.waitUntil;
+    if (typeof waitUntil !== "function") {
+        return undefined;
+    }
+    return {
+        waitUntil: (promise) => {
+            waitUntil.call(value, promise);
+        },
+    };
+}
+function parseRequestUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function delay(ms) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function createRegistryPrefilter(entries) {
+    const userAgentHints = new Set();
+    let requiresFullPrefilterScan = false;
+    for (const { entry } of entries) {
+        const hint = entry.uaPattern.toLowerCase();
+        if (hint.length < 3 || /[.^$|]/u.test(hint)) {
+            requiresFullPrefilterScan = true;
+            continue;
+        }
+        userAgentHints.add(hint);
+    }
+    return {
+        requiresFullPrefilterScan,
+        userAgentHints: [...userAgentHints],
+    };
+}
+function normalizeStatus(value, fallback) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599) {
+        return value;
+    }
+    return fallback;
+}
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value)) {
+        return min;
+    }
+    return Math.min(Math.max(Math.trunc(value), min), max);
+}
+function clampNumber(value, min, max) {
+    if (!Number.isFinite(value)) {
+        return min;
+    }
+    return Math.min(Math.max(value, min), max);
+}
+function truncateString(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return value.slice(0, maxLength);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=client.js.map