@caprail-dev/analytics 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @caprail-dev/analytics
+
+Edge collector for [Caprail](https://caprail.dev) — see which AI agents (Claude
+Code, Codex, ChatGPT, Gemini, Perplexity, …) access your site, in real time.
+
+One install, framework adapters as subpath exports. The collector only classifies
+nothing locally and beacons each request to your Caprail ingest endpoint; the
+server re-classifies the `User-Agent` authoritatively.
+
+## Install
+
+```sh
+npm i @caprail-dev/analytics
+```
+
+Set `CAPRAIL_INGEST_URL` and `CAPRAIL_INGEST_KEY` (your site's `cap_live_…` key,
+from `/dashboard/sites`) in your environment, or pass them explicitly.
+
+## Next.js
+
+```ts
+// middleware.ts
+import { createCaprailMiddleware } from "@caprail-dev/analytics/next";
+
+export const middleware = createCaprailMiddleware(); // reads env, or pass { url, key }
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+Middleware runs *before* the response, so it cannot see the final `status` /
+`Content-Type` — the markdown/html grade falls back to path inference.
+
+## Cloudflare Worker
+
+```ts
+// worker.ts
+import { withCaprail } from "@caprail-dev/analytics/cloudflare";
+
+export default withCaprail({
+  async fetch(request) {
+    return fetch(request); // your origin
+  },
+});
+```
+
+The Worker wraps the real `Response`, so it reports the authoritative status,
+content-type, and latency.
+
+## Exports
+
+| Subpath        | Export                    |
+| -------------- | ------------------------- |
+| `.`            | `classify`, `collect`, `resolveConfig`, types |
+| `./next`       | `createCaprailMiddleware` |
+| `./cloudflare` | `withCaprail`             |
+
+> Adapters for TanStack Start and Node (Express/Hono) are planned.
+
+## Publishing
+
+`exports` currently points at TypeScript source so the Caprail monorepo can
+dogfood the package with no build step (`transpilePackages`). Before publishing
+to npm, run `bun run build` (emits `dist/`) and switch the `exports` map to the
+compiled `./dist/*.js` + `./dist/*.d.ts` entries.

package/dist/beacon.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The beacon — the framework-agnostic half of the collector. Builds the event
+ * payload and POSTs it to the Caprail ingest API. The server re-classifies the
+ * `userAgent` authoritatively, so the collector deliberately sends only raw
+ * request facts and never its own classification (which would be spoofable).
+ */
+/**
+ * A single collected request, matching the ingest API's accepted shape. Only
+ * `timestamp`/`method`/`path`/`status` are required; the rest are best-effort
+ * and depend on what the host framework can observe (e.g. middleware cannot see
+ * the final `status` / `contentType`; a Cloudflare Worker can).
+ */
+export type CaprailEvent = {
+    /** ISO-8601 event time (collector clock). */
+    timestamp: string;
+    method: string;
+    /** Pathname; the server strips any querystring defensively. */
+    path: string;
+    status: number;
+    latencyMs?: number;
+    userAgent?: string;
+    contentType?: string;
+    country?: string;
+    ip?: string;
+};
+/**
+ * POST a batch of events to the ingest endpoint. Fire-and-forget: uses
+ * `keepalive` so it survives the request lifecycle and swallows every error —
+ * collection must never surface to (or block) the end user. Pass the result to
+ * `ev.waitUntil(...)` / `ctx.waitUntil(...)` so the runtime keeps it alive.
+ */
+export declare function sendBeacon(url: string, key: string, events: CaprailEvent[]): Promise<void>;
+//# sourceMappingURL=beacon.d.ts.map

package/dist/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EAAE,GACrB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/beacon.js

