@devtune/ai-traffic 0.12.0 → 0.13.0

package/dist/cjs/client.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * ABOUTME: Implements the DevTune AI Traffic edge-push client.
- * Handles registry refresh, AI bot matching, batched ingest beacons, and route wrappers.
+ * Handles registry refresh, AI bot and AI referral 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;
@@ -10,6 +10,7 @@ exports.createDevTuneAiTrafficMiddleware = createDevTuneAiTrafficMiddleware;
 exports.mightBeAiBotUserAgent = mightBeAiBotUserAgent;
 exports.withDevTuneAiTrafficRoute = withDevTuneAiTrafficRoute;
 const registry_js_1 = require("./registry.js");
+const referral_js_1 = require("./referral.js");
 const client_ip_js_1 = require("./client-ip.js");
 const version_js_1 = require("./version.js");
 const web_bot_auth_js_1 = require("./web-bot-auth.js");
@@ -27,6 +28,9 @@ const MAX_EVENT_PATH_LENGTH = 2048;
 const MAX_EVENT_UA_LENGTH = 2048;
 const MAX_EVENT_URL_LENGTH = 4096;
 const MAX_EVENT_IP_LENGTH = 45;
+const MAX_EVENT_REFERRER_LENGTH = 2048;
+const MAX_CAMPAIGN_VALUE_LENGTH = 512;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const UNAUTHORIZED_STATUS = 401;
 const RATE_LIMITED_STATUS = 429;
 const UNAVAILABLE_STATUS = 503;
@@ -36,6 +40,7 @@ const RETRY_BASE_DELAY_MS = 250;
 const DEFAULT_MAX_RETRY_DELAY_MS = 5_000;
 const RETRY_DELAY_CEILING_MS = 60_000;
 const DEFAULT_MAX_QUEUED_EVENTS = 1_000;
