@agenthoney/analytics

Analytics for the agentic web — and the other half nobody ships: serving those agents a clean markdown twin from the same middleware.

One app.use. It observes every request at the server boundary, so it counts the clients that never run JavaScript, and it can serve a markdown representation of a page to anything that asks for one.

import { agenthoney } from "@agenthoney/analytics/express";

app.use(agenthoney());

Nothing loads in a visitor's browser. No client script, no cookies.

Installing with a coding agent

Point it at https://agenthoney.ai/install.md — the same guide this package serves from your own middleware. It is written for an agent rather than a person: imperative, naming the failure modes, and telling the agent to stop rather than guess at a credential.

The three properties worth knowing before you install

It never blocks and never fails your responses. record() is synchronous and returns void, every adapter entry point wears one safe() wrapper, and nothing awaits the network on the request path. The serve path fails open to content: any throw, timeout or manifest miss falls through to your own handler with the response unchanged. Each adapter has a test asserting byte-identical output with and without the middleware — including with a collector injected to throw on every call.

The response is inspected, never consumed. res is a single-read stream, and monkey-patching write/end to observe a body adds latency, adds memory, and can corrupt what you send. This reads what is already in the headers.

⚠️ The markdown twin is gated on Accept, never on identity. A crawler sending Accept: */* receives exactly what a browser receives. Serving different content by User-Agent is cloaking, it forces Vary: User-Agent (which disables shared caching), and a User-Agent is a claim rather than proof.

⚠️ Look at your routes before you go live

The path is sent as it arrives. The query string is dropped before anything parses it and the Referer is reduced to an origin — but plenty of sites put secrets in the path: /reveal/<token>, /join/<code>, /confirm/<ticket>.

app.use(agenthoney({
  routeTemplate: (path) => path
    .replace(/\/\d+(?=\/|$)/g, "/:id")
    .replace(/^\/(reveal|join|confirm)\/[^/]+/, "/$1/:token"),
  redactPatterns: [/^tok_[A-Za-z0-9]{16,}$/],
  isInternal: (req) => req.path.startsWith("/_health"),
}));

A default backstop redacts segments that look like credentials, and records that it did. It cannot catch a short token and it does not know which of your ids are sensitive. Only your routes do. redactHighEntropyPaths: false turns the backstop off; your own redactPatterns always apply. Never redact by length alone: /^[A-Za-z0-9_-]{20,}$/ matches every readable slug, and those are the pages agents read.

⚠️ The key is a server credential

AGENTHONEY_SERVER_KEY writes events for one site — the site it was minted for, which the server resolves from the credential itself. It must never reach a browser. Every export declares "browser": null, and the package refuses to start if it finds the key under NEXT_PUBLIC_, VITE_, PUBLIC_ or REACT_APP_ — those prefixes inline a value into client JavaScript, which publishes the key to everyone who loads the page.

Zero runtime dependencies

Deliberately, and enforced: a build gate fails if dependencies is non-empty or a bare import survives into dist/. It holds a credential and runs inside other people's request paths; its supply chain is its own.

Documentation

• Install guide, for agents: https://agenthoney.ai/install.md
• What is collected, generated from the wire schema and kept honest by a test: collected-fields.md

Licence

MIT. See LICENSE.