@@ -0,0 +1,26 @@
+/**
+ * The beacon — the framework-agnostic half of the collector. Builds the event
+ * payload and POSTs it to the Caprail ingest API. The server re-classifies the
+ * `userAgent` authoritatively, so the collector deliberately sends only raw
+ * request facts and never its own classification (which would be spoofable).
+ */
+/**
+ * POST a batch of events to the ingest endpoint. Fire-and-forget: uses
+ * `keepalive` so it survives the request lifecycle and swallows every error —
+ * collection must never surface to (or block) the end user. Pass the result to
+ * `ev.waitUntil(...)` / `ctx.waitUntil(...)` so the runtime keeps it alive.
+ */
+export function sendBeacon(url, key, events) {
+    return fetch(url, {
+        method: "POST",
+        keepalive: true,
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${key}`,
+        },
+        body: JSON.stringify({ events }),
+    })
+        .then(() => undefined)
+        .catch(() => undefined);
+}
+//# sourceMappingURL=beacon.js.map

package/dist/beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.js","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,GAAW,EACX,MAAsB;IAEtB,OAAO,KAAK,CAAC,GAAG,EAAE;QAChB,MAAM,EAAE,MAAM;QACd,SAAS,EAAE,IAAI;QACf,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,aAAa,EAAE,UAAU,GAAG,EAAE;SAC/B;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACjC,CAAC;SACC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SACrB,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AAC5B,CAAC"}

package/dist/classify.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent classifier — the single source of truth shared by the Caprail Node
+ * ingest API and every edge collector adapter. Pure, dependency-free, and
+ * runtime-agnostic (no `db`, no Node-only APIs) so it runs unchanged in Node,
+ * the Edge runtime, and Cloudflare Workers.
+ */
+/**
+ * One of the `agent_type` values. Mirrors the `agent_type` pgEnum in the Caprail
+ * app schema (`src/server/db/schema.ts`) — keep the two lists in sync.
+ */
+export type AgentType = "crawler" | "fetcher" | "browser" | "search" | "human";
+export type Classification = {
+    /** e.g. "ClaudeBot"; null = human / unknown. */
+    name: string | null;
+    /** e.g. "Anthropic"; null = human / unknown. */
+    vendor: string | null;
+    type: AgentType;
+    isAgent: boolean;
+};
+/**
+ * Classify a request by its `User-Agent`. Matches known agent tokens as
+ * case-insensitive substrings, most-specific-first; anything unrecognised (or
+ * missing) is treated as `human`.
+ */
+export declare function classify(ua: string | null | undefined): Classification;
+//# sourceMappingURL=classify.d.ts.map

package/dist/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE/E,MAAM,MAAM,cAAc,GAAG;IAC3B,gDAAgD;IAChD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAgLF;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,CAgBtE"}

package/dist/classify.js

@@ -0,0 +1,187 @@
+/**
+ * Agent classifier — the single source of truth shared by the Caprail Node
+ * ingest API and every edge collector adapter. Pure, dependency-free, and
+ * runtime-agnostic (no `db`, no Node-only APIs) so it runs unchanged in Node,
+ * the Edge runtime, and Cloudflare Workers.
+ */
+/**
+ * Known agent tokens, **declared most-specific-first**. Matching walks this list
+ * in order and returns the first substring hit, so qualified tokens MUST precede
+ * their shorter relatives (e.g. `Claude-User` before `ClaudeBot`, `ChatGPT-User`
+ * before `ChatGPT Agent`, `meta-externalfetcher` before `meta-externalagent`,
+ * `Google-Extended` / `GoogleOther` before `Googlebot`). Preserve this ordering
+ * when editing. Canonical published tokens — refresh from knownagents.com /
+ * darkvisitors.com.
+ */
+const AGENTS = [
+    // Anthropic
+    {
+        token: "Claude-SearchBot",
+        name: "Claude-SearchBot",
+        vendor: "Anthropic",
+        type: "search",
+    },
+    {
+        token: "Claude-User",
+        name: "Claude-User",
+        vendor: "Anthropic",
+        type: "fetcher",
+    },
+    {
+        token: "Claude-Web",
+        name: "Claude-Web",
+        vendor: "Anthropic",
+        type: "fetcher",
+    },
+    {
+        token: "ClaudeBot",
+        name: "ClaudeBot",
+        vendor: "Anthropic",
+        type: "crawler",
+    },
+    {
+        token: "anthropic-ai",
+        name: "anthropic-ai",
+        vendor: "Anthropic",
+        type: "crawler",
+    },
+    // Claude Code has no reliable UA token (a collector header is preferred); keep
+    // this as a best-effort fallback.
+    {
+        token: "claude-code",
+        name: "Claude Code",
+        vendor: "Anthropic",
+        type: "fetcher",
+    },
+    // OpenAI
+    {
+        token: "ChatGPT-User",
+        name: "ChatGPT-User",
+        vendor: "OpenAI",
+        type: "fetcher",
+    },
+    {
+        token: "OAI-SearchBot",
+        name: "OAI-SearchBot",
+        vendor: "OpenAI",
+        type: "search",
+    },
+    {
+        token: "ChatGPT Agent",
+        name: "ChatGPT Agent",
+        vendor: "OpenAI",
+        type: "browser",
+    },
+    { token: "GPTBot", name: "GPTBot", vendor: "OpenAI", type: "crawler" },
+    { token: "Codex", name: "Codex", vendor: "OpenAI", type: "fetcher" },
+    // Google
+    {
+        token: "Gemini-Deep-Research",
+        name: "Gemini-Deep-Research",
+        vendor: "Google",
+        type: "fetcher",
+    },
+    {
+        token: "Google-NotebookLM",
+        name: "Google-NotebookLM",
+        vendor: "Google",
+        type: "fetcher",
+    },
+    {
+        token: "Google-Extended",
+        name: "Google-Extended",
+        vendor: "Google",
+        type: "crawler",
+    },
+    {
+        token: "GoogleOther",
+        name: "GoogleOther",
+        vendor: "Google",
+        type: "crawler",
+    },
+    { token: "Googlebot", name: "Googlebot", vendor: "Google", type: "search" },
+    // Perplexity
+    {
+        token: "Perplexity-User",
+        name: "Perplexity-User",
+        vendor: "Perplexity",
+        type: "fetcher",
+    },
+    {
+        token: "PerplexityBot",
+        name: "PerplexityBot",
+        vendor: "Perplexity",
+        type: "search",
+    },
+    // Meta
+    {
+        token: "meta-externalfetcher",
+        name: "meta-externalfetcher",
+        vendor: "Meta",
+        type: "fetcher",
+    },
+    {
+        token: "meta-externalagent",
+        name: "meta-externalagent",
+        vendor: "Meta",
+        type: "crawler",
+    },
+    // Other
+    {
+        token: "Bytespider",
+        name: "Bytespider",
+        vendor: "ByteDance",
+        type: "crawler",
+    },
+    { token: "CCBot", name: "CCBot", vendor: "Common Crawl", type: "crawler" },
+    { token: "Amazonbot", name: "Amazonbot", vendor: "Amazon", type: "crawler" },
+    {
+        token: "Applebot-Extended",
+        name: "Applebot-Extended",
+        vendor: "Apple",
+        type: "crawler",
+    },
+    { token: "cohere-ai", name: "cohere-ai", vendor: "Cohere", type: "crawler" },
+    { token: "Diffbot", name: "Diffbot", vendor: "Diffbot", type: "crawler" },
+    {
+        token: "MistralAI-User",
+        name: "MistralAI-User",
+        vendor: "Mistral",
+        type: "fetcher",
+    },
+    {
+        token: "DuckAssistBot",
+        name: "DuckAssistBot",
+        vendor: "DuckDuckGo",
+        type: "fetcher",
+    },
+    { token: "Bingbot", name: "Bingbot", vendor: "Microsoft", type: "search" },
+];
+const HUMAN = {
+    name: null,
+    vendor: null,
+    type: "human",
+    isAgent: false,
+};
+/**
+ * Classify a request by its `User-Agent`. Matches known agent tokens as
+ * case-insensitive substrings, most-specific-first; anything unrecognised (or
+ * missing) is treated as `human`.
+ */
+export function classify(ua) {
+    if (!ua)
+        return HUMAN;
+    const haystack = ua.toLowerCase();
+    for (const agent of AGENTS) {
+        if (haystack.includes(agent.token.toLowerCase())) {
+            return {
+                name: agent.name,
+                vendor: agent.vendor,
+                type: agent.type,
+                isAgent: true,
+            };
+        }
+    }
+    return HUMAN;
+}
+//# sourceMappingURL=classify.js.map

package/dist/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH;;;;;;;;GAQG;AACH,MAAM,MAAM,GAAiB;IAC3B,YAAY;IACZ;QACE,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,kBAAkB;QACxB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,QAAQ;KACf;IACD;QACE,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,SAAS;KAChB;IACD,+EAA+E;IAC/E,kCAAkC;IAClC;QACE,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,SAAS;KAChB;IAED,SAAS;IACT;QACE,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,QAAQ;KACf;IACD;QACE,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,SAAS;KAChB;IACD,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;IACtE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;IAEpE,SAAS;IACT;QACE,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,SAAS;KAChB;IACD,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;IAE3E,aAAa;IACb;QACE,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,QAAQ;KACf;IAED,OAAO;IACP;QACE,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,SAAS;KAChB;IAED,QAAQ;IACR;QACE,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,SAAS;KAChB;IACD,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE;IAC1E,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;IAC5E;QACE,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE,OAAO;QACf,IAAI,EAAE,SAAS;KAChB;IACD,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;IAC5E,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;IACzE;QACE,KAAK,EAAE,gBAAgB;QACvB,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,SAAS;QACjB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,SAAS;KAChB;IACD,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE;CAC3E,CAAC;AAEF,MAAM,KAAK,GAAmB;IAC5B,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,KAAK;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,EAA6B;IACpD,IAAI,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAEtB,MAAM,QAAQ,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACjD,OAAO;gBACL,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/cloudflare.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cloudflare Worker adapter — `"@caprail-dev/analytics/cloudflare"`.
+ *
+ * `withCaprail(handler)` wraps a Worker `fetch` handler. Because it sees the
+ * real `Response`, it reports the **authoritative** `status` / `Content-Type`
+ * (which the Markdown✓/HTML✗ grade is derived from) and measures `latencyMs` —
+ * none of which Next.js middleware can observe.
+ *
+ *   // worker.ts
+ *   import { withCaprail } from "@caprail-dev/analytics/cloudflare";
+ *   export default withCaprail({
+ *     async fetch(request) { return fetch(request); },
+ *   });
+ *
+ * Config resolves from the Worker `env` binding (`CAPRAIL_INGEST_URL` /
+ * `CAPRAIL_INGEST_KEY`); when either is missing it is a transparent no-op.
+ */
+/** Minimal structural types so the adapter needs no `@cloudflare/workers-types`. */
+type WaitUntilContext = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+type WorkerEnv = Record<string, string | undefined>;
+type FetchHandler = {
+    fetch(request: Request, env: WorkerEnv, ctx: WaitUntilContext): Response | Promise<Response>;
+};
+/** Wrap a Worker `fetch` handler so every request is beaconed to Caprail. */
+export declare function withCaprail(handler: FetchHandler): FetchHandler;
+export {};
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,oFAAoF;AACpF,KAAK,gBAAgB,GAAG;IAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAAE,CAAC;AACvE,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEpD,KAAK,YAAY,GAAG;IAClB,KAAK,CACH,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,gBAAgB,GACpB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACjC,CAAC;AAKF,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CA4B/D"}

package/dist/cloudflare.js

@@ -0,0 +1,42 @@
+/**
+ * Cloudflare Worker adapter — `"@caprail-dev/analytics/cloudflare"`.
+ *
+ * `withCaprail(handler)` wraps a Worker `fetch` handler. Because it sees the
+ * real `Response`, it reports the **authoritative** `status` / `Content-Type`
+ * (which the Markdown✓/HTML✗ grade is derived from) and measures `latencyMs` —
+ * none of which Next.js middleware can observe.
+ *
+ *   // worker.ts
+ *   import { withCaprail } from "@caprail-dev/analytics/cloudflare";
+ *   export default withCaprail({
+ *     async fetch(request) { return fetch(request); },
+ *   });
+ *
+ * Config resolves from the Worker `env` binding (`CAPRAIL_INGEST_URL` /
+ * `CAPRAIL_INGEST_KEY`); when either is missing it is a transparent no-op.
+ */
+import { collect, resolveConfig } from "./core";
+/** Wrap a Worker `fetch` handler so every request is beaconed to Caprail. */
+export function withCaprail(handler) {
+    return {
+        async fetch(request, env, ctx) {
+            const start = Date.now();
+            const res = await handler.fetch(request, env, ctx);
+            const config = resolveConfig(undefined, env);
+            if (config) {
+                ctx.waitUntil(collect({
+                    timestamp: new Date().toISOString(),
+                    method: request.method,
+                    path: new URL(request.url).pathname,
+                    status: res.status,
+                    contentType: res.headers.get("content-type") ?? undefined,
+                    userAgent: request.headers.get("user-agent") ?? undefined,
+                    country: request.cf?.country,
+                    latencyMs: Date.now() - start,
+                }, config));
+            }
+            return res;
+        },
+    };
+}
+//# sourceMappingURL=cloudflare.js.map

package/dist/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAiBhD,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAgB,EAAE,GAAc,EAAE,GAAqB;YACjE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;YAEnD,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YAC7C,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,CAAC,SAAS,CACX,OAAO,CACL;oBACE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACnC,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ;oBACnC,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,SAAS;oBACzD,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS;oBACzD,OAAO,EAAG,OAAyB,CAAC,EAAE,EAAE,OAAO;oBAC/C,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;iBAC9B,EACD,MAAM,CACP,CACF,CAAC;YACJ,CAAC;YAED,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared core — the package's `.` entry point. Resolves configuration (explicit
+ * options ▸ environment) and exposes `collect()`, the single call every adapter
+ * funnels through. Also re-exports `classify` as the single source of truth so
+ * the Caprail ingest API can drop its duplicate copy.
+ */
+import { type CaprailEvent } from "./beacon";
+export { classify } from "./classify";
+export type { AgentType, Classification } from "./classify";
+export type { CaprailEvent } from "./beacon";
+/** Explicit collector config; either field falls back to the matching env var. */
+export type CaprailConfig = {
+    /** Ingest endpoint URL. Falls back to `CAPRAIL_INGEST_URL`. */
+    url?: string;
+    /** Site ingest key (`cap_live_…`). Falls back to `CAPRAIL_INGEST_KEY`. */
+    key?: string;
+};
+/** Fully-resolved config, or `null` when either value is missing (→ no-op). */
+export type ResolvedConfig = {
+    url: string;
+    key: string;
+};
+/**
+ * Merge explicit options over an env source, returning `null` unless both `url`
+ * and `key` are present. `envSource` lets non-`process.env` runtimes (Cloudflare
+ * Workers, which pass `env` as a handler argument) supply their bindings; it
+ * defaults to `process.env` where available.
+ */
+export declare function resolveConfig(options?: CaprailConfig, envSource?: Record<string, string | undefined>): ResolvedConfig | null;
+/**
+ * Beacon a single collected event. Thin wrapper over `sendBeacon` that every
+ * adapter shares; the returned promise should be handed to the runtime's
+ * keep-alive hook (`waitUntil`).
+ */
+export declare function collect(event: CaprailEvent, config: ResolvedConfig): Promise<void>;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,UAAU,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG;IAC1B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,CAAC,EAAE,aAAa,EACvB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC7C,cAAc,GAAG,IAAI,CAMvB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/core.js

@@ -0,0 +1,29 @@
+/**
+ * Shared core — the package's `.` entry point. Resolves configuration (explicit
+ * options ▸ environment) and exposes `collect()`, the single call every adapter
+ * funnels through. Also re-exports `classify` as the single source of truth so
+ * the Caprail ingest API can drop its duplicate copy.
+ */
+import { sendBeacon } from "./beacon";
+export { classify } from "./classify";
+/**
+ * Merge explicit options over an env source, returning `null` unless both `url`
+ * and `key` are present. `envSource` lets non-`process.env` runtimes (Cloudflare
+ * Workers, which pass `env` as a handler argument) supply their bindings; it
+ * defaults to `process.env` where available.
+ */
+export function resolveConfig(options, envSource) {
+    const env = envSource ?? (typeof process !== "undefined" ? process.env : undefined);
+    const url = options?.url ?? env?.CAPRAIL_INGEST_URL;
+    const key = options?.key ?? env?.CAPRAIL_INGEST_KEY;
+    return url && key ? { url, key } : null;
+}
+/**
+ * Beacon a single collected event. Thin wrapper over `sendBeacon` that every
+ * adapter shares; the returned promise should be handed to the runtime's
+ * keep-alive hook (`waitUntil`).
+ */
+export function collect(event, config) {
+    return sendBeacon(config.url, config.key, [event]);
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAqB,UAAU,EAAE,MAAM,UAAU,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAetC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAuB,EACvB,SAA8C;IAE9C,MAAM,GAAG,GACP,SAAS,IAAI,CAAC,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC;IACpD,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC;IACpD,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CACrB,KAAmB,EACnB,MAAsB;IAEtB,OAAO,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/next.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Next.js adapter — `"@caprail-dev/analytics/next"`.
+ *
+ * `createCaprailMiddleware()` returns a `middleware` function for `middleware.ts`
+ * that classifies nothing locally and beacons each request via `ev.waitUntil`,
+ * so it never blocks (or fails) the response.
+ *
+ *   // middleware.ts
+ *   import { createCaprailMiddleware } from "@caprail-dev/analytics/next";
+ *   export const middleware = createCaprailMiddleware();   // reads env
+ *   export const config = {
+ *     matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+ *   };
+ *
+ * Limitation: middleware runs *before* the response, so it cannot observe the
+ * final `status` / `Content-Type` (true on both the Edge and Node runtimes).
+ * The Cloudflare adapter is authoritative for those — see `./cloudflare`.
+ */
+import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
+import { type CaprailConfig } from "./core";
+/**
+ * Build a Caprail collection middleware. Config resolves explicit `options` over
+ * `CAPRAIL_INGEST_URL` / `CAPRAIL_INGEST_KEY`; when neither source yields both a
+ * URL and key the middleware is a transparent no-op.
+ */
+export declare function createCaprailMiddleware(options?: CaprailConfig): (req: NextRequest, ev: NextFetchEvent) => NextResponse<unknown>;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,aAAa,EAA0B,MAAM,QAAQ,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,aAAa,IAClC,KAAK,WAAW,EAAE,IAAI,cAAc,2BAsBhE"}

package/dist/next.js

@@ -0,0 +1,43 @@
+/**
+ * Next.js adapter — `"@caprail-dev/analytics/next"`.
+ *
+ * `createCaprailMiddleware()` returns a `middleware` function for `middleware.ts`
+ * that classifies nothing locally and beacons each request via `ev.waitUntil`,
+ * so it never blocks (or fails) the response.
+ *
+ *   // middleware.ts
+ *   import { createCaprailMiddleware } from "@caprail-dev/analytics/next";
+ *   export const middleware = createCaprailMiddleware();   // reads env
+ *   export const config = {
+ *     matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+ *   };
+ *
+ * Limitation: middleware runs *before* the response, so it cannot observe the
+ * final `status` / `Content-Type` (true on both the Edge and Node runtimes).
+ * The Cloudflare adapter is authoritative for those — see `./cloudflare`.
+ */
+import { NextResponse, } from "next/server";
+import { collect, resolveConfig } from "./core";
+/**
+ * Build a Caprail collection middleware. Config resolves explicit `options` over
+ * `CAPRAIL_INGEST_URL` / `CAPRAIL_INGEST_KEY`; when neither source yields both a
+ * URL and key the middleware is a transparent no-op.
+ */
+export function createCaprailMiddleware(options) {
+    return function middleware(req, ev) {
+        const config = resolveConfig(options);
+        if (config) {
+            const ua = req.headers.get("user-agent");
+            ev.waitUntil(collect({
+                timestamp: new Date().toISOString(),
+                method: req.method,
+                path: req.nextUrl.pathname,
+                status: 200, // pre-response; the real status is unknown here.
+                userAgent: ua ?? undefined,
+                country: req.headers.get("x-vercel-ip-country") ?? undefined,
+            }, config));
+        }
+        return NextResponse.next();
+    };
+}
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,YAAY,GAGb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAsB,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEpE;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAuB;IAC7D,OAAO,SAAS,UAAU,CAAC,GAAgB,EAAE,EAAkB;QAC7D,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QAEtC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACzC,EAAE,CAAC,SAAS,CACV,OAAO,CACL;gBACE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ;gBAC1B,MAAM,EAAE,GAAG,EAAE,iDAAiD;gBAC9D,SAAS,EAAE,EAAE,IAAI,SAAS;gBAC1B,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,SAAS;aAC7D,EACD,MAAM,CACP,CACF,CAAC;QACJ,CAAC;QAED,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@caprail-dev/analytics",
+  "version": "0.1.0",
+  "description": "Edge collector for Caprail — see which AI agents access your site.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/core.js",
+  "types": "./dist/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "default": "./dist/cloudflare.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}