@footfall/next 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nitin Murali
+
+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/dist/beacon-Ht4IlMXQ.d.ts

@@ -0,0 +1,38 @@
+import { IngestPayload, Correction } from '@footfall/core/ingest';
+
+/** Runtime config, from env vars only (no code changes to toggle behaviour). */
+interface FootfallConfig {
+    /** Per-site write token. No token → middleware is inert. */
+    token: string | null;
+    /** Where to POST events. */
+    ingestUrl: string;
+    /** Kill switch: FOOTFALL_DISABLED=1 stops all emission. */
+    disabled: boolean;
+    /** Server-side salt base for IP hashing; combined with the date for daily rotation. */
+    ipSalt: string;
+    /** Per-instance daily soft cap; 0 = uncapped. Above it, events are sampled. */
+    dailyCap: number;
+    /** Hard timeout on the ingest send (ms). */
+    timeoutMs: number;
+}
+declare function readConfig(env?: Record<string, string | undefined>): FootfallConfig;
+/** Whether the middleware should emit at all (token present + not killed). */
+declare function isActive(cfg: FootfallConfig): boolean;
+
+type FetchLike = typeof fetch;
+/**
+ * Fire-and-forget send with a hard timeout and one retry. NEVER throws and never
+ * rejects — all failures are swallowed so the site is never affected by ingest health.
+ * Returns whether the send eventually succeeded (for tests/metrics only).
+ */
+declare function sendBatch(url: string, token: string, batch: IngestPayload, timeoutMs: number, fetchImpl?: FetchLike): Promise<boolean>;
+
+/** POST a status correction. Fire-and-forget: never throws, swallows all failures. */
+declare function sendCorrection(cfg: FootfallConfig, correction: Correction, fetchImpl?: FetchLike): Promise<boolean>;
+/** Call from `instrumentation.ts` `onRequestError` to emit a 5xx correction. */
+declare function footfallOnRequestError(_error: unknown, request: {
+    headers?: Headers | Record<string, string | undefined>;
+    path?: string;
+}): Promise<void>;
+
+export { type FootfallConfig as F, type FetchLike as a, sendCorrection as b, footfallOnRequestError as f, isActive as i, readConfig as r, sendBatch as s };

package/dist/beacon.d.ts

@@ -0,0 +1,2 @@
+import '@footfall/core/ingest';
+export { f as footfallOnRequestError, b as sendCorrection } from './beacon-Ht4IlMXQ.js';

package/dist/beacon.js

@@ -0,0 +1 @@
+export { footfallOnRequestError, sendCorrection } from './chunk-W6AJB5JH.js';

package/dist/chunk-W6AJB5JH.js

