@iorg1/trackking-next 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iorg1
+
+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

@@ -0,0 +1,203 @@
+# @iorg1/trackking-next
+
+Cookieless, server-side page-view tracking for Next.js.
+
+`@iorg1/trackking-next` is a tiny Next.js **middleware** that beacons each page navigation to
+a Trackking collector over HTTPS. There is
+**no cookie**, no client-side script, and no consent banner machinery — the
+middleware runs on the server (Edge runtime), reads the request headers, and
+fires a fire-and-forget POST. Because it observes the document request, it also
+sees **bots and AI crawlers** (Googlebot, GPTBot, ClaudeBot, PerplexityBot) that
+JavaScript-based analytics never record.
+
+## Install
+
+```bash
+npm install @iorg1/trackking-next
+```
+
+## Configure
+
+Set two environment variables in your Next.js app:
+
+```bash
+TRACKKING_ENDPOINT=https://collector.example.com/collect
+TRACKKING_API_KEY=your_site_api_key
+```
+
+Optional:
+
+```bash
+# Reverse proxies in front of your app — trust the right client IP (see Options).
+TRACKKING_TRUSTED_PROXY_HOPS=1
+# Enable the first-party client-event route (see "First-party client events").
+TRACKKING_EVENT_ROUTE=/data/:event
+# Collector event endpoint; defaults to TRACKKING_ENDPOINT with /collect → /event.
+TRACKKING_EVENT_ENDPOINT=https://collector.example.com/event
+```
+
+## Use
+
+### The whole middleware (simplest)
+
+```ts
+// middleware.ts
+import { createTrackingMiddleware } from "@iorg1/trackking-next";
+
+export const middleware = createTrackingMiddleware();
+
+export const config = {
+  // Track real page navigations; skip Next internals, the API, and static files.
+  matcher: ["/", "/((?!_next/|api/|.*\\..*).*)"],
+};
+```
+
+### Inside an existing middleware
+
+Already have a `middleware.ts` (locale negotiation, auth, …)? Call `track()` and
+return your own response:
+
+```ts
+import { NextResponse, type NextRequest, type NextFetchEvent } from "next/server";
+import { track } from "@iorg1/trackking-next";
+
+export function middleware(req: NextRequest, event: NextFetchEvent) {
+  track(req, event); // fire-and-forget, never throws
+  // ...your existing logic...
+  return NextResponse.next();
+}
+```
+
+### First-party client events
+
+Page-view tracking is fully server-side, but sometimes you want to record a
+**client-triggered event** — a signup click, a preview generated, a "real
+browser rendered this" ping. Instead of beaconing the collector's origin from
+the browser (blocked by many ad/tracker blockers, and needing CORS), expose a
+**same-origin** route and let the middleware forward the event server-side. Your
+API key never reaches the browser.
+
+Set `eventRoute` (or `TRACKKING_EVENT_ROUTE`) and add the route to your matcher.
+When a request matches, `handleEvent` records a named event — the captured
+segment is the event name — and answers the client `200 {}`; when it doesn't, it
+returns `null` so you fall through to normal tracking:
+
+```ts
+import { NextResponse, type NextRequest, type NextFetchEvent } from "next/server";
+import { track, handleEvent } from "@iorg1/trackking-next";
+
+export async function middleware(req: NextRequest, event: NextFetchEvent) {
+  const res = await handleEvent(req, event, { eventRoute: "/data/:event" });
+  if (res) return res; // it was a /data/<event> beacon → 200 {}
+
+  track(req, event);
+  return NextResponse.next();
+}
+
+export const config = {
+  // Add the event route to the matcher so the middleware runs for it.
+  matcher: ["/", "/data/:path*", "/((?!_next/|api/|.*\\..*).*)"],
+};
+```
+
+`createTrackingMiddleware()` does this for you automatically when `eventRoute` /
+`TRACKKING_EVENT_ROUTE` is set — just remember to add the route to the matcher.
+
+From the browser, POST to the route with an optional `{ path?, props? }` body:
+
+```ts
+navigator.sendBeacon(
+  "/data/signup",
+  new Blob([JSON.stringify({ props: { plan: "pro" } })], { type: "application/json" }),
+);
+```
+
+The collector records `{ name: "signup", path, props }` (props are re-sanitized
+server-side). Route templates support `:name` (one path segment) and `*` (the
+rest of the path). For full control, pass `resolveEvent: (req) => string | null`
+instead of `eventRoute` — return the event name, or `null` to pass through.
+
+## Options
+
+```ts
+createTrackingMiddleware({
+  endpoint: process.env.TRACKKING_ENDPOINT, // default
+  apiKey: process.env.TRACKKING_API_KEY,    // default
+  shouldTrack: (req) => !req.nextUrl.pathname.startsWith("/admin"),
+  getClientIp: (req) => req.headers.get("cf-connecting-ip"),
+  trustedProxyHops: 1,                       // trust the right x-forwarded-for entry (see below)
+  eventRoute: "/data/:event",                // first-party client-event route (see above)
+  resolveEvent: (req) => …,                  // …or fully custom event extraction (overrides eventRoute)
+  eventEndpoint: process.env.TRACKKING_EVENT_ENDPOINT,
+  debug: process.env.NODE_ENV !== "production", // verbose logging (see below)
+});
+```
+
+The middleware automatically skips non-`GET` requests and Next.js prefetches
+(the event route is exempt — it handles the beacon method you send).
+
+### `trustedProxyHops`
+
+`x-forwarded-for` is appended left→right as a request passes through proxies, and
+the **leftmost entry is client-controlled** (spoofable). This option is the
+number of reverse proxies you run in front of the app, so the middleware trusts
+the value *your* proxy appended:
+
+- `0` (default) — use the leftmost entry. Correct only on a platform that
+  overwrites XFF for you (e.g. Vercel, Cloudflare).
+- `1+` — use the entry that many hops from the right. Behind your own
+  Caddy/nginx/Traefik, set this (usually `1`) so a spoofed leftmost entry can't
+  poison the visitor hash or geo/ASN lookup.
+
+Falls back to `TRACKKING_TRUSTED_PROXY_HOPS`. Ignored when `getClientIp` is set.
+
+## Debugging
+
+Tracking is intentionally silent — it never throws and, by default, never logs,
+so a misconfiguration (wrong endpoint, missing key, an unexpected `4xx`) looks
+like "nothing happens." To see what it's doing, set `TRACKKING_DEBUG`:
+
+```bash
+TRACKKING_DEBUG=1   # any truthy value; "0" / "false" / "" disable it
+```
+
+(or pass `debug: true` in the config, which overrides the env var). For each
+request the middleware then logs to the console via `console.debug`, prefixed
+with `[trackking]`:
+
+- the resolved **config** — endpoint, a masked API key (first 6 chars + length,
+  never the full secret), and which config keys you passed;
+- the **decision** — tracked, or skipped with the reason (not configured,
+  non-`GET`, prefetch, or `shouldTrack()` returned false);
+- the **event payload** that gets posted; and
+- the collector's **response** — `POST <endpoint> → <status> <statusText>`, plus
+  the response body on a non-2xx, or the error if the request threw.
+
+```
+[trackking] GET /pricing { endpoint: 'https://…/collect', apiKey: 'tk_abc…(35 chars)', configKeys: [] }
+[trackking] tracking event: { path: '/pricing', host: 'example.com', referrer: null, userAgent: '…', ip: '203.0.113.10', headers: { … } }
+[trackking] POST https://…/collect → 204 No Content (/pricing)
+```
+
+Leave it unset in production: it logs request metadata (path, IP, user-agent) to
+your server logs.
+
+## What gets sent
+
+**Page views** — a single JSON object: `{ path, host, referrer, userAgent, ip,
+headers }`. The collector hashes `ip` into a daily-rotating visitor id **and
+discards it** — the raw IP is never stored. The referrer is truncated to its
+host. `headers` is a small bag of low-entropy request headers (`Accept-Language`,
+`Accept`, the `Sec-Fetch-*` fetch-metadata set, and `Sec-CH-UA*` client hints)
+that help the collector tell real browsers from bots — it is **not** a device
+fingerprint, and no cookies or client identifiers are involved.
+
+**Events** (if you use the event route) — `{ name, path, props }`, carrying no
+visitor identity. `props` is an optional small, flat bag of non-PII metadata,
+re-sanitized by the collector.
+
+No personal identifiers are persisted.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,269 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildEvent: () => buildEvent,
+  createTrackingMiddleware: () => createTrackingMiddleware,
+  deriveEventEndpoint: () => deriveEventEndpoint,
+  getClientIp: () => getClientIp,
+  handleEvent: () => handleEvent,
+  matchEventRoute: () => matchEventRoute,
+  resolveEventName: () => resolveEventName,
+  track: () => track
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/middleware.ts
+var import_server = require("next/server");
+
+// src/forwarded.ts
+function clientIpFromForwardedFor(xff, trustedProxyHops2 = 0) {
+  if (!xff) return null;
+  const parts = xff.split(",").map((p) => p.trim()).filter(Boolean);
+  if (parts.length === 0) return null;
+  if (trustedProxyHops2 <= 0) return parts[0] ?? null;
+  const idx = Math.max(0, parts.length - trustedProxyHops2);
+  return parts[idx] ?? null;
+}
+
+// src/event-route.ts
+function eventRouteRegex(template) {
+  const source = template.split("/").map((seg) => {
+    if (seg.startsWith(":")) return "([^/]+)";
+    if (seg === "*") return "(.+)";
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("/");
+  return new RegExp(`^${source}$`);
+}
+function matchEventRoute(pathname, template) {
+  if (!template) return null;
+  const match = eventRouteRegex(template).exec(pathname);
+  if (!match) return null;
+  const captured = match[1] ?? pathname.split("/").filter(Boolean).pop() ?? "";
+  try {
+    return decodeURIComponent(captured);
+  } catch {
+    return captured;
+  }
+}
+function deriveEventEndpoint(base) {
+  if (!base) return void 0;
+  return base.replace(/\/collect\/?$/, "/event");
+}
+function parseEventBody(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const b = body;
+  const out = {};
+  if (typeof b.path === "string") out.path = b.path;
+  if (b.props && typeof b.props === "object" && !Array.isArray(b.props)) {
+    out.props = b.props;
+  }
+  return out;
+}
+
+// src/middleware.ts
+function trustedProxyHops(config) {
+  if (typeof config.trustedProxyHops === "number") return config.trustedProxyHops;
+  const raw = process.env.TRACKKING_TRUSTED_PROXY_HOPS;
+  const n = raw ? Number.parseInt(raw, 10) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function envDebug() {
+  const v = process.env.TRACKKING_DEBUG;
+  return v != null && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+function isDebug(config) {
+  return config.debug ?? envDebug();
+}
+function log(...args) {
+  console.debug("[trackking]", ...args);
+}
+function maskKey(key) {
+  if (!key) return "(unset)";
+  if (key.length <= 8) return "********";
+  return `${key.slice(0, 6)}\u2026(${key.length} chars)`;
+}
+function getClientIp(req, hops = 0) {
+  const xff = clientIpFromForwardedFor(req.headers.get("x-forwarded-for"), hops);
+  if (xff) return xff;
+  const real = req.headers.get("x-real-ip");
+  if (real) return real.trim();
+  const ip = req.ip;
+  return ip ?? null;
+}
+function isPrefetch(req) {
+  if (req.headers.get("next-router-prefetch")) return true;
+  const purpose = req.headers.get("purpose") ?? req.headers.get("x-purpose");
+  if (purpose && purpose.toLowerCase() === "prefetch") return true;
+  const secPurpose = req.headers.get("sec-purpose");
+  if (secPurpose && secPurpose.toLowerCase().includes("prefetch")) return true;
+  return false;
+}
+function headerSignals(req) {
+  const h = req.headers;
+  return {
+    acceptLanguage: h.get("accept-language"),
+    accept: h.get("accept"),
+    secFetchSite: h.get("sec-fetch-site"),
+    secFetchMode: h.get("sec-fetch-mode"),
+    secFetchDest: h.get("sec-fetch-dest"),
+    secFetchUser: h.get("sec-fetch-user"),
+    secChUa: h.get("sec-ch-ua"),
+    secChUaMobile: h.get("sec-ch-ua-mobile"),
+    secChUaPlatform: h.get("sec-ch-ua-platform"),
+    upgradeInsecureRequests: h.get("upgrade-insecure-requests")
+  };
+}
+function buildEvent(req, config = {}) {
+  const ipFn = config.getClientIp ?? ((r) => getClientIp(r, trustedProxyHops(config)));
+  return {
+    path: req.nextUrl.pathname,
+    host: req.nextUrl.host || req.headers.get("host"),
+    referrer: req.headers.get("referer"),
+    userAgent: req.headers.get("user-agent"),
+    ip: ipFn(req),
+    headers: headerSignals(req)
+  };
+}
+async function sendEvent(event, endpoint, apiKey, debug) {
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify(event),
+      // Survive a terminating edge runtime tearing the request down.
+      keepalive: true
+    });
+    if (debug) {
+      log(`POST ${endpoint} \u2192 ${res.status} ${res.statusText} (${event.path})`);
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        if (body) log("response body:", body.slice(0, 500));
+      }
+    }
+  } catch (err) {
+    if (debug) log("request failed:", err);
+  }
+}
+function track(req, event, config = {}) {
+  const endpoint = config.endpoint ?? process.env.TRACKKING_ENDPOINT;
+  const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
+  const debug = isDebug(config);
+  if (debug) {
+    log(`${req.method} ${req.nextUrl.pathname}`, {
+      endpoint: endpoint ?? "(unset)",
+      apiKey: maskKey(apiKey),
+      configKeys: Object.keys(config)
+    });
+  }
+  if (!endpoint || !apiKey) {
+    if (debug) log("skip: not configured (endpoint and/or apiKey missing)");
+    return;
+  }
+  if (req.method !== "GET") {
+    if (debug) log(`skip: method ${req.method} is not GET`);
+    return;
+  }
+  if (isPrefetch(req)) {
+    if (debug) log("skip: prefetch request");
+    return;
+  }
+  if (config.shouldTrack && !config.shouldTrack(req)) {
+    if (debug) log("skip: shouldTrack() returned false");
+    return;
+  }
+  const payload = buildEvent(req, config);
+  if (debug) log("tracking event:", payload);
+  event.waitUntil(sendEvent(payload, endpoint, apiKey, debug));
+}
+function eventEndpointFor(config) {
+  return config.eventEndpoint ?? process.env.TRACKKING_EVENT_ENDPOINT ?? deriveEventEndpoint(config.endpoint ?? process.env.TRACKKING_ENDPOINT);
+}
+function resolveEventName(req, config = {}) {
+  if (config.resolveEvent) return config.resolveEvent(req);
+  const template = config.eventRoute ?? process.env.TRACKKING_EVENT_ROUTE;
+  if (!template) return null;
+  return matchEventRoute(req.nextUrl.pathname, template);
+}
+async function sendClientEvent(payload, endpoint, apiKey, debug) {
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+    if (debug) log(`event POST ${endpoint} \u2192 ${res.status} (${payload.name})`);
+  } catch (err) {
+    if (debug) log("event request failed:", err);
+  }
+}
+async function handleEvent(req, event, config = {}) {
+  const name = resolveEventName(req, config);
+  if (name == null || name === "") return null;
+  const debug = isDebug(config);
+  let body = null;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    body = await req.json().catch(() => null);
+  }
+  const { path, props } = parseEventBody(body);
+  const referrerPath = (() => {
+    const ref = req.headers.get("referer");
+    if (!ref) return void 0;
+    try {
+      return new URL(ref).pathname;
+    } catch {
+      return void 0;
+    }
+  })();
+  const payload = { name, path: path ?? referrerPath, props };
+  const endpoint = eventEndpointFor(config);
+  const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
+  if (endpoint && apiKey) {
+    if (debug) log("tracking client event:", payload);
+    event.waitUntil(sendClientEvent(payload, endpoint, apiKey, debug));
+  } else if (debug) {
+    log("event route matched but not configured (endpoint and/or apiKey missing)");
+  }
+  return import_server.NextResponse.json({});
+}
+function createTrackingMiddleware(config = {}) {
+  return async function middleware(req, event) {
+    const eventResponse = await handleEvent(req, event, config);
+    if (eventResponse) return eventResponse;
+    track(req, event, config);
+    return import_server.NextResponse.next();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildEvent,
+  createTrackingMiddleware,
+  deriveEventEndpoint,
+  getClientIp,
+  handleEvent,
+  matchEventRoute,
+  resolveEventName,
+  track
+});