+const DEFAULT_MAX_QUEUED_REFERRAL_EVENTS = 200;
 const MAX_QUEUED_EVENTS_CEILING = 100_000;
 const AI_BOT_USER_AGENT_HINTS = [
     "-ai",
@@ -79,6 +84,8 @@ class DevTuneAiTrafficClient {
     maxRetryAttempts;
     maxRetryDelayMs;
     maxQueuedEvents;
+    maxQueuedReferralEvents;
+    captureReferrals;
     trustedProxy;
     projectId;
     keyCredential;
@@ -90,6 +97,7 @@ class DevTuneAiTrafficClient {
     flushPromise = null;
     delayedFlushPromise = null;
     queue = [];
+    referralQueue = [];
     constructor(options) {
         this.options = options;
         if (!options.ingestKey && !options.projectId) {
@@ -124,58 +132,57 @@ class DevTuneAiTrafficClient {
         this.maxRetryAttempts = clampInteger(options.maxRetryAttempts ?? DEFAULT_MAX_RETRY_ATTEMPTS, 0, RETRY_ATTEMPTS_CEILING);
         this.maxRetryDelayMs = clampInteger(options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS, 0, RETRY_DELAY_CEILING_MS);
         this.maxQueuedEvents = clampInteger(options.maxQueuedEvents ?? DEFAULT_MAX_QUEUED_EVENTS, MAX_INGEST_BATCH_SIZE, MAX_QUEUED_EVENTS_CEILING);
+        this.maxQueuedReferralEvents = clampInteger(options.maxQueuedReferralEvents ?? DEFAULT_MAX_QUEUED_REFERRAL_EVENTS, MAX_INGEST_BATCH_SIZE, MAX_QUEUED_EVENTS_CEILING);
+        this.captureReferrals = options.captureReferrals ?? true;
         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,
+            referrers: referral_js_1.FALLBACK_AI_REFERRAL_SOURCES,
             ...fallbackPrefilter,
             version: "bundled",
         };
     }
+    /**
+     * A cheap check that `trackRequest()` could record this request: true for
+     * an AI bot candidate, by user agent alone, or for an AI referral candidate
+     * (see `matchReferralPlatform`). Adapters that record after the response
+     * call it first, so other requests cost no response work. A request without
+     * a `url` is checked as a bot candidate only.
+     */
     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));
+        return this.mightBeAiBot(userAgent) || this.matchReferralPlatform(request) !== null;
     }
     /**
-     * Records a matched AI bot request. Pass `receivedAt` when the request is
-     * recorded after its response, taken from `signedArrivalTime()` as the
-     * request arrived: a signed event is checked against the time it was signed
-     * for. Other events keep the time they are recorded.
+     * Records a matched AI bot request or AI referral visit. A user agent in
+     * the bot registry makes it a bot request whatever its `Referer`. Pass
+     * `receivedAt` when the request is recorded after its response, taken from
+     * `signedArrivalTime()` as the request arrived: a signed bot event is
+     * checked against the time it was signed for. Other events keep the time
+     * they are recorded.
      */
     trackRequest(request, waitUntilContext, responseStatus, receivedAt) {
         this.refreshRegistryIfStale(waitUntilContext);
         this.captureVercelOidcToken(request);
-        if (!this.mightTrackRequest(request) ||
-            isPageInitiatedRequest(request) ||
-            isFrameworkDataRequest(request)) {
-            return null;
-        }
         const userAgent = request.headers.get("user-agent");
-        if (!userAgent) {
+        const source = userAgent ? this.matchSource(request, userAgent) : null;
+        if (!userAgent || !source) {
             return null;
         }
-        const entry = (0, registry_js_1.matchAiBotRegistryEntry)(userAgent, this.registry.entries);
-        if (!entry) {
-            return null;
-        }
-        const event = this.createEvent(request, userAgent, responseStatus, receivedAt);
+        const event = source.kind === "bot"
+            ? this.createBotEvent(request, userAgent, responseStatus, receivedAt)
+            : this.createReferralEvent(request, userAgent, responseStatus);
         if (!event) {
             return null;
         }
-        this.enqueue(event, waitUntilContext);
-        return {
-            entry,
-            event,
-        };
+        this.enqueue(source.kind, event, waitUntilContext);
+        return { ...source, event };
     }
     /**
      * The client's clock now for a request carrying Web Bot Auth signature
@@ -214,7 +221,8 @@ class DevTuneAiTrafficClient {
         if (!response.ok) {
             throw new Error(`Registry request failed with status ${response.status}`);
         }
-        const payload = (0, registry_js_1.parseAiBotRegistryPayload)(await response.json());
+        const body = await response.json();
+        const payload = (0, registry_js_1.parseAiBotRegistryPayload)(body);
         if (!payload) {
             throw new Error("Registry response was not a valid DevTune registry");
         }
@@ -226,15 +234,38 @@ class DevTuneAiTrafficClient {
             entries,
             etag: response.headers.get("etag") ?? `"${payload.version}"`,
             fetchedAt: Date.now(),
+            // Missing or unusable referrers, as from a registry older than referral
+            // capture, keep the last working lists.
+            referrers: (0, referral_js_1.parseAiReferralSources)((0, registry_js_1.isRecord)(body) ? body.referrers : undefined) ??
+                this.registry.referrers,
             ...createRegistryPrefilter(entries),
             version: payload.version,
         };
     }
     async flush() {
+        return this.startDrain(true);
+    }
+    /**
+     * Starts a drain, or joins the one in flight. A drain that spends a retry
+     * budget leaves events queued that would otherwise wait for the next tracked
+     * request, so it schedules one follow-up drain, no sooner than a capped
+     * retry's wait. The follow-up schedules none: if it is throttled too, the
+     * rest waits for the next tracked request, as before 0.13.0. The timer is
+     * unref'd and not tied to `waitUntil`, so only a long-lived process runs it.
+     */
+    startDrain(followUpWhenThrottled) {
         if (this.flushPromise) {
             return this.flushPromise;
         }
-        this.flushPromise = this.flushQueuedEvents().finally(() => {
+        this.flushPromise = this.flushQueuedEvents()
+            .then((spentRetries) => {
+            if (spentRetries && followUpWhenThrottled && this.queuedEventCount() > 0) {
+                const timer = setTimeout(() => scheduleBackground(this.startDrain(false)), Math.max(this.flushIntervalMs, this.maxRetryDelayMs));
+                // Retrying telemetry must never hold a Node process open.
+                timer.unref?.();
+            }
+        })
+            .finally(() => {
             this.flushPromise = null;
         });
         return this.flushPromise;
@@ -260,26 +291,133 @@ class DevTuneAiTrafficClient {
         });
         scheduleBackground(this.refreshPromise, this.waitUntilRegistryRefresh ? waitUntilContext : undefined);
     }
-    createEvent(request, userAgent, responseStatus, receivedAt) {
-        const url = parseRequestUrl(request.url);
-        if (!url) {
+    mightBeAiBot(userAgent) {
+        if (mightBeAiBotUserAgent(userAgent) || this.registry.requiresFullPrefilterScan) {
+            return true;
+        }
+        const normalized = userAgent.toLowerCase();
+        return this.registry.userAgentHints.some((hint) => normalized.includes(hint));
+    }
+    /**
+     * A bot registry match that is not a page's own request, or failing that the
+     * AI platform a referral visit came from. A bot user agent wins: it is never
+     * recorded as a referral.
+     */
+    matchSource(request, userAgent) {
+        const entry = this.mightBeAiBot(userAgent)
+            ? (0, registry_js_1.matchAiBotRegistryEntry)(userAgent, this.registry.entries)
+            : null;
+        if (entry) {
+            return isPageInitiatedRequest(request) || isFrameworkDataRequest(request)
+                ? null
+                : { kind: "bot", entry };
+        }
+        const platform = this.matchReferralPlatform(request);
+        return platform ? { kind: "referral", platform } : null;
+    }
+    /**
+     * The AI platform a referral candidate came from, or null. A candidate is a
+     * `GET` from another site (`Sec-Fetch-Site` not `same-origin` or
+     * `same-site`) whose `Referer` host, or failing that `utm_source`, is in the
+     * registry, and that loads a top-level page: `Sec-Fetch-Dest` is `document`
+     * or absent, it is not a prefetch, and it is not a framework data request.
+     * Frames stay bot-only. Every request reaches this, so the method and
+     * fetch-site checks and substring tests run before any URL is parsed.
+     * Browsers send the `Referer` host lower-cased, as the registry lists it.
+     * Always null when `captureReferrals` is off.
+     */
+    matchReferralPlatform(request) {
+        const { headers, method, url } = request;
+        if (!this.captureReferrals ||
+            (method !== "GET" && method !== "get") ||
+            typeof url !== "string") {
+            return null;
+        }
+        const site = headers.get("sec-fetch-site");
+        if (site === "same-origin" || site === "same-site") {
+            return null;
+        }
+        const platform = this.matchReferrerOrUtmSource(headers.get("referer"), url);
+        const destination = headers.get("sec-fetch-dest");
+        if (!platform ||
+            (destination !== null && destination !== "document") ||
+            isPageInitiatedRequest(request) ||
+            isFrameworkDataRequest({ headers, url })) {
+            return null;
+        }
+        return platform;
+    }
+    /** The `Referer` host's platform, or else the `utm_source`'s, as DevTune's classifier orders them. */
+    matchReferrerOrUtmSource(referer, url) {
+        const { referrers } = this.registry;
+        if (referer && mentionsAnyHost(referer, referrers.hosts)) {
+            const referrer = parseHttpUrl(referer);
+            const platform = referrer ? (0, referral_js_1.matchAiReferralHost)(referrer.hostname, referrers.hosts) : null;
+            if (platform) {
+                return platform;
+            }
+        }
+        if (!url.includes("utm_source=")) {
+            return null;
+        }
+        const source = parseRequestUrl(url)?.searchParams.get("utm_source");
+        return source ? (0, referral_js_1.matchAiReferralUtmSource)(source, referrers) : null;
+    }
+    createBotEvent(request, userAgent, responseStatus, receivedAt) {
+        const page = this.createBaseFields(request, userAgent, responseStatus);
+        if (!page) {
             return null;
         }
-        const pathname = truncateString(url.pathname || "/", MAX_EVENT_PATH_LENGTH);
-        const status = this.resolveStatus(request, pathname, responseStatus);
         const ip = (0, client_ip_js_1.resolveClientIp)(request, this.trustedProxy);
         const webBotAuth = readWebBotAuthSafely(request);
         const ts = webBotAuth && receivedAt && Number.isFinite(receivedAt.getTime()) ? receivedAt : this.now();
         return {
-            path: pathname,
-            url: truncateString(`${url.origin}${pathname}`, MAX_EVENT_URL_LENGTH),
-            ua: truncateString(userAgent, MAX_EVENT_UA_LENGTH),
-            ...(status === null ? {} : { status }),
+            ...page.fields,
             ts: ts.toISOString(),
             ...(ip === null ? {} : { ip: truncateString(ip, MAX_EVENT_IP_LENGTH) }),
             ...(webBotAuth === null ? {} : { webBotAuth }),
         };
     }
+    /**
+     * A referral visit carries its `Referer` origin and campaign parameters,
+     * and never an address or signature material: there is no claimed crawler
+     * identity to verify. A visit answered with a redirect is not recorded:
+     * the browser takes the same `Referer` to the redirect's target, which is
+     * where DevTune counts it, so ingest drops the redirect's event.
+     */
+    createReferralEvent(request, userAgent, responseStatus) {
+        const page = this.createBaseFields(request, userAgent, responseStatus);
+        if (!page || (page.fields.status !== undefined && REDIRECT_STATUSES.has(page.fields.status))) {
+            return null;
+        }
+        const referrer = readReferrerOrigin(request.headers.get("referer"));
+        const campaign = readCampaign(page.url);
+        return {
+            ...page.fields,
+            ts: this.now().toISOString(),
+            ...(referrer === null ? {} : { referrer }),
+            ...(campaign === null ? {} : { campaign }),
+        };
+    }
+    /** The fields every event carries. The `url` is the origin and path, without the query. */
+    createBaseFields(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 {
+            url,
+            fields: {
+                path: pathname,
+                url: truncateString(`${url.origin}${pathname}`, MAX_EVENT_URL_LENGTH),
+                ua: truncateString(userAgent, MAX_EVENT_UA_LENGTH),
+                ...(status === null ? {} : { status }),
+                ...(isBehindCdn(request.headers) ? { cdn: true } : {}),
+            },
+        };
+    }
     resolveStatus(request, pathname, responseStatus) {
         if (responseStatus === null) {
             return null;
@@ -317,24 +455,20 @@ class DevTuneAiTrafficClient {
         return false;
     }
     /**
-     * Adds an event to the queue and decides when to send.
+     * Adds an event to its queue and decides when to send.
      *
      * Backing off on a 429 means the queue can now drain slower than traffic
      * arrives, which it never could when every batch cost exactly one request.
      * The bound is what keeps that from growing without limit in a customer's
      * process: past `maxQueuedEvents` the oldest events are shed, because the
-     * newest ones are the ones still worth measuring.
+     * newest ones are the ones still worth measuring. Referral visits have
+     * their own queue and bound, `maxQueuedReferralEvents`, so a burst of them
+     * never sheds a bot event.
      */
-    enqueue(event, waitUntilContext) {
-        this.queue.push(event);
-        if (this.queue.length > this.maxQueuedEvents) {
-            const shed = this.queue.splice(0, this.queue.length - this.maxQueuedEvents);
-            this.sampleWarn("DevTune AI Traffic ingest queue overflowed", {
-                droppedEvents: shed.length,
-                maxQueuedEvents: this.maxQueuedEvents,
-            });
-        }
-        if (this.queue.length >= this.batchSize) {
+    enqueue(kind, event, waitUntilContext) {
+        (kind === "bot" ? this.queue : this.referralQueue).push(event);
+        this.shedOverflow(kind);
+        if (this.queuedEventCount() >= this.batchSize) {
             scheduleBackground(this.flush(), waitUntilContext);
             return;
         }
@@ -349,8 +483,37 @@ class DevTuneAiTrafficClient {
         });
         scheduleBackground(this.delayedFlushPromise, waitUntilContext);
     }
+    /** Sheds the oldest events past a queue's bound, with a sampled warning. */
+    shedOverflow(kind) {
+        const bot = kind === "bot";
+        const queue = bot ? this.queue : this.referralQueue;
+        const maxEvents = bot ? this.maxQueuedEvents : this.maxQueuedReferralEvents;
+        if (queue.length <= maxEvents) {
+            return;
+        }
+        const droppedEvents = queue.splice(0, queue.length - maxEvents).length;
+        if (bot) {
+            this.sampleWarn("DevTune AI Traffic ingest queue overflowed", {
+                droppedEvents,
+                maxQueuedEvents: maxEvents,
+            });
+        }
+        else {
+            this.sampleWarn("DevTune AI Traffic referral queue overflowed", {
+                droppedEvents,
+                maxQueuedReferralEvents: maxEvents,
+            });
+        }
+    }
     /**
-     * Drains the queue one wire batch at a time.
+     * Drains the queues one wire batch at a time, bots before referrals. A
+     * batch never mixes the two, and referrals never cost bots: each has its own
+     * retry budget per flush, a referral batch that spends its budget is dropped
+     * while bots keep draining, and a referral batch that gets a 429 while bots
+     * are waiting goes back to the front of its queue after the backoff, with
+     * its attempt count, so the bots are sent first. When the bots' budget is
+     * spent the drain ends there: the rate limit covers both kinds, so referrals
+     * would only meet the same 429, and the next drain starts with bots.
      *
      * A 429 is the one failure the ingest endpoint tells us is temporary, so the
      * batch is held out of the queue and redelivered after the server's
@@ -360,14 +523,14 @@ class DevTuneAiTrafficClient {
      * are not folded into the batch being retried, so they cannot be dropped on a
      * bound they never had a chance to spend.
      *
-     * The retry budget belongs to the whole drain, not to each batch. A per-batch
+     * Each budget belongs to the whole drain, not to each batch. A per-batch
      * bound says nothing about how long a drain can run, because a throttled
      * endpoint rejects every batch in turn and traffic keeps arriving behind it.
-     * One budget per pass caps the added latency of a flush at
-     * `maxRetryAttempts * maxRetryDelayMs` no matter how deep the queue is. When
-     * it is spent the current batch is dropped with the usual sampled warning and
-     * the drain stops, leaving the rest queued for the next flush, which gets a
-     * fresh budget.
+     * One budget per kind per pass caps the added latency of a flush at
+     * `2 * maxRetryAttempts * maxRetryDelayMs` no matter how deep the queues
+     * are. When a budget is spent the current batch is dropped with the usual
+     * sampled warning, leaving the rest queued for the next flush, which gets
+     * fresh budgets. Resolves true when a budget was spent.
      *
      * Every other failure keeps its previous behavior: one attempt, dropped, and
      * a sampled warning.
@@ -382,12 +545,26 @@ class DevTuneAiTrafficClient {
      * keys, is retried exactly like a 429.
      */
     async flushQueuedEvents() {
-        let retryBudget = this.maxRetryAttempts;
+        const retryBudgets = { bot: this.maxRetryAttempts, referral: this.maxRetryAttempts };
+        let referralsStopped = false;
         let keyOnly = false;
         const failedExchanges = new Map();
-        while (this.queue.length > 0) {
-            const batch = this.queue.splice(0, MAX_INGEST_BATCH_SIZE);
-            let attempts = 0;
+        // The last referral batch that stepped aside for bots. The queue bound
+        // sheds from the front, so its last event is the one that survives.
+        let requeued = null;
+        for (;;) {
+            const kind = this.queue.length > 0
+                ? "bot"
+                : !referralsStopped && this.referralQueue.length > 0
+                    ? "referral"
+                    : null;
+            if (kind === null) {
+                return referralsStopped;
+            }
+            const batch = (kind === "bot" ? this.queue : this.referralQueue).splice(0, MAX_INGEST_BATCH_SIZE);
+            let attempts = kind === "referral" && requeued?.last !== undefined && batch.includes(requeued.last)
+                ? requeued.attempts
+                : 0;
             for (;;) {
                 // The key path stays synchronous up to each send, as it always was.
                 const credential = !keyOnly && this.projectId && this.vercelOidcToken
@@ -398,10 +575,11 @@ class DevTuneAiTrafficClient {
                 }
                 if (credential === null || credential === "drop-queue") {
                     if (credential === null) {
-                        this.warnMissingVercelOidcTokenOnce(batch.length + this.queue.length);
+                        this.warnMissingVercelOidcTokenOnce(batch.length + this.queuedEventCount());
                     }
                     this.queue.splice(0);
-                    return;
+                    this.referralQueue.splice(0);
+                    return false;
                 }
                 let response;
                 try {
@@ -436,17 +614,29 @@ class DevTuneAiTrafficClient {
                     }
                     break;
                 }
-                if (retryBudget === 0) {
+                if (retryBudgets[kind] === 0) {
                     this.sampleWarn("DevTune AI Traffic ingest request failed", {
                         attempts,
                         droppedEvents: batch.length,
                         status: response.status,
                     });
-                    return;
+                    if (kind === "bot") {
+                        return true;
+                    }
+                    referralsStopped = true;
+                    break;
                 }
-                const retryDelayMs = this.resolveRetryDelayMs(response.headers.get("retry-after"), this.maxRetryAttempts - retryBudget);
-                retryBudget -= 1;
+                const retryDelayMs = this.resolveRetryDelayMs(response.headers.get("retry-after"), this.maxRetryAttempts - retryBudgets[kind]);
+                retryBudgets[kind] -= 1;
                 await delay(retryDelayMs);
+                // The rate limit covers both kinds, so waiting bots go after the
+                // backoff rather than into the same 429.
+                if (kind === "referral" && this.queue.length > 0) {
+                    this.referralQueue.unshift(...batch);
+                    this.shedOverflow("referral");
+                    requeued = { last: batch.at(-1), attempts };
+                    break;
+                }
             }
         }
     }
@@ -455,19 +645,26 @@ class DevTuneAiTrafficClient {
      * Vercel only puts the token on requests, never in the environment, so it
      * cannot be read when the client is built. Every token from one deployment
      * carries the same identity, so the latest one can send events queued by
-     * earlier requests.
+     * earlier requests. Adapters that filter requests or track after the
+     * response call this on every request as it arrives, before filtering; it
+     * never tracks, sends or throws into the handler.
      */
     captureVercelOidcToken(request) {
         if (!this.projectId) {
             return;
         }
-        const value = request.headers.get(vercel_oidc_js_1.VERCEL_OIDC_TOKEN_HEADER);
-        if (!value || value === this.vercelOidcToken?.value) {
-            return;
+        try {
+            const value = request.headers.get(vercel_oidc_js_1.VERCEL_OIDC_TOKEN_HEADER);
+            if (!value || value === this.vercelOidcToken?.value) {
+                return;
+            }
+            const expiresAtMs = (0, vercel_oidc_js_1.readVercelOidcTokenExpiry)(value, this.now().getTime());
+            if (expiresAtMs !== null) {
+                this.vercelOidcToken = { value, expiresAtMs };
+            }
         }
-        const expiresAtMs = (0, vercel_oidc_js_1.readVercelOidcTokenExpiry)(value, this.now().getTime());
-        if (expiresAtMs !== null) {
-            this.vercelOidcToken = { value, expiresAtMs };
+        catch {
+            // Token capture must not interrupt the customer's request handler.
         }
     }
     /**
@@ -490,7 +687,7 @@ class DevTuneAiTrafficClient {
             if (this.keyCredential) {
                 return this.keyCredential;
             }
-            this.sampleWarn("DevTune AI Traffic dropped events: the Vercel OIDC token expired before it could be used", { droppedEvents: batchEvents + this.queue.length });
+            this.sampleWarn("DevTune AI Traffic dropped events: the Vercel OIDC token expired before it could be used", { droppedEvents: batchEvents + this.queuedEventCount() });
             return "drop-queue";
         }
         const earlierFailure = failedExchanges.get(token.value);
@@ -499,7 +696,7 @@ class DevTuneAiTrafficClient {
                 return this.keyCredential;
             }
             this.sampleWarn("DevTune AI Traffic could not exchange the Vercel OIDC token", {
-                droppedEvents: batchEvents + this.queue.length,
+                droppedEvents: batchEvents + this.queuedEventCount(),
                 ...earlierFailure,
             });
             return "drop-queue";
@@ -539,6 +736,9 @@ class DevTuneAiTrafficClient {
         this.warnedMissingVercelOidcToken = true;
         this.logger?.warn("DevTune AI Traffic dropped events: projectId sends only from a Vercel deployment with OIDC enabled, and no ingestKey is set", { droppedEvents });
     }
+    queuedEventCount() {
+        return this.queue.length + this.referralQueue.length;
+    }
     resolveRetryDelayMs(retryAfterHeader, retryAttempts) {
         const retryAfterMs = parseRetryAfterMs(retryAfterHeader, this.now());
         const backoffMs = RETRY_BASE_DELAY_MS * 2 ** retryAttempts;
@@ -594,6 +794,69 @@ function readWebBotAuthSafely(request) {
         return null;
     }
 }
+/** A cheap substring test, so a `Referer` naming no registry host is never parsed. */
+function mentionsAnyHost(referer, hosts) {
+    for (const { hostname } of hosts) {
+        if (referer.includes(hostname)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** A URL, only when it parses and is `http:` or `https:`. */
+function parseHttpUrl(value) {
+    const url = value ? parseRequestUrl(value) : null;
+    return url && (url.protocol === "http:" || url.protocol === "https:") ? url : null;
+}
+/** The `Referer` cut to its origin, as DevTune's snippet keeps it. */
+function readReferrerOrigin(referer) {
+    const origin = parseHttpUrl(referer)?.origin;
+    return origin && origin.length <= MAX_EVENT_REFERRER_LENGTH ? origin : null;
+}
+/**
+ * The campaign parameters DevTune's referral and paid-click rules read, and
+ * nothing else from the query. A value DevTune would not accept is left out
+ * rather than truncated: an over-long medium is never a paid one.
+ */
+function readCampaign(url) {
+    const utmSource = readCampaignValue(url, "utm_source");
+    const utmMedium = readCampaignValue(url, "utm_medium");
+    const oppref = url.searchParams.has("oppref");
+    if (utmSource === null && utmMedium === null && !oppref) {
+        return null;
+    }
+    return {
+        ...(utmSource === null ? {} : { utm_source: utmSource }),
+        ...(utmMedium === null ? {} : { utm_medium: utmMedium }),
+        ...(oppref ? { oppref: true } : {}),
+    };
+}
+function readCampaignValue(url, name) {
+    const value = url.searchParams.get(name);
+    return value && value.length <= MAX_CAMPAIGN_VALUE_LENGTH ? value : null;
+}
+const CDN_HEADERS = ["cf-ray", "x-amz-cf-id", "fastly-client-ip", "fastly-ff", "fastly-ssl"];
+/**
+ * Whether a CDN forwarded the request: Cloudflare's `cf-ray`, CloudFront's
+ * `x-amz-cf-id`, or any `fastly-*` header where the header names can be
+ * listed. A cache that adds none of them goes undetected.
+ */
+function isBehindCdn(headers) {
+    try {
+        if (CDN_HEADERS.some((name) => headers.get(name) !== null)) {
+            return true;
+        }
+        for (const name of headers.keys?.() ?? []) {
+            if (name.toLowerCase().startsWith("fastly-")) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // A custom headers object must not throw into the customer's request path.
+    }
+    return false;
+}
 function scheduleBackground(promise, waitUntilContext) {
     const guardedPromise = promise.catch(() => undefined);
     if (waitUntilContext) {
@@ -603,7 +866,7 @@ function scheduleBackground(promise, waitUntilContext) {
     void guardedPromise;
 }
 function getWaitUntilContext(value) {
-    if (!isRecord(value)) {
+    if (!(0, registry_js_1.isRecord)(value)) {
         return undefined;
     }
     const waitUntil = value.waitUntil;
@@ -700,7 +963,7 @@ function classifyFailure(error) {
             ? { kind: error.kind, status: error.status }
             : { kind: error.kind };
     }
-    const name = isRecord(error) ? error.name : undefined;
+    const name = (0, registry_js_1.isRecord)(error) ? error.name : undefined;
     if (name === "TimeoutError") {
         return { kind: "timeout" };
     }
@@ -784,7 +1047,4 @@ function truncateString(value, maxLength) {
     }
     return value.slice(0, maxLength);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
 //# sourceMappingURL=client.js.map