@@ -0,0 +1,57 @@
+// src/config.ts
+function truthy(v) {
+  return v === "1" || v === "true" || v === "yes";
+}
+function readConfig(env = process.env) {
+  return {
+    token: env.FOOTFALL_TOKEN ?? null,
+    ingestUrl: env.FOOTFALL_INGEST_URL ?? "",
+    disabled: truthy(env.FOOTFALL_DISABLED),
+    ipSalt: env.FOOTFALL_IP_SALT ?? "footfall",
+    dailyCap: Number.parseInt(env.FOOTFALL_DAILY_CAP ?? "0", 10) || 0,
+    timeoutMs: Number.parseInt(env.FOOTFALL_TIMEOUT_MS ?? "500", 10) || 500
+  };
+}
+function isActive(cfg) {
+  return !cfg.disabled && cfg.token !== null && cfg.token !== "" && cfg.ingestUrl !== "";
+}
+
+// src/beacon.ts
+async function sendCorrection(cfg, correction, fetchImpl = fetch) {
+  const token = cfg.token;
+  if (!isActive(cfg) || !token) return false;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), cfg.timeoutMs);
+  try {
+    const res = await fetchImpl(cfg.ingestUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ site: token, corrections: [correction] }),
+      signal: controller.signal,
+      keepalive: true
+    });
+    clearTimeout(timer);
+    return res.ok;
+  } catch {
+    clearTimeout(timer);
+    return false;
+  }
+}
+function readHeader(h, key) {
+  if (typeof h.get === "function") return h.get(key);
+  return h[key] ?? null;
+}
+async function footfallOnRequestError(_error, request) {
+  const cfg = readConfig();
+  if (!isActive(cfg) || !request.headers) return;
+  const requestId = readHeader(request.headers, "x-footfall-id");
+  if (!requestId) return;
+  await sendCorrection(cfg, {
+    request_id: requestId,
+    status: 500,
+    path: request.path ?? readHeader(request.headers, "x-footfall-path"),
+    ts: Date.now()
+  });
+}
+
+export { footfallOnRequestError, isActive, readConfig, sendCorrection };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { NextRequest, NextFetchEvent } from 'next/server';
+import { F as FootfallConfig } from './beacon-Ht4IlMXQ.js';
+export { a as FetchLike, f as footfallOnRequestError, i as isActive, r as readConfig, s as sendBatch, b as sendCorrection } from './beacon-Ht4IlMXQ.js';
+import { Event } from '@footfall/core/schema';
+import '@footfall/core/ingest';
+
+/**
+ * Build an Event from a request. Middleware runs before the response, so `status`,
+ * `resp_bytes`, `content_type`, and `duration_ms` are null here — they're filled by
+ * server-side beacons (404/5xx) or left for the coverage matrix to handle.
+ */
+declare function buildEvent(req: Request, opts: {
+    site: string;
+    ipSalt: string;
+    nowMs: number;
+}): Promise<Event>;
+
+/**
+ * Edge-runtime IP hashing (Web Crypto, not node:crypto). The salt rotates daily so
+ * sessions stitch within a day but the raw IP is never stored or reversible across days.
+ */
+/** The salt in effect for the day containing `nowMs`. */
+declare function dailySalt(saltBase: string, nowMs: number): string;
+/** SHA-256 of (dailySalt + ip), hex, truncated to 32 chars. Async (crypto.subtle). */
+declare function hashIp(ip: string, saltBase: string, nowMs: number): Promise<string>;
+
+/**
+ * Best-effort per-instance daily cap with graceful sampling above it. Edge instances
+ * are stateless/distributed, so this is a soft guard; the authoritative cap is enforced
+ * at ingest (Phase 6). Crucially, dropped counts are never silent — the next emitted
+ * batch carries the accumulated `dropped` so truncation is always visible.
+ */
+declare class Sampler {
+    private readonly cap;
+    /** Above the cap, keep 1 in `keepEvery`. */
+    private readonly keepEvery;
+    private day;
+    private count;
+    private dropped;
+    constructor(cap: number, 
+    /** Above the cap, keep 1 in `keepEvery`. */
+    keepEvery?: number);
+    private roll;
+    private takeDropped;
+    /** Decide whether to emit this request; when emitting, hand back accumulated drops. */
+    next(nowMs: number): {
+        emit: boolean;
+        dropped: number;
+    };
+}
+
+/** A Next.js middleware function (what `middleware.ts` exports). */
+type MiddlewareFn = (req: NextRequest, ev: NextFetchEvent) => Response | Promise<Response | undefined> | undefined;
+interface WithFootfallOptions {
+    /** Override env config (mainly for tests). */
+    config?: FootfallConfig;
+    /** Inject fetch (mainly for tests). */
+    fetchImpl?: typeof fetch;
+    /** Inject the clock (mainly for tests). */
+    now?: () => number;
+}
+/**
+ * Wrap a site's middleware (or nothing) with observe-only event capture. The wrapped
+ * middleware's response is returned unchanged; capture happens in `event.waitUntil`,
+ * so ingest health can never affect the site.
+ */
+declare function withFootfall(existing?: MiddlewareFn, opts?: WithFootfallOptions): MiddlewareFn;
+
+export { FootfallConfig, type MiddlewareFn, Sampler, type WithFootfallOptions, buildEvent, dailySalt, hashIp, withFootfall };