package/dist/index.d.cts

@@ -0,0 +1,158 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/**
+ * The wire format posted to the Trackking collector's `/collect` endpoint.
+ * Deliberately minimal: no cookies, no client identifiers. The raw `ip` is
+ * sent over HTTPS so the collector can derive a daily-rotating visitor hash —
+ * the collector hashes it on arrival and never stores it.
+ */
+interface TrackkingEvent {
+    /** Pathname only (no query string), e.g. "/en/pricing". */
+    path: string;
+    /** Host of the tracked site, used by the collector to drop self-referrals. */
+    host: string | null;
+    /** Raw `Referer` header value, or null. Truncated to its host by the collector. */
+    referrer: string | null;
+    /** Raw `User-Agent` header value, or null. */
+    userAgent: string | null;
+    /** Best-effort client IP. Hashed-and-discarded by the collector; never stored. */
+    ip: string | null;
+    /** Low-cost request headers the collector stores for server-side bot scoring. */
+    headers?: TrackkingHeaderSignals;
+    /** Optional ISO timestamp. The collector stamps server time if omitted. */
+    timestamp?: string;
+}
+/**
+ * Request headers that help the collector tell real browser navigations from
+ * bots without any client-side JS: Fetch Metadata (Sec-Fetch-*), low-entropy
+ * client hints (Sec-CH-UA*), Accept-Language, and Upgrade-Insecure-Requests.
+ * All optional — browsers differ (Firefox/Safari omit client hints), so the
+ * collector treats a missing value as "unknown", never a bot signal on its own.
+ */
+interface TrackkingHeaderSignals {
+    acceptLanguage?: string | null;
+    accept?: string | null;
+    secFetchSite?: string | null;
+    secFetchMode?: string | null;
+    secFetchDest?: string | null;
+    secFetchUser?: string | null;
+    secChUa?: string | null;
+    secChUaMobile?: string | null;
+    secChUaPlatform?: string | null;
+    upgradeInsecureRequests?: string | null;
+}
+interface TrackkingConfig {
+    /** Collector URL. Defaults to `process.env.TRACKKING_ENDPOINT`. */
+    endpoint?: string;
+    /** API key identifying the site. Defaults to `process.env.TRACKKING_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Collector *event* endpoint (for the first-party event route). Defaults to
+     * `process.env.TRACKKING_EVENT_ENDPOINT`, then to the page-view `endpoint`
+     * with a trailing `/collect` swapped for `/event`.
+     */
+    eventEndpoint?: string;
+    /**
+     * First-party route template for client event beacons, e.g. `"/data/:event"`
+     * or `"/data/*"`. When a request path matches, the middleware records a named
+     * event (the captured segment is the event name), forwards it to the collector
+     * server-side, and answers the client `200 {}` instead of passing through.
+     * Defaults to the `TRACKKING_EVENT_ROUTE` env var. Ignored when `resolveEvent`
+     * is set.
+     */
+    eventRoute?: string;
+    /**
+     * Full control over event extraction. Return the event name to record (the
+     * middleware then answers `200 {}`), or null to let the request pass through
+     * untouched. Overrides `eventRoute`.
+     */
+    resolveEvent?: (req: NextRequest) => string | null;
+    /** Override how the client IP is extracted from the request. */
+    getClientIp?: (req: NextRequest) => string | null;
+    /**
+     * Number of reverse proxies you run in front of the tracked app. Controls
+     * which `x-forwarded-for` entry is trusted as the client IP: 0 (default) uses
+     * the spoofable leftmost entry; 1+ uses the value your own proxy appended,
+     * counting from the right. Falls back to the `TRACKKING_TRUSTED_PROXY_HOPS`
+     * env var. Ignored when `getClientIp` is provided.
+     */
+    trustedProxyHops?: number;
+    /** Return false to skip tracking a given request. */
+    shouldTrack?: (req: NextRequest) => boolean;
+    /**
+     * Log verbose diagnostics (config, per-request decisions, response status) to
+     * the console. Defaults to the `TRACKKING_DEBUG` env var being set to a truthy
+     * value ("1", "true", any non-empty value other than "0"/"false").
+     */
+    debug?: boolean;
+}
+
+/**
+ * Best-effort client IP. Behind a proxy (Vercel, Caddy, nginx) the real visitor
+ * IP is in `x-forwarded-for`; the socket IP would be the proxy.
+ *
+ * `hops` is the number of reverse proxies you run in front of the tracked app.
+ * With `hops = 0` (default) the leftmost XFF entry is used — spoofable, so treat
+ * counts as directional. With `hops >= 1` the value your own proxy appended is
+ * used instead (see `clientIpFromForwardedFor`), which a client cannot forge.
+ */
+declare function getClientIp(req: NextRequest, hops?: number): string | null;
+/** Build the event payload from an incoming request. */
+declare function buildEvent(req: NextRequest, config?: TrackkingConfig): TrackkingEvent;
+/**
+ * Fire-and-forget a page-view beacon. Call this from inside your own Next.js
+ * middleware when you already have one, then return your own response:
+ *
+ *   export function middleware(req: NextRequest, event: NextFetchEvent) {
+ *     track(req, event);
+ *     return NextResponse.next();
+ *   }
+ */
+declare function track(req: NextRequest, event: NextFetchEvent, config?: TrackkingConfig): void;
+/**
+ * Decide whether a request is a client-event beacon and, if so, extract the
+ * event name. `resolveEvent` wins; otherwise the `eventRoute` template (or the
+ * `TRACKKING_EVENT_ROUTE` env var) is matched against the path. Returns null
+ * when this isn't an event request (let it pass through).
+ */
+declare function resolveEventName(req: NextRequest, config?: TrackkingConfig): string | null;
+/**
+ * Handle a client-event beacon on the first-party event route. When the request
+ * matches, records the event (server-side, so the API key never reaches the
+ * browser) and returns a `200 {}` response to send back to the client. Returns
+ * null when the request is not an event beacon — the caller should then proceed
+ * with normal page-view tracking.
+ *
+ *   export async function middleware(req, event) {
+ *     const res = await handleEvent(req, event, config);
+ *     if (res) return res;              // it was a /data/<event> beacon
+ *     track(req, event, config);        // otherwise track the page view
+ *     return NextResponse.next();
+ *   }
+ */
+declare function handleEvent(req: NextRequest, event: NextFetchEvent, config?: TrackkingConfig): Promise<NextResponse | null>;
+/**
+ * Returns a complete Next.js middleware function for the common case where
+ * tracking is the only thing your middleware does. It also serves the
+ * first-party event route when `eventRoute`/`TRACKKING_EVENT_ROUTE` (or
+ * `resolveEvent`) is set:
+ *
+ *   export const middleware = createTrackingMiddleware();
+ *   export const config = { matcher: ["/", "/data/:path*", "/((?!_next|api|.*\\..*).*)"] };
+ */
+declare function createTrackingMiddleware(config?: TrackkingConfig): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse>;
+
+/**
+ * Return the event name captured from `pathname` by `template`, or null when the
+ * path doesn't match. The name is URI-decoded. When the template has no
+ * placeholder but still matches, the last non-empty path segment is used.
+ */
+declare function matchEventRoute(pathname: string, template: string): string | null;
+/**
+ * Derive the collector's event endpoint from the page-view endpoint by swapping
+ * a trailing `/collect` for `/event` — so the same base URL used for page views
+ * works for events without extra config. Returns undefined when `base` is unset.
+ */
+declare function deriveEventEndpoint(base: string | undefined): string | undefined;
+
+export { type TrackkingConfig, type TrackkingEvent, buildEvent, createTrackingMiddleware, deriveEventEndpoint, getClientIp, handleEvent, matchEventRoute, resolveEventName, track };

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/**
+ * The wire format posted to the Trackking collector's `/collect` endpoint.
+ * Deliberately minimal: no cookies, no client identifiers. The raw `ip` is
+ * sent over HTTPS so the collector can derive a daily-rotating visitor hash —
+ * the collector hashes it on arrival and never stores it.
+ */
+interface TrackkingEvent {
+    /** Pathname only (no query string), e.g. "/en/pricing". */
+    path: string;
+    /** Host of the tracked site, used by the collector to drop self-referrals. */
+    host: string | null;
+    /** Raw `Referer` header value, or null. Truncated to its host by the collector. */
+    referrer: string | null;
+    /** Raw `User-Agent` header value, or null. */
+    userAgent: string | null;
+    /** Best-effort client IP. Hashed-and-discarded by the collector; never stored. */
+    ip: string | null;
+    /** Low-cost request headers the collector stores for server-side bot scoring. */
+    headers?: TrackkingHeaderSignals;
+    /** Optional ISO timestamp. The collector stamps server time if omitted. */
+    timestamp?: string;
+}
+/**
+ * Request headers that help the collector tell real browser navigations from
+ * bots without any client-side JS: Fetch Metadata (Sec-Fetch-*), low-entropy
+ * client hints (Sec-CH-UA*), Accept-Language, and Upgrade-Insecure-Requests.
+ * All optional — browsers differ (Firefox/Safari omit client hints), so the
+ * collector treats a missing value as "unknown", never a bot signal on its own.
+ */
+interface TrackkingHeaderSignals {
+    acceptLanguage?: string | null;
+    accept?: string | null;
+    secFetchSite?: string | null;
+    secFetchMode?: string | null;
+    secFetchDest?: string | null;
+    secFetchUser?: string | null;
+    secChUa?: string | null;
+    secChUaMobile?: string | null;
+    secChUaPlatform?: string | null;
+    upgradeInsecureRequests?: string | null;
+}
+interface TrackkingConfig {
+    /** Collector URL. Defaults to `process.env.TRACKKING_ENDPOINT`. */
+    endpoint?: string;
+    /** API key identifying the site. Defaults to `process.env.TRACKKING_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Collector *event* endpoint (for the first-party event route). Defaults to
+     * `process.env.TRACKKING_EVENT_ENDPOINT`, then to the page-view `endpoint`
+     * with a trailing `/collect` swapped for `/event`.
+     */
+    eventEndpoint?: string;
+    /**
+     * First-party route template for client event beacons, e.g. `"/data/:event"`
+     * or `"/data/*"`. When a request path matches, the middleware records a named
+     * event (the captured segment is the event name), forwards it to the collector
+     * server-side, and answers the client `200 {}` instead of passing through.
+     * Defaults to the `TRACKKING_EVENT_ROUTE` env var. Ignored when `resolveEvent`
+     * is set.
+     */
+    eventRoute?: string;
+    /**
+     * Full control over event extraction. Return the event name to record (the
+     * middleware then answers `200 {}`), or null to let the request pass through
+     * untouched. Overrides `eventRoute`.
+     */
+    resolveEvent?: (req: NextRequest) => string | null;
+    /** Override how the client IP is extracted from the request. */
+    getClientIp?: (req: NextRequest) => string | null;
+    /**
+     * Number of reverse proxies you run in front of the tracked app. Controls
+     * which `x-forwarded-for` entry is trusted as the client IP: 0 (default) uses
+     * the spoofable leftmost entry; 1+ uses the value your own proxy appended,
+     * counting from the right. Falls back to the `TRACKKING_TRUSTED_PROXY_HOPS`
+     * env var. Ignored when `getClientIp` is provided.
+     */
+    trustedProxyHops?: number;
+    /** Return false to skip tracking a given request. */
+    shouldTrack?: (req: NextRequest) => boolean;
+    /**
+     * Log verbose diagnostics (config, per-request decisions, response status) to
+     * the console. Defaults to the `TRACKKING_DEBUG` env var being set to a truthy
+     * value ("1", "true", any non-empty value other than "0"/"false").
+     */
+    debug?: boolean;
+}
+
+/**
+ * Best-effort client IP. Behind a proxy (Vercel, Caddy, nginx) the real visitor
+ * IP is in `x-forwarded-for`; the socket IP would be the proxy.
+ *
+ * `hops` is the number of reverse proxies you run in front of the tracked app.
+ * With `hops = 0` (default) the leftmost XFF entry is used — spoofable, so treat
+ * counts as directional. With `hops >= 1` the value your own proxy appended is
+ * used instead (see `clientIpFromForwardedFor`), which a client cannot forge.
+ */
+declare function getClientIp(req: NextRequest, hops?: number): string | null;
+/** Build the event payload from an incoming request. */
+declare function buildEvent(req: NextRequest, config?: TrackkingConfig): TrackkingEvent;
+/**
+ * Fire-and-forget a page-view beacon. Call this from inside your own Next.js
+ * middleware when you already have one, then return your own response:
+ *
+ *   export function middleware(req: NextRequest, event: NextFetchEvent) {
+ *     track(req, event);
+ *     return NextResponse.next();
+ *   }
+ */
+declare function track(req: NextRequest, event: NextFetchEvent, config?: TrackkingConfig): void;
+/**
+ * Decide whether a request is a client-event beacon and, if so, extract the
+ * event name. `resolveEvent` wins; otherwise the `eventRoute` template (or the
+ * `TRACKKING_EVENT_ROUTE` env var) is matched against the path. Returns null
+ * when this isn't an event request (let it pass through).
+ */
+declare function resolveEventName(req: NextRequest, config?: TrackkingConfig): string | null;
+/**
+ * Handle a client-event beacon on the first-party event route. When the request
+ * matches, records the event (server-side, so the API key never reaches the
+ * browser) and returns a `200 {}` response to send back to the client. Returns
+ * null when the request is not an event beacon — the caller should then proceed
+ * with normal page-view tracking.
+ *
+ *   export async function middleware(req, event) {
+ *     const res = await handleEvent(req, event, config);
+ *     if (res) return res;              // it was a /data/<event> beacon
+ *     track(req, event, config);        // otherwise track the page view
+ *     return NextResponse.next();
+ *   }
+ */
+declare function handleEvent(req: NextRequest, event: NextFetchEvent, config?: TrackkingConfig): Promise<NextResponse | null>;
+/**
+ * Returns a complete Next.js middleware function for the common case where
+ * tracking is the only thing your middleware does. It also serves the
+ * first-party event route when `eventRoute`/`TRACKKING_EVENT_ROUTE` (or
+ * `resolveEvent`) is set:
+ *
+ *   export const middleware = createTrackingMiddleware();
+ *   export const config = { matcher: ["/", "/data/:path*", "/((?!_next|api|.*\\..*).*)"] };
+ */
+declare function createTrackingMiddleware(config?: TrackkingConfig): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse>;
+
+/**
+ * Return the event name captured from `pathname` by `template`, or null when the
+ * path doesn't match. The name is URI-decoded. When the template has no
+ * placeholder but still matches, the last non-empty path segment is used.
+ */
+declare function matchEventRoute(pathname: string, template: string): string | null;
+/**
+ * Derive the collector's event endpoint from the page-view endpoint by swapping
+ * a trailing `/collect` for `/event` — so the same base URL used for page views
+ * works for events without extra config. Returns undefined when `base` is unset.
+ */
+declare function deriveEventEndpoint(base: string | undefined): string | undefined;
+
+export { type TrackkingConfig, type TrackkingEvent, buildEvent, createTrackingMiddleware, deriveEventEndpoint, getClientIp, handleEvent, matchEventRoute, resolveEventName, track };

