statswhatshesaid 0.1.0

package/dist/index.cjs

@@ -0,0 +1,641 @@
+"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, {
+  FileSnapshotAdapter: () => FileSnapshotAdapter,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/middleware.ts
+var import_server2 = require("next/server");
+
+// src/bots.ts
+var BOT_UA_RE = /bot|crawler|spider|crawling|facebookexternalhit|slurp|mediapartners|ahrefs|semrush|bingpreview|headlesschrome|lighthouse|curl|wget|python-requests|node-fetch|axios|httpclient|java\//i;
+function isBot(ua) {
+  if (!ua) return true;
+  return BOT_UA_RE.test(ua);
+}
+
+// src/config.ts
+var DEFAULT_SNAPSHOT_PATH = "./.statswhatshesaid.json";
+var DEFAULT_FLUSH_INTERVAL_MS = 60 * 60 * 1e3;
+var DEFAULT_ENDPOINT_PATH = "/stats";
+var DEFAULT_HISTORY_DAYS = 90;
+var DEFAULT_MAX_HISTORY_DAYS = 365;
+var DEFAULT_TRUST_PROXY = 1;
+var MIN_RECOMMENDED_TOKEN_LENGTH = 32;
+var MIN_FLUSH_INTERVAL_MS = 1e3;
+var ENDPOINT_PATH_RE = /^\/[A-Za-z0-9\-._~/]*$/;
+var weakTokenWarned = false;
+function resolveConfig(options = {}) {
+  const env = typeof process !== "undefined" ? process.env : {};
+  const token = options.token ?? env.STATS_TOKEN;
+  if (!token) {
+    throw new Error(
+      "[statswhatshesaid] Missing required token. Set the STATS_TOKEN env var or pass `token` to stats.middleware({ token })."
+    );
+  }
+  if (!weakTokenWarned && token.length < MIN_RECOMMENDED_TOKEN_LENGTH) {
+    weakTokenWarned = true;
+    console.warn(
+      `[statswhatshesaid] Warning: the stats token is shorter than ${MIN_RECOMMENDED_TOKEN_LENGTH} characters (${token.length}). Short tokens are vulnerable to brute-force attacks against the /stats endpoint. Consider generating a strong token with: \`openssl rand -hex 32\`. You can also rate-limit /stats at your reverse proxy or CDN.`
+    );
+  }
+  const snapshotPath = options.snapshotPath ?? env.STATS_SNAPSHOT_PATH ?? DEFAULT_SNAPSHOT_PATH;
+  const flushIntervalMs = options.flushIntervalMs ?? parseIntOr(env.STATS_FLUSH_INTERVAL_MS, DEFAULT_FLUSH_INTERVAL_MS);
+  requirePositiveInt(flushIntervalMs, "flushIntervalMs");
+  if (flushIntervalMs < MIN_FLUSH_INTERVAL_MS) {
+    throw new Error(
+      `[statswhatshesaid] flushIntervalMs must be at least ${MIN_FLUSH_INTERVAL_MS} ms to avoid hammering the persist layer; got ${flushIntervalMs}.`
+    );
+  }
+  const rawEndpointPath = options.endpointPath ?? env.STATS_ENDPOINT_PATH ?? DEFAULT_ENDPOINT_PATH;
+  const endpointPath = normalizePath(rawEndpointPath);
+  if (!ENDPOINT_PATH_RE.test(endpointPath)) {
+    throw new Error(
+      `[statswhatshesaid] Invalid endpointPath: ${JSON.stringify(rawEndpointPath)}. Must match /^\\/[A-Za-z0-9\\-._~/]*$/.`
+    );
+  }
+  const historyDays = options.historyDays ?? DEFAULT_HISTORY_DAYS;
+  requireNonNegativeInt(historyDays, "historyDays");
+  const maxHistoryDays = options.maxHistoryDays ?? DEFAULT_MAX_HISTORY_DAYS;
+  requireNonNegativeInt(maxHistoryDays, "maxHistoryDays");
+  const filterBots = options.filterBots ?? true;
+  const persist = options.persist ?? null;
+  const rawTrustProxy = options.trustProxy ?? parseIntOr(env.STATS_TRUST_PROXY, DEFAULT_TRUST_PROXY, true);
+  if (!Number.isInteger(rawTrustProxy) || rawTrustProxy < 0) {
+    throw new Error(
+      `[statswhatshesaid] Invalid trustProxy value: ${rawTrustProxy}. Must be a non-negative integer (0, 1, 2, ...).`
+    );
+  }
+  return {
+    token,
+    snapshotPath,
+    persist,
+    flushIntervalMs,
+    endpointPath,
+    historyDays,
+    maxHistoryDays,
+    filterBots,
+    trustProxy: rawTrustProxy
+  };
+}
+function requirePositiveInt(value, name) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(
+      `[statswhatshesaid] ${name} must be a positive integer; got ${value}.`
+    );
+  }
+}
+function requireNonNegativeInt(value, name) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `[statswhatshesaid] ${name} must be a non-negative integer; got ${value}.`
+    );
+  }
+}
+function parseIntOr(value, fallback, allowZero = false) {
+  if (!value) return fallback;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n)) return fallback;
+  if (allowZero ? n < 0 : n <= 0) return fallback;
+  return n;
+}
+function normalizePath(p) {
+  if (!p.startsWith("/")) return `/${p}`;
+  return p;
+}
+
+// src/identity.ts
+var import_node_crypto = require("crypto");
+function utcDateString(d) {
+  return d.toISOString().slice(0, 10);
+}
+var DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function isValidUtcDate(s) {
+  const m = DATE_RE.exec(s);
+  if (!m) return false;
+  const year = Number(m[1]);
+  const month = Number(m[2]);
+  const day = Number(m[3]);
+  const d = new Date(Date.UTC(year, month - 1, day));
+  return d.getUTCFullYear() === year && d.getUTCMonth() === month - 1 && d.getUTCDate() === day;
+}
+var SALT_BYTES = 32;
+function generateSalt() {
+  return (0, import_node_crypto.randomBytes)(SALT_BYTES);
+}
+var UNKNOWN_PEER = "0.0.0.0";
+function extractIp(headers, trustProxy) {
+  if (trustProxy < 1) return UNKNOWN_PEER;
+  const xff = headers.get("x-forwarded-for");
+  if (!xff) return UNKNOWN_PEER;
+  const entries = xff.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (entries.length < trustProxy) return UNKNOWN_PEER;
+  return entries[entries.length - trustProxy];
+}
+function computeVisitorHash(ip, ua, salt) {
+  const ipBuf = Buffer.from(ip, "utf8");
+  const uaBuf = Buffer.from(ua, "utf8");
+  const lenBuf = Buffer.alloc(8);
+  lenBuf.writeUInt32BE(ipBuf.length, 0);
+  lenBuf.writeUInt32BE(uaBuf.length, 4);
+  return (0, import_node_crypto.createHash)("sha256").update(lenBuf).update(ipBuf).update(uaBuf).update(salt).digest();
+}
+function scheduleMidnightTimer(onMidnight, now = /* @__PURE__ */ new Date()) {
+  let timer = null;
+  let interval = null;
+  const msUntilNext = msUntilUtcMidnight(now) + 1e3;
+  timer = setTimeout(() => {
+    try {
+      onMidnight();
+    } catch {
+    }
+    interval = setInterval(
+      () => {
+        try {
+          onMidnight();
+        } catch {
+        }
+      },
+      24 * 60 * 60 * 1e3
+    );
+    interval.unref?.();
+  }, msUntilNext);
+  timer.unref?.();
+  return () => {
+    if (timer) clearTimeout(timer);
+    if (interval) clearInterval(interval);
+    timer = null;
+    interval = null;
+  };
+}
+function msUntilUtcMidnight(now) {
+  const next = Date.UTC(
+    now.getUTCFullYear(),
+    now.getUTCMonth(),
+    now.getUTCDate() + 1,
+    0,
+    0,
+    0,
+    0
+  );
+  return next - now.getTime();
+}
+
+// src/endpoint.ts
+var import_node_crypto2 = require("crypto");
+var import_server = require("next/server");
+function handleStatsEndpoint(req, runtime) {
+  const provided = extractAuthToken(req);
+  if (!provided || !constantTimeEqual(provided, runtime.config.token)) {
+    return new import_server.NextResponse("Unauthorized", { status: 401 });
+  }
+  runtime.store.rollOverIfNeeded();
+  const body = {
+    today: {
+      date: runtime.store.today,
+      uniqueVisitors: runtime.store.estimateToday()
+    },
+    history: runtime.store.getHistoryDesc(runtime.config.historyDays),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return import_server.NextResponse.json(body, {
+    headers: { "cache-control": "no-store" }
+  });
+}
+function extractAuthToken(req) {
+  const auth = req.headers.get("authorization");
+  if (auth) {
+    const match = /^Bearer\s+(\S+)\s*$/i.exec(auth);
+    if (match) return match[1];
+  }
+  return req.nextUrl.searchParams.get("t");
+}
+function constantTimeEqual(a, b) {
+  const ah = (0, import_node_crypto2.createHash)("sha256").update(a, "utf8").digest();
+  const bh = (0, import_node_crypto2.createHash)("sha256").update(b, "utf8").digest();
+  return (0, import_node_crypto2.timingSafeEqual)(ah, bh);
+}
+
+// src/snapshot.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/hll.ts
+var P = 14;
+var HLL_REGISTER_COUNT = 1 << P;
+var TAIL_HIGH_BITS = 32 - P;
+var TAIL_HIGH_MASK = (1 << TAIL_HIGH_BITS) - 1;
+var TAIL_TOTAL_BITS = 64 - P;
+var MAX_RANK = TAIL_TOTAL_BITS + 1;
+var ALPHA_M = 0.7213 / (1 + 1.079 / HLL_REGISTER_COUNT);
+var HyperLogLog = class _HyperLogLog {
+  registers;
+  constructor(registers) {
+    if (registers) {
+      if (registers.length !== HLL_REGISTER_COUNT) {
+        throw new Error(
+          `[statswhatshesaid] HLL registers must be ${HLL_REGISTER_COUNT} bytes, got ${registers.length}`
+        );
+      }
+      this.registers = new Uint8Array(registers);
+    } else {
+      this.registers = new Uint8Array(HLL_REGISTER_COUNT);
+    }
+  }
+  /**
+   * Add a 64-bit hash (the first 8 bytes of a larger buffer are fine) to the
+   * sketch. This is the only mutating call on the hot path.
+   */
+  addHashBuffer(buf) {
+    const first = buf.readUInt32BE(0);
+    const second = buf.readUInt32BE(4);
+    const idx = first >>> TAIL_HIGH_BITS;
+    const tailHigh = first & TAIL_HIGH_MASK;
+    let rank;
+    if (tailHigh !== 0) {
+      rank = Math.clz32(tailHigh) - 14 + 1;
+    } else if (second !== 0) {
+      rank = 18 + Math.clz32(second) + 1;
+    } else {
+      rank = MAX_RANK;
+    }
+    if (rank > this.registers[idx]) {
+      this.registers[idx] = rank;
+    }
+  }
+  /**
+   * Estimated number of distinct items inserted.
+   * Applies the linear-counting correction for small cardinalities.
+   */
+  estimate() {
+    const m = HLL_REGISTER_COUNT;
+    let sum = 0;
+    let zeros = 0;
+    for (let i = 0; i < m; i++) {
+      const r = this.registers[i];
+      sum += 2 ** -r;
+      if (r === 0) zeros++;
+    }
+    let estimate = ALPHA_M * m * m / sum;
+    if (estimate <= 2.5 * m && zeros > 0) {
+      estimate = m * Math.log(m / zeros);
+    }
+    return Math.round(estimate);
+  }
+  /** Deep copy the register array for serialization. */
+  cloneRegisters() {
+    return new Uint8Array(this.registers);
+  }
+  static fromRegisters(registers) {
+    return new _HyperLogLog(registers);
+  }
+};
+
+// src/snapshot.ts
+var FileSnapshotAdapter = class {
+  path;
+  constructor(path) {
+    this.path = path;
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(path), { recursive: true });
+  }
+  load() {
+    let text;
+    try {
+      text = (0, import_node_fs.readFileSync)(this.path, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return null;
+    }
+    if (!isValidSnapshot(parsed)) return null;
+    return parsed;
+  }
+  save(snap) {
+    const tmp = `${this.path}.tmp`;
+    (0, import_node_fs.writeFileSync)(tmp, JSON.stringify(snap), { mode: 384 });
+    (0, import_node_fs.renameSync)(tmp, this.path);
+  }
+};
+function isValidSnapshot(x) {
+  if (!x || typeof x !== "object") return false;
+  const o = x;
+  if (o.version !== 1) return false;
+  if (typeof o.today !== "string" || !isValidUtcDate(o.today)) return false;
+  if (typeof o.salt !== "string") return false;
+  if (typeof o.hllRegisters !== "string") return false;
+  if (typeof o.history !== "object" || o.history === null || Array.isArray(o.history)) {
+    return false;
+  }
+  const expectedBase64 = Math.ceil(HLL_REGISTER_COUNT / 3) * 4;
+  if (o.hllRegisters.length !== expectedBase64) return false;
+  return true;
+}
+
+// src/store.ts
+var VisitorStore = class _VisitorStore {
+  _today;
+  _salt;
+  _hll;
+  _history;
+  _dirty;
+  constructor(args) {
+    this._today = args.today;
+    this._salt = args.salt;
+    this._hll = args.hll;
+    this._history = args.history;
+    this._dirty = args.dirty;
+  }
+  static fresh(today) {
+    return new _VisitorStore({
+      today,
+      salt: generateSalt(),
+      hll: new HyperLogLog(),
+      history: /* @__PURE__ */ new Map(),
+      dirty: true
+    });
+  }
+  /**
+   * Build a store from a persisted snapshot. If the snapshot's `today` no
+   * longer matches the current UTC date, the snapshot's HLL is finalized into
+   * history and a fresh HLL + salt is created for `currentDate`.
+   *
+   * This path is the main "untrusted JSON" boundary — defensive at every
+   * step. Any decode/validation failure degrades gracefully: we keep what
+   * we can of history and start today fresh.
+   */
+  static fromSnapshot(snap, currentDate) {
+    const history = sanitizeHistory(snap.history, currentDate);
+    if (snap.today === currentDate) {
+      try {
+        const salt = decodeSalt(snap.salt);
+        const registers = decodeRegisters(snap.hllRegisters);
+        const hll = new HyperLogLog(registers);
+        return new _VisitorStore({
+          today: currentDate,
+          salt,
+          hll,
+          history,
+          dirty: false
+        });
+      } catch {
+        return new _VisitorStore({
+          today: currentDate,
+          salt: generateSalt(),
+          hll: new HyperLogLog(),
+          history,
+          dirty: true
+        });
+      }
+    }
+    try {
+      const registers = decodeRegisters(snap.hllRegisters);
+      const oldHll = new HyperLogLog(registers);
+      history.set(snap.today, oldHll.estimate());
+    } catch {
+    }
+    return new _VisitorStore({
+      today: currentDate,
+      salt: generateSalt(),
+      hll: new HyperLogLog(),
+      history,
+      dirty: true
+    });
+  }
+  get today() {
+    return this._today;
+  }
+  get dirty() {
+    return this._dirty;
+  }
+  /** Estimated unique visitors so far today. */
+  estimateToday() {
+    return this._hll.estimate();
+  }
+  /** Hot path. */
+  track(ip, ua) {
+    const hash = computeVisitorHash(ip, ua, this._salt);
+    this._hll.addHashBuffer(hash);
+    this._dirty = true;
+  }
+  /**
+   * If the current UTC date has moved past `this._today`, finalize the
+   * previous day into history and start a fresh HLL + salt for the new day.
+   * Returns true if a rollover happened.
+   */
+  rollOverIfNeeded(now = /* @__PURE__ */ new Date()) {
+    const current = utcDateString(now);
+    if (current === this._today) return false;
+    this._history.set(this._today, this._hll.estimate());
+    this._today = current;
+    this._salt = generateSalt();
+    this._hll = new HyperLogLog();
+    this._dirty = true;
+    return true;
+  }
+  /** Drop history entries older than `maxDays` days from today (inclusive). */
+  trimHistory(maxDays) {
+    if (maxDays <= 0) return;
+    if (this._history.size <= maxDays) return;
+    const sortedDesc = [...this._history.keys()].sort().reverse();
+    for (let i = maxDays; i < sortedDesc.length; i++) {
+      this._history.delete(sortedDesc[i]);
+    }
+    this._dirty = true;
+  }
+  /** History (excluding today) in descending date order, capped at `limit`. */
+  getHistoryDesc(limit) {
+    const rows = [];
+    for (const [date, count] of this._history) {
+      if (date === this._today) continue;
+      rows.push({ date, uniqueVisitors: count });
+    }
+    rows.sort((a, b) => a.date < b.date ? 1 : a.date > b.date ? -1 : 0);
+    return rows.slice(0, limit);
+  }
+  toSnapshot() {
+    return {
+      version: 1,
+      today: this._today,
+      salt: this._salt.toString("base64"),
+      hllRegisters: Buffer.from(this._hll.cloneRegisters()).toString("base64"),
+      history: Object.fromEntries(this._history)
+    };
+  }
+  markClean() {
+    this._dirty = false;
+  }
+};
+function decodeSalt(saltBase64) {
+  const salt = Buffer.from(saltBase64, "base64");
+  if (salt.length !== SALT_BYTES) {
+    throw new Error(
+      `invalid snapshot salt: expected ${SALT_BYTES} bytes, got ${salt.length}`
+    );
+  }
+  return salt;
+}
+function decodeRegisters(registersBase64) {
+  const buf = Buffer.from(registersBase64, "base64");
+  if (buf.length !== HLL_REGISTER_COUNT) {
+    throw new Error(
+      `invalid snapshot registers: expected ${HLL_REGISTER_COUNT} bytes, got ${buf.length}`
+    );
+  }
+  return new Uint8Array(buf);
+}
+function sanitizeHistory(raw, currentDate) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [date, count] of Object.entries(raw)) {
+    if (!isValidUtcDate(date)) continue;
+    if (date === currentDate) continue;
+    if (typeof count !== "number") continue;
+    if (!Number.isFinite(count) || !Number.isInteger(count)) continue;
+    if (count < 0) continue;
+    out.set(date, count);
+  }
+  return out;
+}
+
+// src/lifecycle.ts
+function getOrInitRuntime(config) {
+  if (globalThis.__statswhatshesaid__) return globalThis.__statswhatshesaid__;
+  assertNodeRuntime();
+  const persist = config.persist ?? new FileSnapshotAdapter(config.snapshotPath);
+  const today = utcDateString(/* @__PURE__ */ new Date());
+  const loaded = safeLoad(persist);
+  const store = loaded ? VisitorStore.fromSnapshot(loaded, today) : VisitorStore.fresh(today);
+  store.trimHistory(config.maxHistoryDays);
+  let shuttingDown = false;
+  let flushTimer = null;
+  let cancelMidnight = null;
+  const flush = () => {
+    if (!store.dirty) return;
+    try {
+      persist.save(store.toSnapshot());
+      store.markClean();
+    } catch (err) {
+      console.error("[statswhatshesaid] flush failed:", err);
+    }
+  };
+  const tick = () => {
+    try {
+      if (store.rollOverIfNeeded()) {
+        store.trimHistory(config.maxHistoryDays);
+      }
+    } catch (err) {
+      console.error("[statswhatshesaid] rollover failed:", err);
+    }
+    flush();
+  };
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (flushTimer) clearInterval(flushTimer);
+    if (cancelMidnight) cancelMidnight();
+    process.removeListener("SIGTERM", shutdown);
+    process.removeListener("SIGINT", shutdown);
+    process.removeListener("beforeExit", shutdown);
+    try {
+      flush();
+    } catch {
+    }
+    try {
+      if (config.persist == null) {
+      }
+    } catch {
+    }
+    if (globalThis.__statswhatshesaid__ === runtime) {
+      globalThis.__statswhatshesaid__ = void 0;
+    }
+  };
+  flushTimer = setInterval(tick, config.flushIntervalMs);
+  flushTimer.unref?.();
+  cancelMidnight = scheduleMidnightTimer(tick);
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+  process.on("beforeExit", shutdown);
+  const runtime = { config, store, persist, flush, shutdown };
+  globalThis.__statswhatshesaid__ = runtime;
+  flush();
+  return runtime;
+}
+function safeLoad(persist) {
+  try {
+    return persist.load();
+  } catch (err) {
+    console.error("[statswhatshesaid] snapshot load failed:", err);
+    return null;
+  }
+}
+function assertNodeRuntime() {
+  if (typeof process === "undefined" || !process.versions || !process.versions.node) {
+    throw new Error(
+      "[statswhatshesaid] This library requires the Node.js runtime. Set `export const config = { runtime: 'nodejs' }` in your middleware.ts (requires Next.js 15.2 or newer)."
+    );
+  }
+}
+
+// src/middleware.ts
+function createMiddleware(options = {}) {
+  let resolved = null;
+  return function statsMiddleware(req) {
+    if (!resolved) resolved = resolveConfig(options);
+    const runtime = getOrInitRuntime(resolved);
+    if (req.nextUrl.pathname === resolved.endpointPath) {
+      return handleStatsEndpoint(req, runtime);
+    }
+    trackRequestInternal(req, runtime);
+    return import_server2.NextResponse.next();
+  };
+}
+function trackRequest(req, options = {}) {
+  const config = resolveConfig(options);
+  const runtime = getOrInitRuntime(config);
+  trackRequestInternal(req, runtime);
+}
+var MAX_UA_LENGTH = 512;
+function trackRequestInternal(req, runtime) {
+  const rawUa = req.headers.get("user-agent") ?? "";
+  const ua = rawUa.length > MAX_UA_LENGTH ? rawUa.slice(0, MAX_UA_LENGTH) : rawUa;
+  if (runtime.config.filterBots && isBot(ua)) return;
+  const ip = extractIp(req.headers, runtime.config.trustProxy);
+  runtime.store.track(ip, ua);
+}
+
+// src/index.ts
+var stats = {
+  middleware: (options) => createMiddleware(options),
+  track: trackRequest
+};
+var index_default = stats;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileSnapshotAdapter
+});
+//# sourceMappingURL=index.cjs.map