package/dist/index.js

@@ -0,0 +1,624 @@
+import { readConfig, isActive } from './chunk-W6AJB5JH.js';
+export { footfallOnRequestError, isActive, readConfig, sendCorrection } from './chunk-W6AJB5JH.js';
+import { NextResponse } from 'next/server';
+
+// ../core/src/verify/cidr.ts
+function parseV4(s) {
+  const m = s.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return null;
+  let v = 0n;
+  for (let i = 1; i <= 4; i++) {
+    const o = Number(m[i]);
+    if (o > 255) return null;
+    v = v << 8n | BigInt(o);
+  }
+  return v;
+}
+function parseV6(input) {
+  let s = input;
+  if (s.includes(".")) {
+    const idx = s.lastIndexOf(":");
+    const v4 = parseV4(s.slice(idx + 1));
+    if (v4 === null) return null;
+    const hi = Number(v4 >> 16n & 0xffffn);
+    const lo = Number(v4 & 0xffffn);
+    s = `${s.slice(0, idx + 1)}${hi.toString(16)}:${lo.toString(16)}`;
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const missing = 8 - head.length - tail.length;
+  if (halves.length === 1 && head.length !== 8) return null;
+  if (missing < 0) return null;
+  const groups = [
+    ...head,
+    ...halves.length === 2 ? Array(missing).fill("0") : [],
+    ...tail
+  ];
+  if (groups.length !== 8) return null;
+  let v = 0n;
+  for (const g of groups) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null;
+    v = v << 16n | BigInt(Number.parseInt(g, 16));
+  }
+  return v;
+}
+function ipInCidr(ip, cidr) {
+  const slash = cidr.lastIndexOf("/");
+  if (slash < 0) return false;
+  const base = cidr.slice(0, slash);
+  const prefix = Number(cidr.slice(slash + 1));
+  const isV6 = cidr.includes(":");
+  const bits = isV6 ? 128 : 32;
+  if (!Number.isInteger(prefix) || prefix < 0 || prefix > bits) return false;
+  const ipVal = isV6 ? parseV6(ip) : parseV4(ip);
+  const baseVal = isV6 ? parseV6(base) : parseV4(base);
+  if (ipVal === null || baseVal === null) return false;
+  const mask = prefix === 0 ? 0n : (1n << BigInt(bits)) - 1n ^ (1n << BigInt(bits - prefix)) - 1n;
+  return (ipVal & mask) === (baseVal & mask);
+}
+
+// ../core/src/verify/operators.ts
+var OPERATORS = [
+  { operator: "googlebot", family: "googlebot", class: "crawler", ua: /Googlebot/i },
+  { operator: "bingbot", family: "bingbot", class: "crawler", ua: /bingbot/i },
+  { operator: "gptbot", family: "gptbot", class: "crawler", ua: /GPTBot/i }
+];
+function matchOperator(ua) {
+  if (!ua) return null;
+  return OPERATORS.find((o) => o.ua.test(ua)) ?? null;
+}
+
+// ../core/src/verify/ranges.ts
+var OPERATOR_RANGES = {
+  googlebot: [
+    "2001:4860:4801:10::/64",
+    "2001:4860:4801:11::/64",
+    "2001:4860:4801:12::/64",
+    "2001:4860:4801:13::/64",
+    "2001:4860:4801:14::/64",
+    "2001:4860:4801:15::/64",
+    "2001:4860:4801:16::/64",
+    "2001:4860:4801:17::/64",
+    "2001:4860:4801:18::/64",
+    "2001:4860:4801:19::/64",
+    "2001:4860:4801:1a::/64",
+    "2001:4860:4801:1b::/64",
+    "2001:4860:4801:1c::/64",
+    "2001:4860:4801:1d::/64",
+    "2001:4860:4801:1e::/64",
+    "2001:4860:4801:1f::/64",
+    "2001:4860:4801:20::/64",
+    "2001:4860:4801:21::/64",
+    "2001:4860:4801:22::/64",
+    "2001:4860:4801:23::/64",
+    "2001:4860:4801:24::/64",
+    "2001:4860:4801:25::/64",
+    "2001:4860:4801:26::/64",
+    "2001:4860:4801:27::/64",
+    "2001:4860:4801:28::/64",
+    "2001:4860:4801:29::/64",
+    "2001:4860:4801:2::/64",
+    "2001:4860:4801:2a::/64",
+    "2001:4860:4801:2b::/64",
+    "2001:4860:4801:2c::/64",
+    "2001:4860:4801:2d::/64",
+    "2001:4860:4801:2e::/64",
+    "2001:4860:4801:2f::/64",
+    "2001:4860:4801:30::/64",
+    "2001:4860:4801:31::/64",
+    "2001:4860:4801:32::/64",
+    "2001:4860:4801:33::/64",
+    "2001:4860:4801:34::/64",
+    "2001:4860:4801:35::/64",
+    "2001:4860:4801:36::/64",
+    "2001:4860:4801:37::/64",
+    "2001:4860:4801:38::/64",
+    "2001:4860:4801:39::/64",
+    "2001:4860:4801:3a::/64",
+    "2001:4860:4801:3b::/64",
+    "2001:4860:4801:3c::/64",
+    "2001:4860:4801:3d::/64",
+    "2001:4860:4801:3e::/64",
+    "2001:4860:4801:3f::/64",
+    "2001:4860:4801:40::/64",
+    "2001:4860:4801:41::/64",
+    "2001:4860:4801:42::/64",
+    "2001:4860:4801:44::/64",
+    "2001:4860:4801:45::/64",
+    "2001:4860:4801:46::/64",
+    "2001:4860:4801:47::/64",
+    "2001:4860:4801:48::/64",
+    "2001:4860:4801:49::/64",
+    "2001:4860:4801:4a::/64",
+    "2001:4860:4801:4b::/64",
+    "2001:4860:4801:4c::/64",
+    "2001:4860:4801:4d::/64",
+    "2001:4860:4801:4e::/64",
+    "2001:4860:4801:50::/64",
+    "2001:4860:4801:51::/64",
+    "2001:4860:4801:52::/64",
+    "2001:4860:4801:53::/64",
+    "2001:4860:4801:54::/64",
+    "2001:4860:4801:55::/64",
+    "2001:4860:4801:56::/64",
+    "2001:4860:4801:57::/64",
+    "2001:4860:4801:58::/64",
+    "2001:4860:4801:59::/64",
+    "2001:4860:4801:60::/64",
+    "2001:4860:4801:61::/64",
+    "2001:4860:4801:62::/64",
+    "2001:4860:4801:63::/64",
+    "2001:4860:4801:64::/64",
+    "2001:4860:4801:65::/64",
+    "2001:4860:4801:66::/64",
+    "2001:4860:4801:67::/64",
+    "2001:4860:4801:68::/64",
+    "2001:4860:4801:69::/64",
+    "2001:4860:4801:6a::/64",
+    "2001:4860:4801:6b::/64",
+    "2001:4860:4801:6c::/64",
+    "2001:4860:4801:6d::/64",
+    "2001:4860:4801:6e::/64",
+    "2001:4860:4801:6f::/64",
+    "2001:4860:4801:70::/64",
+    "2001:4860:4801:71::/64",
+    "2001:4860:4801:72::/64",
+    "2001:4860:4801:73::/64",
+    "2001:4860:4801:74::/64",
+    "2001:4860:4801:75::/64",
+    "2001:4860:4801:76::/64",
+    "2001:4860:4801:77::/64",
+    "2001:4860:4801:78::/64",
+    "2001:4860:4801:79::/64",
+    "2001:4860:4801:7a::/64",
+    "2001:4860:4801:7b::/64",
+    "2001:4860:4801:7c::/64",
+    "2001:4860:4801:7d::/64",
+    "2001:4860:4801:7e::/64",
+    "2001:4860:4801:7f::/64",
+    "2001:4860:4801:80::/64",
+    "2001:4860:4801:81::/64",
+    "2001:4860:4801:82::/64",
+    "2001:4860:4801:83::/64",
+    "2001:4860:4801:84::/64",
+    "2001:4860:4801:85::/64",
+    "2001:4860:4801:86::/64",
+    "2001:4860:4801:87::/64",
+    "2001:4860:4801:88::/64",
+    "2001:4860:4801:90::/64",
+    "2001:4860:4801:91::/64",
+    "2001:4860:4801:92::/64",
+    "2001:4860:4801:93::/64",
+    "2001:4860:4801:94::/64",
+    "2001:4860:4801:95::/64",
+    "2001:4860:4801:96::/64",
+    "2001:4860:4801:97::/64",
+    "2001:4860:4801:a0::/64",
+    "2001:4860:4801:a1::/64",
+    "2001:4860:4801:a2::/64",
+    "2001:4860:4801:a3::/64",
+    "2001:4860:4801:a4::/64",
+    "2001:4860:4801:a5::/64",
+    "2001:4860:4801:a6::/64",
+    "2001:4860:4801:a7::/64",
+    "2001:4860:4801:a8::/64",
+    "2001:4860:4801:a9::/64",
+    "2001:4860:4801:aa::/64",
+    "2001:4860:4801:ab::/64",
+    "2001:4860:4801:ac::/64",
+    "2001:4860:4801:ad::/64",
+    "2001:4860:4801:ae::/64",
+    "2001:4860:4801:b0::/64",
+    "2001:4860:4801:b1::/64",
+    "2001:4860:4801:b2::/64",
+    "2001:4860:4801:b3::/64",
+    "2001:4860:4801:b4::/64",
+    "2001:4860:4801:b5::/64",
+    "2001:4860:4801:b6::/64",
+    "2001:4860:4801:c::/64",
+    "2001:4860:4801:f::/64",
+    "192.178.4.0/27",
+    "192.178.4.128/27",
+    "192.178.4.160/27",
+    "192.178.4.192/27",
+    "192.178.4.224/27",
+    "192.178.4.32/27",
+    "192.178.4.64/27",
+    "192.178.4.96/27",
+    "192.178.5.0/27",
+    "192.178.6.0/27",
+    "192.178.6.128/27",
+    "192.178.6.160/27",
+    "192.178.6.192/27",
+    "192.178.6.224/27",
+    "192.178.6.32/27",
+    "192.178.6.64/27",
+    "192.178.6.96/27",
+    "192.178.7.0/27",
+    "192.178.7.128/27",
+    "192.178.7.160/27",
+    "192.178.7.192/27",
+    "192.178.7.224/27",
+    "192.178.7.32/27",
+    "192.178.7.64/27",
+    "192.178.7.96/27",
+    "34.100.182.96/28",
+    "34.101.50.144/28",
+    "34.118.254.0/28",
+    "34.118.66.0/28",
+    "34.126.178.96/28",
+    "34.146.150.144/28",
+    "34.147.110.144/28",
+    "34.151.74.144/28",
+    "34.152.50.64/28",
+    "34.154.114.144/28",
+    "34.155.98.32/28",
+    "34.165.18.176/28",
+    "34.175.160.64/28",
+    "34.176.130.16/28",
+    "34.22.85.0/27",
+    "34.64.82.64/28",
+    "34.65.242.112/28",
+    "34.80.50.80/28",
+    "34.88.194.0/28",
+    "34.89.10.80/28",
+    "34.89.198.80/28",
+    "34.96.162.48/28",
+    "35.247.243.240/28",
+    "66.249.64.0/27",
+    "66.249.64.128/27",
+    "66.249.64.160/27",
+    "66.249.64.192/27",
+    "66.249.64.224/27",
+    "66.249.64.32/27",
+    "66.249.64.64/27",
+    "66.249.64.96/27",
+    "66.249.65.0/27",
+    "66.249.65.128/27",
+    "66.249.65.160/27",
+    "66.249.65.192/27",
+    "66.249.65.224/27",
+    "66.249.65.32/27",
+    "66.249.65.64/27",
+    "66.249.65.96/27",
+    "66.249.66.0/27",
+    "66.249.66.128/27",
+    "66.249.66.160/27",
+    "66.249.66.192/27",
+    "66.249.66.224/27",
+    "66.249.66.32/27",
+    "66.249.66.64/27",
+    "66.249.66.96/27",
+    "66.249.67.0/27",
+    "66.249.67.32/27",
+    "66.249.67.64/27",
+    "66.249.68.0/27",
+    "66.249.68.128/27",
+    "66.249.68.160/27",
+    "66.249.68.192/27",
+    "66.249.68.32/27",
+    "66.249.68.64/27",
+    "66.249.68.96/27",
+    "66.249.69.0/27",
+    "66.249.69.128/27",
+    "66.249.69.160/27",
+    "66.249.69.192/27",
+    "66.249.69.224/27",
+    "66.249.69.32/27",
+    "66.249.69.64/27",
+    "66.249.69.96/27",
+    "66.249.70.0/27",
+    "66.249.70.128/27",
+    "66.249.70.160/27",
+    "66.249.70.192/27",
+    "66.249.70.224/27",
+    "66.249.70.32/27",
+    "66.249.70.64/27",
+    "66.249.70.96/27",
+    "66.249.71.0/27",
+    "66.249.71.128/27",
+    "66.249.71.160/27",
+    "66.249.71.192/27",
+    "66.249.71.224/27",
+    "66.249.71.32/27",
+    "66.249.71.64/27",
+    "66.249.71.96/27",
+    "66.249.72.0/27",
+    "66.249.72.128/27",
+    "66.249.72.160/27",
+    "66.249.72.192/27",
+    "66.249.72.224/27",
+    "66.249.72.32/27",
+    "66.249.72.64/27",
+    "66.249.72.96/27",
+    "66.249.73.0/27",
+    "66.249.73.128/27",
+    "66.249.73.160/27",
+    "66.249.73.192/27",
+    "66.249.73.224/27",
+    "66.249.73.32/27",
+    "66.249.73.64/27",
+    "66.249.73.96/27",
+    "66.249.74.0/27",
+    "66.249.74.128/27",
+    "66.249.74.160/27",
+    "66.249.74.192/27",
+    "66.249.74.224/27",
+    "66.249.74.32/27",
+    "66.249.74.64/27",
+    "66.249.74.96/27",
+    "66.249.75.0/27",
+    "66.249.75.128/27",
+    "66.249.75.160/27",
+    "66.249.75.192/27",
+    "66.249.75.224/27",
+    "66.249.75.32/27",
+    "66.249.75.64/27",
+    "66.249.75.96/27",
+    "66.249.76.0/27",
+    "66.249.76.128/27",
+    "66.249.76.160/27",
+    "66.249.76.192/27",
+    "66.249.76.224/27",
+    "66.249.76.32/27",
+    "66.249.76.64/27",
+    "66.249.76.96/27",
+    "66.249.77.0/27",
+    "66.249.77.128/27",
+    "66.249.77.160/27",
+    "66.249.77.192/27",
+    "66.249.77.224/27",
+    "66.249.77.32/27",
+    "66.249.77.64/27",
+    "66.249.77.96/27",
+    "66.249.78.0/27",
+    "66.249.78.128/27",
+    "66.249.78.160/27",
+    "66.249.78.192/27",
+    "66.249.78.224/27",
+    "66.249.78.32/27",
+    "66.249.78.64/27",
+    "66.249.78.96/27",
+    "66.249.79.0/27",
+    "66.249.79.128/27",
+    "66.249.79.160/27",
+    "66.249.79.192/27",
+    "66.249.79.224/27",
+    "66.249.79.32/27",
+    "66.249.79.64/27"
+  ],
+  bingbot: [
+    "157.55.39.0/24",
+    "207.46.13.0/24",
+    "40.77.167.0/24",
+    "13.66.139.0/24",
+    "13.66.144.0/24",
+    "52.167.144.0/24",
+    "13.67.10.16/28",
+    "13.69.66.240/28",
+    "13.71.172.224/28",
+    "139.217.52.0/28",
+    "191.233.204.224/28",
+    "20.36.108.32/28",
+    "20.43.120.16/28",
+    "40.79.131.208/28",
+    "40.79.186.176/28",
+    "52.231.148.0/28",
+    "20.79.107.240/28",
+    "51.105.67.0/28",
+    "20.125.163.80/28",
+    "40.77.188.0/22",
+    "65.55.210.0/24",
+    "199.30.24.0/23",
+    "40.77.202.0/24",
+    "40.77.139.0/25",
+    "20.74.197.0/28",
+    "20.15.133.160/27",
+    "40.77.177.0/24",
+    "40.77.178.0/23"
+  ],
+  gptbot: [
+    "132.196.86.0/24",
+    "172.182.202.0/25",
+    "172.182.204.0/24",
+    "172.182.207.0/25",
+    "172.182.214.0/24",
+    "172.182.215.0/24",
+    "20.125.66.80/28",
+    "20.171.206.0/24",
+    "20.171.207.0/24",
+    "4.227.36.0/25",
+    "52.230.152.0/24",
+    "74.7.175.128/25",
+    "74.7.227.0/25",
+    "74.7.227.128/25",
+    "74.7.228.0/25",
+    "74.7.230.0/25",
+    "74.7.241.0/25",
+    "74.7.241.128/25",
+    "74.7.242.0/25",
+    "74.7.243.128/25",
+    "74.7.244.0/25"
+  ]
+};
+
+// ../core/src/verify/index.ts
+function verifyBot(ua, ip) {
+  const op = matchOperator(ua);
+  if (!op) return { operator: null, result: "unverifiable" };
+  const ranges = OPERATOR_RANGES[op.operator];
+  if (!ranges || !ip || ip === "unknown") return { operator: op.operator, result: "unverifiable" };
+  const inRange = ranges.some((cidr) => ipInCidr(ip, cidr));
+  return { operator: op.operator, result: inRange ? "verified" : "spoofed" };
+}
+function botVerified(ua, ip) {
+  const { result } = verifyBot(ua, ip);
+  return result === "unverifiable" ? null : result;
+}
+
+// ../core/src/version.ts
+var EVENT_VERSION = 1;
+
+// src/hash.ts
+function dailySalt(saltBase, nowMs) {
+  const day = new Date(nowMs).toISOString().slice(0, 10);
+  return `${saltBase}:${day}`;
+}
+async function hashIp(ip, saltBase, nowMs) {
+  const data = new TextEncoder().encode(`${dailySalt(saltBase, nowMs)}:${ip}`);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  let hex = "";
+  for (const b of new Uint8Array(digest)) hex += b.toString(16).padStart(2, "0");
+  return hex.slice(0, 32);
+}
+
+// src/event.ts
+var ASSET_EXT = /\.(css|js|mjs|map|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|eot)$/i;
+function isAsset(path) {
+  return path.startsWith("/_next/static") || ASSET_EXT.test(path);
+}
+function firstForwardedIp(headers) {
+  const xff = headers.get("x-forwarded-for");
+  if (xff) return xff.split(",")[0]?.trim() || "unknown";
+  return headers.get("x-real-ip") ?? "unknown";
+}
+function refererHost(referer) {
+  if (!referer) return null;
+  try {
+    return new URL(referer).host;
+  } catch {
+    return null;
+  }
+}
+async function buildEvent(req, opts) {
+  const url = new URL(req.url);
+  const h = req.headers;
+  const ip = firstForwardedIp(h);
+  const verified = botVerified(h.get("user-agent"), ip);
+  return {
+    v: EVENT_VERSION,
+    ts: opts.nowMs,
+    site: opts.site,
+    method: req.method,
+    path: url.pathname,
+    has_query: url.search !== "",
+    status: null,
+    resp_bytes: null,
+    content_type: null,
+    duration_ms: null,
+    ua: h.get("user-agent"),
+    accept: h.get("accept"),
+    sec_fetch_mode: h.get("sec-fetch-mode"),
+    referer_host: refererHost(h.get("referer")),
+    conditional: h.has("if-none-match") || h.has("if-modified-since"),
+    ip_hash: await hashIp(ip, opts.ipSalt, opts.nowMs),
+    asset: isAsset(url.pathname),
+    bot_verified: verified
+  };
+}
+
+// src/sampling.ts
+var Sampler = class {
+  constructor(cap, keepEvery = 10) {
+    this.cap = cap;
+    this.keepEvery = keepEvery;
+  }
+  cap;
+  keepEvery;
+  day = "";
+  count = 0;
+  dropped = 0;
+  roll(nowMs) {
+    const d = new Date(nowMs).toISOString().slice(0, 10);
+    if (d !== this.day) {
+      this.day = d;
+      this.count = 0;
+      this.dropped = 0;
+    }
+  }
+  takeDropped() {
+    const d = this.dropped;
+    this.dropped = 0;
+    return d;
+  }
+  /** Decide whether to emit this request; when emitting, hand back accumulated drops. */
+  next(nowMs) {
+    this.roll(nowMs);
+    this.count += 1;
+    if (this.cap <= 0 || this.count <= this.cap) {
+      return { emit: true, dropped: this.takeDropped() };
+    }
+    const over = this.count - this.cap;
+    if (over % this.keepEvery === 0) {
+      return { emit: true, dropped: this.takeDropped() };
+    }
+    this.dropped += 1;
+    return { emit: false, dropped: 0 };
+  }
+};
+
+// src/send.ts
+async function sendBatch(url, token, batch, timeoutMs, fetchImpl = fetch) {
+  const body = JSON.stringify(batch);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body,
+        signal: controller.signal,
+        keepalive: true
+      });
+      clearTimeout(timer);
+      if (res.ok) return true;
+    } catch {
+      clearTimeout(timer);
+    }
+  }
+  return false;
+}
+
+// src/index.ts
+function withFootfall(existing, opts = {}) {
+  const cfg = opts.config ?? readConfig();
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? Date.now;
+  const sampler = new Sampler(cfg.dailyCap);
+  const token = cfg.token;
+  return (req, ev) => {
+    if (!isActive(cfg) || !token) {
+      return existing ? existing(req, ev) : void 0;
+    }
+    const requestId = crypto.randomUUID();
+    const nowMs = now();
+    const decision = sampler.next(nowMs);
+    if (decision.emit) {
+      const capture = (async () => {
+        try {
+          const event = await buildEvent(req, { site: token, ipSalt: cfg.ipSalt, nowMs });
+          event.request_id = requestId;
+          await sendBatch(
+            cfg.ingestUrl,
+            token,
+            { site: token, events: [event], dropped: decision.dropped },
+            cfg.timeoutMs,
+            fetchImpl
+          );
+        } catch {
+        }
+      })();
+      ev.waitUntil(capture);
+    }
+    if (existing) return existing(req, ev);
+    const headers = new Headers(req.headers);
+    headers.set("x-footfall-id", requestId);
+    headers.set("x-footfall-path", new URL(req.url).pathname);
+    return NextResponse.next({ request: { headers } });
+  };
+}
+
+export { Sampler, buildEvent, dailySalt, hashIp, sendBatch, withFootfall };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@footfall/next",
+  "version": "0.1.0",
+  "description": "Observe-only, fail-open Next.js middleware that mirrors request events to Footfall.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./beacon": {
+      "types": "./dist/beacon.d.ts",
+      "import": "./dist/beacon.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nextjs",
+    "middleware",
+    "analytics",
+    "ai-agents",
+    "observability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nitinm21/footfall.git",
+    "directory": "packages/middleware"
+  },
+  "homepage": "https://github.com/nitinm21/footfall",
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "next": "^15.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "@footfall/core": "0.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
+  }
+}