package/dist/index.js

@@ -0,0 +1,235 @@
+// src/middleware.ts
+import { NextResponse } from "next/server";
+
+// src/forwarded.ts
+function clientIpFromForwardedFor(xff, trustedProxyHops2 = 0) {
+  if (!xff) return null;
+  const parts = xff.split(",").map((p) => p.trim()).filter(Boolean);
+  if (parts.length === 0) return null;
+  if (trustedProxyHops2 <= 0) return parts[0] ?? null;
+  const idx = Math.max(0, parts.length - trustedProxyHops2);
+  return parts[idx] ?? null;
+}
+
+// src/event-route.ts
+function eventRouteRegex(template) {
+  const source = template.split("/").map((seg) => {
+    if (seg.startsWith(":")) return "([^/]+)";
+    if (seg === "*") return "(.+)";
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("/");
+  return new RegExp(`^${source}$`);
+}
+function matchEventRoute(pathname, template) {
+  if (!template) return null;
+  const match = eventRouteRegex(template).exec(pathname);
+  if (!match) return null;
+  const captured = match[1] ?? pathname.split("/").filter(Boolean).pop() ?? "";
+  try {
+    return decodeURIComponent(captured);
+  } catch {
+    return captured;
+  }
+}
+function deriveEventEndpoint(base) {
+  if (!base) return void 0;
+  return base.replace(/\/collect\/?$/, "/event");
+}
+function parseEventBody(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const b = body;
+  const out = {};
+  if (typeof b.path === "string") out.path = b.path;
+  if (b.props && typeof b.props === "object" && !Array.isArray(b.props)) {
+    out.props = b.props;
+  }
+  return out;
+}
+
+// src/middleware.ts
+function trustedProxyHops(config) {
+  if (typeof config.trustedProxyHops === "number") return config.trustedProxyHops;
+  const raw = process.env.TRACKKING_TRUSTED_PROXY_HOPS;
+  const n = raw ? Number.parseInt(raw, 10) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function envDebug() {
+  const v = process.env.TRACKKING_DEBUG;
+  return v != null && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+function isDebug(config) {
+  return config.debug ?? envDebug();
+}
+function log(...args) {
+  console.debug("[trackking]", ...args);
+}
+function maskKey(key) {
+  if (!key) return "(unset)";
+  if (key.length <= 8) return "********";
+  return `${key.slice(0, 6)}\u2026(${key.length} chars)`;
+}
+function getClientIp(req, hops = 0) {
+  const xff = clientIpFromForwardedFor(req.headers.get("x-forwarded-for"), hops);
+  if (xff) return xff;
+  const real = req.headers.get("x-real-ip");
+  if (real) return real.trim();
+  const ip = req.ip;
+  return ip ?? null;
+}
+function isPrefetch(req) {
+  if (req.headers.get("next-router-prefetch")) return true;
+  const purpose = req.headers.get("purpose") ?? req.headers.get("x-purpose");
+  if (purpose && purpose.toLowerCase() === "prefetch") return true;
+  const secPurpose = req.headers.get("sec-purpose");
+  if (secPurpose && secPurpose.toLowerCase().includes("prefetch")) return true;
+  return false;
+}
+function headerSignals(req) {
+  const h = req.headers;
+  return {
+    acceptLanguage: h.get("accept-language"),
+    accept: h.get("accept"),
+    secFetchSite: h.get("sec-fetch-site"),
+    secFetchMode: h.get("sec-fetch-mode"),
+    secFetchDest: h.get("sec-fetch-dest"),
+    secFetchUser: h.get("sec-fetch-user"),
+    secChUa: h.get("sec-ch-ua"),
+    secChUaMobile: h.get("sec-ch-ua-mobile"),
+    secChUaPlatform: h.get("sec-ch-ua-platform"),
+    upgradeInsecureRequests: h.get("upgrade-insecure-requests")
+  };
+}
+function buildEvent(req, config = {}) {
+  const ipFn = config.getClientIp ?? ((r) => getClientIp(r, trustedProxyHops(config)));
+  return {
+    path: req.nextUrl.pathname,
+    host: req.nextUrl.host || req.headers.get("host"),
+    referrer: req.headers.get("referer"),
+    userAgent: req.headers.get("user-agent"),
+    ip: ipFn(req),
+    headers: headerSignals(req)
+  };
+}
+async function sendEvent(event, endpoint, apiKey, debug) {
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify(event),
+      // Survive a terminating edge runtime tearing the request down.
+      keepalive: true
+    });
+    if (debug) {
+      log(`POST ${endpoint} \u2192 ${res.status} ${res.statusText} (${event.path})`);
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        if (body) log("response body:", body.slice(0, 500));
+      }
+    }
+  } catch (err) {
+    if (debug) log("request failed:", err);
+  }
+}
+function track(req, event, config = {}) {
+  const endpoint = config.endpoint ?? process.env.TRACKKING_ENDPOINT;
+  const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
+  const debug = isDebug(config);
+  if (debug) {
+    log(`${req.method} ${req.nextUrl.pathname}`, {
+      endpoint: endpoint ?? "(unset)",
+      apiKey: maskKey(apiKey),
+      configKeys: Object.keys(config)
+    });
+  }
+  if (!endpoint || !apiKey) {
+    if (debug) log("skip: not configured (endpoint and/or apiKey missing)");
+    return;
+  }
+  if (req.method !== "GET") {
+    if (debug) log(`skip: method ${req.method} is not GET`);
+    return;
+  }
+  if (isPrefetch(req)) {
+    if (debug) log("skip: prefetch request");
+    return;
+  }
+  if (config.shouldTrack && !config.shouldTrack(req)) {
+    if (debug) log("skip: shouldTrack() returned false");
+    return;
+  }
+  const payload = buildEvent(req, config);
+  if (debug) log("tracking event:", payload);
+  event.waitUntil(sendEvent(payload, endpoint, apiKey, debug));
+}
+function eventEndpointFor(config) {
+  return config.eventEndpoint ?? process.env.TRACKKING_EVENT_ENDPOINT ?? deriveEventEndpoint(config.endpoint ?? process.env.TRACKKING_ENDPOINT);
+}
+function resolveEventName(req, config = {}) {
+  if (config.resolveEvent) return config.resolveEvent(req);
+  const template = config.eventRoute ?? process.env.TRACKKING_EVENT_ROUTE;
+  if (!template) return null;
+  return matchEventRoute(req.nextUrl.pathname, template);
+}
+async function sendClientEvent(payload, endpoint, apiKey, debug) {
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+    if (debug) log(`event POST ${endpoint} \u2192 ${res.status} (${payload.name})`);
+  } catch (err) {
+    if (debug) log("event request failed:", err);
+  }
+}
+async function handleEvent(req, event, config = {}) {
+  const name = resolveEventName(req, config);
+  if (name == null || name === "") return null;
+  const debug = isDebug(config);
+  let body = null;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    body = await req.json().catch(() => null);
+  }
+  const { path, props } = parseEventBody(body);
+  const referrerPath = (() => {
+    const ref = req.headers.get("referer");
+    if (!ref) return void 0;
+    try {
+      return new URL(ref).pathname;
+    } catch {
+      return void 0;
+    }
+  })();
+  const payload = { name, path: path ?? referrerPath, props };
+  const endpoint = eventEndpointFor(config);
+  const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
+  if (endpoint && apiKey) {
+    if (debug) log("tracking client event:", payload);
+    event.waitUntil(sendClientEvent(payload, endpoint, apiKey, debug));
+  } else if (debug) {
+    log("event route matched but not configured (endpoint and/or apiKey missing)");
+  }
+  return NextResponse.json({});
+}
+function createTrackingMiddleware(config = {}) {
+  return async function middleware(req, event) {
+    const eventResponse = await handleEvent(req, event, config);
+    if (eventResponse) return eventResponse;
+    track(req, event, config);
+    return NextResponse.next();
+  };
+}
+export {
+  buildEvent,
+  createTrackingMiddleware,
+  deriveEventEndpoint,
+  getClientIp,
+  handleEvent,
+  matchEventRoute,
+  resolveEventName,
+  track
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@iorg1/trackking-next",
+  "version": "0.4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iorg1/trackking.git",
+    "directory": "packages/middleware"
+  },
+  "description": "Cookieless, server-side page-view tracking for Next.js. Drop-in middleware that beacons visits to a Trackking collector — no cookies, no client-side script.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/*.test.ts"
+  },
+  "keywords": [
+    "nextjs",
+    "analytics",
+    "tracking",
+    "cookieless",
+    "middleware",
+    "privacy",
+    "gdpr"
+  ],
+  "peerDependencies": {
+    "next": ">=13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "next": "^14.2.15",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}