@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.

Install

pnpm add @devtune/ai-traffic

Set your project-scoped server-side ingest key:

DEVTUNE_AI_TRAFFIC_INGEST_KEY=dt_ingest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Next.js Proxy / Middleware

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.

// proxy.ts
import { createDevTuneAiTraffic } from "@devtune/ai-traffic";
import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";

const aiTraffic = createDevTuneAiTraffic({
  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);

  return response;
}

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:

export function proxy(request: NextRequest, event: NextFetchEvent) {
  const response = new Response("Forbidden", { status: 403 });

  aiTraffic.trackRequest(request, event, response.status);

  return response;
}

If you only need a minimal best-effort hook, the middleware helper is also available:

import { createDevTuneAiTrafficMiddleware } from "@devtune/ai-traffic";
import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";

const trackAiTraffic = createDevTuneAiTrafficMiddleware({
  ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
});

export function proxy(request: NextRequest, event: NextFetchEvent) {
  trackAiTraffic(request, event);

  return NextResponse.next();
}

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.

Status Capture

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.

Use the route wrapper where you own the handler response and need exact status capture:

// 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!,
  },
);

For known misses in middleware, mark them explicitly:

const trackAiTraffic = createDevTuneAiTrafficMiddleware({
  ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
  notFoundPathPatterns: [/^\/docs\/removed\//],
});

What Gets Sent

For matched AI bot requests only, the package sends:

• path
• url
• ua
• status when known
• ts

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.

Registry Cache

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.

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.

Vercel Pull Status

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.