Server middleware

Crawlers and agents never load your script. @vector5/middleware inspects the user agent and forwards non-human requests to /api/hit.

If you only install v5.js, your AI Traffic panel will be empty. GPTBot does not execute JavaScript. The middleware is the other half of Vector 5.

Why it exists

Client-side analytics is blind to training crawlers, retrieval bots, and most headless agents. @vector5/middleware runs inside your server, checks the UA, and fire-and-forgets a hit. It never awaits the request and never blocks your response.

Install

terminal

pnpm add @vector5/middleware

middleware.ts

import { vector5 } from '@vector5/middleware/next'

export const middleware = vector5({
  endpoint: 'https://analytics.example.com/api/hit',
  domain: 'example.com',
})

Behaviour

By default only non-human actors are recorded. The UA is matched against a crawler/bot/headless regex.
Pass `recordHumans: true` for sites without JavaScript.
Sends are keepalive fetch calls. Failures are swallowed — analytics must never 500 your app.
On Next.js, x-forwarded-for is forwarded for geo, then discarded by the API.

Options

Option	Type	Required	Notes
`endpoint`	`string`	yes	Full URL to `POST /api/hit`
`domain`	`string`	yes	Registered site hostname
`recordHumans`	`boolean`	no	Default `false`

Hit payload

POST /api/hit

{
  "domain": "example.com",
  "method": "GET",
  "path": "/docs/middleware",
  "status": 0,
  "bytes": 0,
  "ua": "GPTBot",
  "referer": "",
  "ip": "203.0.113.10"
}

The API classifies the UA as ai_crawler / ai_agent / bot, hashes the visitor, looks up country, and drops the IP. Status and bytes are optional — the Next adapter does not wait for the response, so status is often 0.