@agenthoney/analytics 0.0.0-stage → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fifth Mind LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @agenthoney/analytics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```ts
+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>`.
+
+```ts
+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`](https://github.com/Fifth-Mind/agenthoney/blob/main/docs/design/collected-fields.md)
+
+## Licence
+
+MIT. See [`LICENSE`](./LICENSE).