@entreprenoid/analytics 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1289 @@
+'use strict';
+
+// src/core/breaker.ts
+function createBreaker(options = {}) {
+  const failureThreshold = options.failureThreshold ?? 5;
+  const openMs = options.openMs ?? 3e4;
+  const now = options.now ?? (() => Date.now());
+  let consecutiveFailures = 0;
+  let openedAt = 0;
+  let state = "closed";
+  return {
+    get state() {
+      return state;
+    },
+    allow() {
+      if (state === "closed") return true;
+      if (state === "half-open") return true;
+      if (now() - openedAt >= openMs) {
+        state = "half-open";
+        return true;
+      }
+      return false;
+    },
+    success() {
+      consecutiveFailures = 0;
+      state = "closed";
+    },
+    failure() {
+      consecutiveFailures += 1;
+      if (state === "half-open" || consecutiveFailures >= failureThreshold) {
+        state = "open";
+        openedAt = now();
+      }
+    }
+  };
+}
+
+// src/core/config.ts
+var UNSET_SITE_ID = "unset";
+var DEFAULTS = {
+  batchSize: 20,
+  maxBatchSize: 100,
+  flushIntervalMs: 2e3,
+  maxQueueEvents: 1e3,
+  maxBodyBytes: 512 * 1024,
+  requestTimeoutMs: 2e3
+};
+var PUBLIC_ENV_PREFIXES = ["NEXT_PUBLIC_", "VITE_", "PUBLIC_", "REACT_APP_", "NUXT_PUBLIC_"];
+var EntreprenoidConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EntreprenoidConfigError";
+  }
+};
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function boolFromEnv(raw) {
+  if (raw === void 0) return void 0;
+  const v = raw.trim().toLowerCase();
+  if (v === "1" || v === "true" || v === "yes") return true;
+  if (v === "0" || v === "false" || v === "no") return false;
+  return void 0;
+}
+function resolveConfig(options = {}, env = typeof process === "undefined" ? {} : process.env) {
+  for (const prefix of PUBLIC_ENV_PREFIXES) {
+    const name = `${prefix}ENTREPRENOID_SERVER_KEY`;
+    if (env[name]) {
+      throw new EntreprenoidConfigError(
+        `${name} is set. The "${prefix}" prefix inlines a value into client-side JavaScript, so this key is already public. Revoke it, then set ENTREPRENOID_SERVER_KEY instead (no prefix) so it stays on the server.`
+      );
+    }
+  }
+  const ingestUrl = options.ingestUrl ?? env["ENTREPRENOID_INGEST_URL"] ?? "";
+  const serverKey = options.serverKey ?? env["ENTREPRENOID_SERVER_KEY"] ?? "";
+  const siteId = options.siteId ?? env["ENTREPRENOID_SITE_ID"] ?? UNSET_SITE_ID;
+  const enabled = options.enabled ?? boolFromEnv(env["ENTREPRENOID_ENABLED"]) ?? true;
+  const debug = options.debug ?? boolFromEnv(env["ENTREPRENOID_DEBUG"]) ?? false;
+  let disabled = null;
+  if (typeof window !== "undefined") {
+    disabled = "browser-environment";
+  } else if (!enabled) {
+    disabled = "explicitly-disabled";
+  } else if (!ingestUrl) {
+    disabled = "missing-url";
+  } else if (!serverKey) {
+    disabled = "missing-key";
+  }
+  return Object.freeze({
+    ingestUrl,
+    serverKey,
+    siteId,
+    debug,
+    batchSize: clamp(options.batchSize ?? DEFAULTS.batchSize, 1, DEFAULTS.maxBatchSize),
+    flushIntervalMs: clamp(options.flushIntervalMs ?? DEFAULTS.flushIntervalMs, 100, 6e4),
+    maxQueueEvents: clamp(options.maxQueueEvents ?? DEFAULTS.maxQueueEvents, 1, 1e5),
+    maxBodyBytes: clamp(options.maxBodyBytes ?? DEFAULTS.maxBodyBytes, 1024, DEFAULTS.maxBodyBytes),
+    requestTimeoutMs: clamp(options.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs, 100, 3e4),
+    routeTemplate: options.routeTemplate,
+    redactPatterns: options.redactPatterns ?? [],
+    // ⚠️ Defaults to TRUE. An `?? true` that a refactor turns into `?? false`
+    // is the entire bug returning, so `config.test.ts` asserts the default.
+    redactHighEntropyPaths: options.redactHighEntropyPaths ?? true,
+    isInternal: options.isInternal,
+    disabled
+  });
+}
+function redact(text) {
+  return text.replace(/\bep_(live|test)_server_[A-Za-z0-9_-]+/g, "ep_$1_server_[redacted]");
+}
+
+// src/core/encode.ts
+var MAX_BODY_BYTES = 512 * 1024;
+var OPEN = '{"events":[';
+var CLOSE = "]}";
+var byteLength = typeof TextEncoder === "function" ? (s) => new TextEncoder().encode(s).length : (
+  // Node 18+ always has TextEncoder; this is here so the module cannot
+  // throw at import time on an exotic runtime, which would take the host
+  // application down with it.
+  (s) => s.length
+);
+function encodeBatch(events, maxBytes = MAX_BODY_BYTES) {
+  if (events.length === 0) {
+    return { body: OPEN + CLOSE, taken: 0, oversized: false };
+  }
+  const overhead = byteLength(OPEN) + byteLength(CLOSE);
+  let used = overhead;
+  const parts = [];
+  for (const event of events) {
+    const encoded = JSON.stringify(event);
+    const cost = byteLength(encoded) + (parts.length > 0 ? 1 : 0);
+    if (used + cost > maxBytes) break;
+    parts.push(encoded);
+    used += cost;
+  }
+  return {
+    body: OPEN + parts.join(",") + CLOSE,
+    taken: parts.length,
+    oversized: parts.length === 0
+  };
+}
+
+// src/core/queue.ts
+var BoundedQueue = class {
+  capacity;
+  #items;
+  #head = 0;
+  #size = 0;
+  #dropped = 0;
+  constructor(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new TypeError(`capacity must be a positive integer, got ${capacity}`);
+    }
+    this.capacity = capacity;
+    this.#items = new Array(capacity);
+  }
+  get size() {
+    return this.#size;
+  }
+  /** How many events have been discarded because the buffer was full. */
+  get dropped() {
+    return this.#dropped;
+  }
+  push(item) {
+    if (this.#size === this.capacity) {
+      this.#items[this.#head] = item;
+      this.#head = (this.#head + 1) % this.capacity;
+      this.#dropped += 1;
+      return;
+    }
+    this.#items[(this.#head + this.#size) % this.capacity] = item;
+    this.#size += 1;
+  }
+  /** The first `max` items, without removing them. */
+  peek(max) {
+    const n = Math.min(max, this.#size);
+    const out = new Array(n);
+    for (let i = 0; i < n; i += 1) {
+      out[i] = this.#items[(this.#head + i) % this.capacity];
+    }
+    return out;
+  }
+  /** Remove the first `n` items. Called only after they are safely sent. */
+  commit(n) {
+    const count = Math.min(n, this.#size);
+    for (let i = 0; i < count; i += 1) {
+      this.#items[(this.#head + i) % this.capacity] = void 0;
+    }
+    this.#head = (this.#head + count) % this.capacity;
+    this.#size -= count;
+  }
+  /** Reset the drop counter, once the count has been reported on the wire. */
+  clearDropped() {
+    this.#dropped = 0;
+  }
+};
+
+// src/core/safe.ts
+function safe(fn, onError) {
+  try {
+    fn();
+  } catch (error) {
+    try {
+      onError?.(error);
+    } catch {
+    }
+  }
+}
+async function safeAsync(fn, onError) {
+  try {
+    await fn();
+  } catch (error) {
+    try {
+      onError?.(error);
+    } catch {
+    }
+  }
+}
+
+// src/core/transport.ts
+function outcomeForStatus(status, retryAfterMs) {
+  if (status >= 200 && status < 300) return { outcome: "accepted", status };
+  if (status === 408 || status === 429 || status >= 500) {
+    return retryAfterMs === void 0 ? { outcome: "retryable", status } : { outcome: "retryable", status, retryAfterMs };
+  }
+  return { outcome: "rejected", status };
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const date = Date.parse(value);
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+function fetchTransport(url) {
+  return {
+    async send(body, headers, signal) {
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body,
+          signal,
+          // Never follow a redirect: this request carries a bearer token, and
+          // a redirect is an instruction from the network to send that
+          // credential somewhere we did not choose.
+          redirect: "error",
+          keepalive: false
+        });
+        return outcomeForStatus(
+          response.status,
+          parseRetryAfter(response.headers.get("retry-after"))
+        );
+      } catch {
+        return { outcome: "retryable" };
+      }
+    }
+  };
+}
+
+// src/core/collector.ts
+var MAX_RETRIES = 2;
+function defaultSetTimer(fn, ms) {
+  const handle = setInterval(fn, ms);
+  handle.unref?.();
+  return { cancel: () => clearInterval(handle) };
+}
+function createCollector(config, deps = {}) {
+  const log = deps.log ?? ((message) => console.warn(redact(message)));
+  const debug = (message) => {
+    if (config.debug) log(`[entreprenoid] ${message}`);
+  };
+  if (config.disabled) {
+    debug(`collection disabled: ${config.disabled}`);
+    const noop = {
+      record: () => {
+      },
+      flush: async () => {
+      },
+      stats: { queued: 0, dropped: 0, sent: 0, failed: 0, breaker: "closed" },
+      close: () => {
+      }
+    };
+    return noop;
+  }
+  const queue = new BoundedQueue(config.maxQueueEvents);
+  const transport = deps.transport ?? fetchTransport(config.ingestUrl);
+  const breaker = deps.breaker ?? createBreaker();
+  const random = deps.random ?? Math.random;
+  const setTimer = deps.setTimer ?? defaultSetTimer;
+  let sent = 0;
+  let failed = 0;
+  let inFlight = null;
+  const timer = setTimer(() => {
+    void flush();
+  }, config.flushIntervalMs);
+  function headers() {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${config.serverKey}`
+    };
+  }
+  async function sendOnce(body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.requestTimeoutMs);
+    timeout.unref?.();
+    try {
+      return await transport.send(body, headers(), controller.signal);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  function backoffMs(attempt, retryAfterMs) {
+    if (retryAfterMs !== void 0) return Math.min(retryAfterMs, 3e4);
+    return random() * Math.min(5e3, 200 * 3 ** attempt);
+  }
+  const sleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+  });
+  async function flushOnce() {
+    if (queue.size === 0) return;
+    if (!breaker.allow()) {
+      debug("breaker open, skipping flush");
+      return;
+    }
+    const candidates = queue.peek(config.batchSize);
+    const droppedSoFar = queue.dropped;
+    if (droppedSoFar > 0 && candidates[0]) {
+      candidates[0] = {
+        ...candidates[0],
+        sdk: { ...candidates[0].sdk, dropped: droppedSoFar }
+      };
+    }
+    const encoded = encodeBatch(candidates, config.maxBodyBytes);
+    if (encoded.oversized) {
+      queue.commit(1);
+      debug("dropped one event larger than the body limit");
+      return;
+    }
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+      const result = await sendOnce(encoded.body);
+      if (result.outcome === "accepted") {
+        queue.commit(encoded.taken);
+        if (droppedSoFar > 0) queue.clearDropped();
+        sent += encoded.taken;
+        breaker.success();
+        return;
+      }
+      if (result.outcome === "rejected") {
+        queue.commit(encoded.taken);
+        failed += encoded.taken;
+        debug(`batch rejected with ${result.status}; dropped ${encoded.taken} event(s)`);
+        return;
+      }
+      if (attempt === MAX_RETRIES) break;
+      await sleep(backoffMs(attempt, result.retryAfterMs));
+    }
+    failed += encoded.taken;
+    breaker.failure();
+    debug(`batch failed after ${MAX_RETRIES + 1} attempt(s); ${queue.size} event(s) still buffered`);
+  }
+  function flush() {
+    if (inFlight) return inFlight;
+    inFlight = safeAsync(flushOnce, (error) => debug(`flush failed: ${String(error)}`)).finally(
+      () => {
+        inFlight = null;
+      }
+    );
+    return inFlight;
+  }
+  return {
+    record(event) {
+      try {
+        queue.push(event);
+      } catch {
+      }
+    },
+    flush,
+    get stats() {
+      return {
+        queued: queue.size,
+        dropped: queue.dropped,
+        sent,
+        failed,
+        breaker: breaker.state
+      };
+    },
+    close() {
+      timer.cancel();
+    }
+  };
+}
+
+// src/observe/redact.ts
+var MIN_LENGTH = 16;
+var MIN_ENTROPY_BITS = 3;
+var PLACEHOLDER = /^[:*[{<]/;
+var HAS_EXTENSION = /\.[A-Za-z0-9]{1,8}$/;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var CUID = /^c[a-z0-9]{20,31}$/;
+var JWT = /^ey[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+var LONG_HEX = /^[0-9a-f]{16,}$/i;
+var ALL_LOWER_ALPHA = /^[a-z]+$/;
+function entropyBits(value) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const ch of value) counts.set(ch, (counts.get(ch) ?? 0) + 1);
+  let bits = 0;
+  for (const n of counts.values()) {
+    const p = n / value.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
+function dense(value) {
+  if (value.length < MIN_LENGTH) return false;
+  if (ALL_LOWER_ALPHA.test(value)) return false;
+  const classes = Number(/[a-z]/.test(value)) + Number(/[A-Z]/.test(value)) + Number(/[0-9]/.test(value)) + Number(/[^A-Za-z0-9]/.test(value));
+  if (classes < 3) return false;
+  return entropyBits(value) >= MIN_ENTROPY_BITS;
+}
+function slugLike(segment) {
+  const parts = segment.split(/[-_]/).filter(Boolean);
+  if (parts.length < 2) return false;
+  const tidy = parts.every((p) => /^[a-z]+$/.test(p) || /^[0-9]+$/.test(p));
+  const hasWord = parts.some((p) => /^[a-z]{2,}$/.test(p));
+  return tidy && hasWord;
+}
+function looksLikeSecret(segment) {
+  if (segment.length < MIN_LENGTH) return false;
+  if (PLACEHOLDER.test(segment)) return false;
+  if (HAS_EXTENSION.test(segment)) return false;
+  if (UUID.test(segment) || CUID.test(segment) || JWT.test(segment) || LONG_HEX.test(segment)) {
+    return true;
+  }
+  for (const part of segment.split(/[-_.]/)) {
+    if (dense(part)) return true;
+  }
+  if (slugLike(segment)) return false;
+  return dense(segment);
+}
+var REDACTED = "[redacted]";
+function redactPath(path, patterns, useDefault) {
+  if (patterns.length === 0 && !useDefault) return { path, redacted: false };
+  let redacted = false;
+  const out = path.split("/").map((segment) => {
+    if (!segment) return segment;
+    const matchesCustom = patterns.some((re) => {
+      re.lastIndex = 0;
+      return re.test(segment);
+    });
+    if (matchesCustom || useDefault && looksLikeSecret(segment)) {
+      redacted = true;
+      return REDACTED;
+    }
+    return segment;
+  }).join("/");
+  return { path: out, redacted };
+}
+
+// src/observe/request.ts
+var CAMPAIGN_PARAMS = ["utm_source", "utm_medium", "utm_campaign", "utm_content"];
+var CLICK_ID_PARAMS = ["gclid", "fbclid", "msclkid"];
+function normalisePath(rawPath, redactPatterns = []) {
+  const path = cleanPath(rawPath);
+  return redactPatterns.length > 0 ? redactPath(path, redactPatterns, false).path : path;
+}
+function cleanPath(rawPath) {
+  let path = rawPath;
+  const hash = path.indexOf("#");
+  if (hash !== -1) path = path.slice(0, hash);
+  const query = path.indexOf("?");
+  if (query !== -1) path = path.slice(0, query);
+  if (path === "") path = "/";
+  if (!path.startsWith("/")) path = `/${path}`;
+  path = path.replace(/\/{2,}/g, "/");
+  if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+  return path.length > 1024 ? path.slice(0, 1024) : path;
+}
+function referrerOrigin(referer) {
+  if (!referer) return void 0;
+  try {
+    const url = new URL(referer);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+    return url.origin.slice(0, 255);
+  } catch {
+    return void 0;
+  }
+}
+function campaignFrom(params) {
+  let found = false;
+  const campaign = {};
+  for (const name of CAMPAIGN_PARAMS) {
+    const value = params.get(name);
+    if (value) {
+      campaign[name.slice(4)] = value.slice(0, 120);
+      found = true;
+    }
+  }
+  return found ? campaign : void 0;
+}
+function clickIdFrom(params) {
+  for (const name of CLICK_ID_PARAMS) {
+    if (params.has(name)) return name;
+  }
+  return void 0;
+}
+function observeRequest(facts, config) {
+  const cleaned = cleanPath(facts.url);
+  let params = new URLSearchParams();
+  try {
+    params = new URL(facts.url, "http://x").searchParams;
+  } catch {
+  }
+  const templated = config.routeTemplate?.(cleaned);
+  const { path, redacted } = redactPath(
+    cleaned,
+    config.redactPatterns,
+    config.redactHighEntropyPaths
+  );
+  const observed = {
+    method: facts.method.slice(0, 10).toUpperCase(),
+    path
+  };
+  if (templated) {
+    const safeRoute = redactPath(templated, config.redactPatterns, config.redactHighEntropyPaths);
+    observed.route = safeRoute.path.slice(0, 512);
+    if (safeRoute.redacted) observed.pathRedacted = true;
+  }
+  if (redacted) observed.pathRedacted = true;
+  if (facts.host) observed.host = facts.host.slice(0, 253);
+  if (facts.protocol) observed.protocol = facts.protocol;
+  if (facts.userAgent) observed.userAgent = facts.userAgent.slice(0, 512);
+  const origin = referrerOrigin(facts.referer);
+  if (origin) observed.referrerOrigin = origin;
+  const campaign = campaignFrom(params);
+  if (campaign) observed.campaign = campaign;
+  const clickIdType = clickIdFrom(params);
+  if (clickIdType) observed.clickIdType = clickIdType;
+  if (config.isInternal?.(observed)) observed.internal = true;
+  return observed;
+}
+
+// src/observe/response.ts
+function observeResponse(facts) {
+  const response = { observation: facts.observation };
+  if (facts.observation === "unknown") {
+    if (typeof facts.latencyMs === "number" && Number.isFinite(facts.latencyMs)) {
+      response.latencyMs = Math.max(0, Math.round(facts.latencyMs));
+    }
+    return response;
+  }
+  if (typeof facts.status === "number" && facts.status >= 100 && facts.status <= 599) {
+    response.status = facts.status;
+  }
+  if (facts.contentType) {
+    response.contentType = String(facts.contentType).slice(0, 255);
+  }
+  const length = typeof facts.contentLength === "string" ? Number(facts.contentLength) : facts.contentLength;
+  if (typeof length === "number" && Number.isFinite(length) && length >= 0) {
+    response.contentLength = Math.round(length);
+  }
+  if (typeof facts.latencyMs === "number" && Number.isFinite(facts.latencyMs)) {
+    response.latencyMs = Math.max(0, Math.round(facts.latencyMs));
+  }
+  return response;
+}
+
+// src/runtime.ts
+var SDK_NAME = "@entreprenoid/analytics";
+var SDK_VERSION = "0.1.0";
+function runtimeName() {
+  try {
+    const g = globalThis;
+    const deno = g["Deno"];
+    if (deno?.version?.deno) return `deno-${deno.version.deno}`;
+    const bun = g["Bun"];
+    if (bun?.version) return `bun-${bun.version}`;
+    if (typeof process !== "undefined" && process.versions?.node) {
+      return `node-${process.versions.node}`;
+    }
+    const nav = g["navigator"];
+    if (nav?.userAgent?.includes("Cloudflare-Workers")) return "workerd";
+  } catch {
+  }
+  return "unknown";
+}
+function newEventId() {
+  try {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function") return c.randomUUID();
+  } catch {
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+
+// src/serve/accept.ts
+function parseAccept(header2) {
+  if (!header2) return [];
+  const ranges = [];
+  for (const part of header2.split(",")) {
+    const segments = part.trim().split(";");
+    const type = segments[0]?.trim().toLowerCase();
+    if (!type) continue;
+    let q = 1;
+    for (const segment of segments.slice(1)) {
+      const [key, value] = segment.split("=").map((s) => s.trim().toLowerCase());
+      if (key === "q") {
+        const parsed = Number(value);
+        q = Number.isFinite(parsed) ? Math.min(1, Math.max(0, parsed)) : 1;
+      }
+    }
+    ranges.push({ type, q });
+  }
+  return ranges;
+}
+function exactQ(ranges, type) {
+  let best = 0;
+  for (const range of ranges) {
+    if (range.type === type) best = Math.max(best, range.q);
+  }
+  return best;
+}
+function effectiveQ(ranges, type) {
+  const prefix = `${type.split("/")[0]}/*`;
+  let best = 0;
+  for (const range of ranges) {
+    if (range.type === type || range.type === prefix || range.type === "*/*") {
+      best = Math.max(best, range.q);
+    }
+  }
+  return best;
+}
+var MARKDOWN_TYPES = ["text/markdown", "text/x-markdown"];
+function prefersMarkdown(header2) {
+  const ranges = parseAccept(header2);
+  if (ranges.length === 0) return false;
+  let markdown = 0;
+  for (const type of MARKDOWN_TYPES) {
+    markdown = Math.max(markdown, exactQ(ranges, type));
+  }
+  if (markdown === 0) return false;
+  const html = effectiveQ(ranges, "text/html");
+  return markdown >= html;
+}
+
+// src/serve/twin.ts
+var DISCOVERY_PATHS = ["/llms.txt", "/llms-full.txt", "/install.md"];
+var DEFAULT_TWIN_CONTENT_TYPE = "text/markdown; charset=utf-8";
+var DEFAULT_TWIN_CACHE_CONTROL = "public, max-age=3600, s-maxage=86400";
+function decideTwin(input) {
+  const method = input.method.toUpperCase();
+  if (method !== "GET" && method !== "HEAD") {
+    return { action: "pass", reason: "not_get" };
+  }
+  if (input.path.endsWith(".md")) {
+    return { action: "serve", lookupPath: stripMdSuffix(input.path), reason: "md_path" };
+  }
+  if (prefersMarkdown(input.accept)) {
+    return { action: "serve", lookupPath: input.path, reason: "accept_header" };
+  }
+  return { action: "pass", reason: "no_signal" };
+}
+function stripMdSuffix(path) {
+  const withoutSuffix = path.slice(0, -3);
+  if (withoutSuffix === "" || withoutSuffix === "/index") return "/";
+  return withoutSuffix;
+}
+function twinPathFor(path) {
+  if (path === "/") return "/index.md";
+  return `${path}.md`;
+}
+function buildTwinResponse(twin, decision, options) {
+  const headers = {
+    "content-type": twin.contentType ?? DEFAULT_TWIN_CONTENT_TYPE,
+    "cache-control": options.cacheControl ?? DEFAULT_TWIN_CACHE_CONTROL
+  };
+  if (decision.reason === "accept_header") {
+    headers["vary"] = "Accept";
+  }
+  if (twin.etag) headers["etag"] = twin.etag;
+  if (twin.lastModified) headers["last-modified"] = twin.lastModified;
+  return { status: 200, headers, body: twin.body };
+}
+function advertiseHeader(path) {
+  return `<${twinPathFor(path)}>; rel="alternate"; type="text/markdown"`;
+}
+
+// src/web.ts
+function observe(handler, options = {}) {
+  const config = resolveConfig(options);
+  const collector = options.collector ?? createCollector(config);
+  if (options.twin?.discovery) {
+    console.warn(
+      "[entreprenoid] twin.discovery is configured but the web adapter does not serve /llms.txt, /llms-full.txt or /install.md. Serve them from your own router, or use the Express adapter. See https://entreprenoid.com/install.md"
+    );
+  }
+  return async (request, ...rest) => {
+    const startedAt = Date.now();
+    let served;
+    let twinResponse;
+    if (options.twin) {
+      const url = new URL(request.url);
+      const path = normalisePath(url.pathname, config.redactPatterns);
+      const decision = decideTwin({
+        method: request.method,
+        path,
+        accept: request.headers.get("accept")
+      });
+      if (decision.action === "serve") {
+        try {
+          const found = await options.twin.resolve(decision.lookupPath);
+          if (found) {
+            const built = buildTwinResponse(found, decision, options.twin);
+            served = {
+              decision: "served",
+              reason: decision.reason,
+              format: built.headers["content-type"] ?? "text/markdown"
+            };
+            twinResponse = new Response(
+              request.method.toUpperCase() === "HEAD" ? null : built.body,
+              { status: built.status, headers: built.headers }
+            );
+          } else {
+            served = { decision: "fell_through", reason: "no_twin" };
+          }
+        } catch {
+          served = { decision: "error", reason: "resolver_error" };
+        }
+      } else {
+        served = { decision: "fell_through", reason: decision.reason };
+      }
+    }
+    const response = twinResponse ?? await handler(request, ...rest);
+    if (options.twin && !twinResponse && options.twin.advertise !== false) {
+      try {
+        const path = normalisePath(new URL(request.url).pathname, config.redactPatterns);
+        if (await options.twin.resolve(path)) {
+          response.headers.append("link", advertiseHeader(path));
+          served = { decision: "advertised", reason: "no_twin" };
+        }
+      } catch {
+      }
+    }
+    safe(() => {
+      if (config.disabled) return;
+      const url = new URL(request.url);
+      const observed = observeRequest(
+        {
+          method: request.method,
+          url: url.pathname + url.search,
+          host: url.host,
+          protocol: url.protocol === "https:" ? "https" : "http",
+          userAgent: request.headers.get("user-agent") ?? void 0,
+          referer: request.headers.get("referer") ?? void 0
+        },
+        config
+      );
+      const event = {
+        ...observed,
+        eventId: newEventId(),
+        siteId: config.siteId,
+        observedAt: new Date(startedAt).toISOString(),
+        ...served ? { serve: served } : {},
+        response: observeResponse({
+          status: response.status,
+          contentType: response.headers.get("content-type"),
+          contentLength: response.headers.get("content-length"),
+          latencyMs: Date.now() - startedAt,
+          observation: "measured"
+        }),
+        sdk: {
+          name: SDK_NAME,
+          version: SDK_VERSION,
+          adapter: "web",
+          runtime: runtimeName()
+        }
+      };
+      collector.record(event);
+    });
+    if (options.waitUntil) {
+      safe(() => options.waitUntil?.(collector.flush()));
+    }
+    return response;
+  };
+}
+
+// src/serve/discovery.ts
+function titleFor(entry) {
+  if (entry.title) return entry.title;
+  if (entry.path === "/") return "Home";
+  const last = entry.path.split("/").filter(Boolean).pop() ?? entry.path;
+  return last.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+var twinPath = (path) => path === "/" ? "/index.md" : `${path}.md`;
+function renderLlmsTxt(options) {
+  const origin = options.origin ?? "";
+  const lines = [`# ${options.siteName}`, ""];
+  if (options.description) {
+    for (const line of options.description.split("\n")) lines.push(`> ${line}`);
+    lines.push("");
+  }
+  lines.push(
+    "Every page listed here is also available as markdown: append `.md` to the path",
+    "(`/` becomes `/index.md`), or send `Accept: text/markdown`.",
+    "",
+    "## Pages",
+    ""
+  );
+  for (const entry of options.entries) {
+    const href = `${origin}${twinPath(entry.path)}`;
+    lines.push(`- [${titleFor(entry)}](${href})${entry.summary ? `: ${entry.summary}` : ""}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+async function renderLlmsFullTxt(options, resolve) {
+  const parts = [`# ${options.siteName}`, ""];
+  if (options.description) {
+    for (const line of options.description.split("\n")) parts.push(`> ${line}`);
+    parts.push("");
+  }
+  for (const entry of options.entries) {
+    let twin;
+    try {
+      twin = await resolve(entry.path);
+    } catch {
+      continue;
+    }
+    if (!twin) continue;
+    parts.push(`---`, ``, `## ${titleFor(entry)}`, ``, `Source: ${entry.path}`, ``, twin.body.trim(), ``);
+  }
+  return parts.join("\n");
+}
+function renderInstallMd(options = {}) {
+  const pkg = options.packageName ?? "@entreprenoid/analytics";
+  return `# entreprenoid install guide (for AI coding agents)
+
+You are installing **entreprenoid** \u2014 analytics for the agentic web. It records every
+request a site serves, especially from AI agents, and can serve those agents a clean
+markdown twin of each page. Collection is fire-and-forget: it never blocks and never
+fails the user's responses.
+
+## Before you start
+
+Every environment variable this package reads:
+
+| Variable | Required | What it is |
+| --- | --- | --- |
+| \`ENTREPRENOID_INGEST_URL\` | **yes** | The ingest endpoint. \u26A0\uFE0F It must end in \`/v1/events\` \u2014 the SDK POSTs this URL verbatim and appends nothing, so a bare origin sends every batch to \`POST /\`, which is rejected. The SDK fails open, so you would see nothing at all. |
+| \`ENTREPRENOID_SERVER_KEY\` | **yes** | The site's key, starting with \`ep_live_server_\`. |
+| \`ENTREPRENOID_SITE_ID\` | no | The dashboard shows it beside the key. Safe to set, safe to omit: the server resolves the site from the credential and ignores this value. |
+| \`ENTREPRENOID_ENABLED\` | no | \`false\` makes collection a transparent no-op without removing any code. Useful per environment. |
+| \`ENTREPRENOID_DEBUG\` | no | \`true\` prints one startup line saying whether collection is on, and why not if it is off. |
+
+**If either required value is missing, STOP and ask.** Do not invent them, and do not
+leave a placeholder \u2014 a config that looks complete and is not is worse than no config.
+
+Safety rules that apply throughout:
+
+- **Never hardcode the key**, never print it, never commit it. Environment variables only.
+- Before writing an env file, make sure it is gitignored.
+- \u26A0\uFE0F **Never prefix the key with \`NEXT_PUBLIC_\`, \`VITE_\`, \`PUBLIC_\` or \`REACT_APP_\`.**
+  Those prefixes inline a value into client-side JavaScript, which publishes the key to
+  everyone who loads the page. The SDK refuses to start if it finds one.
+- Only touch the files this install needs.
+
+## Step 1 \u2014 install the package
+
+Detect the package manager from the lockfile:
+
+| Lockfile | Command |
+| --- | --- |
+| \`pnpm-lock.yaml\` | \`pnpm add ${pkg}\` |
+| \`yarn.lock\` | \`yarn add ${pkg}\` |
+| \`bun.lock\` | \`bun add ${pkg}\` |
+| \`package-lock.json\` or none | \`npm install ${pkg}\` |
+
+## Step 2 \u2014 wire up the collector (pick exactly ONE)
+
+### Express
+
+\`\`\`ts
+import { entreprenoid } from "${pkg}/express";
+
+app.use(entreprenoid());
+\`\`\`
+
+Add it **before** your routes so it observes all of them.
+
+### Next.js (App Router, 14+)
+
+Use the **Next adapter**, not the web one. In \`proxy.ts\` at the project root
+(\`middleware.ts\` on Next 15 and earlier \u2014 same file, renamed in Next 16):
+
+\`\`\`ts
+import { after } from "next/server";
+import { proxy } from "${pkg}/next";
+
+export default proxy({ after });
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+\`\`\`
+
+\u26A0\uFE0F **Do not use \`${pkg}/web\` in a Next proxy.** It runs and it lies. A proxy
+executes *before* the route and hands control onward with a sentinel response \u2014 status
+200, no real content type \u2014 so the web adapter would record a **measured 200 for every
+request**, including the ones your routes render as 404 or 500.
+
+The Next adapter emits only what a proxy can actually know, and **omits the response
+entirely** rather than guessing at it. Your dashboard will show those requests with no
+status, which is the truth: nothing observed one.
+
+\u26A0\uFE0F **Pass \`after\`.** Without it the collector relies on its own timer, and a serverless
+invocation can be frozen before that timer fires \u2014 events are simply lost, silently.
+
+### Web-standard runtimes (Cloudflare Workers, Deno, Bun, Hono)
+
+\`\`\`ts
+import { observe } from "${pkg}/web";
+
+export default {
+  fetch: observe(handler, { waitUntil: (p) => ctx.waitUntil(p) }),
+};
+\`\`\`
+
+Pass \`waitUntil\` where the runtime offers one, or a serverless invocation can be
+frozen before the events are sent.
+
+## Step 3 \u2014 optional: serve a markdown twin
+
+Agents pay for every token they read, and most of a modern page is markup they do not
+want. Supply a resolver and the same middleware will serve clean markdown when a client
+asks for it:
+
+\`\`\`ts
+app.use(entreprenoid({
+  twin: { resolve: (path) => markdownFor(path) },
+}));
+\`\`\`
+
+\u26A0\uFE0F **A browser never receives markdown.** The twin is served only when the path ends in
+\`.md\` or the \`Accept\` header explicitly prefers \`text/markdown\` \u2014 never based on the
+User-Agent, which would be cloaking and would break shared caching.
+
+## Step 4 \u2014 \u26A0\uFE0F look at the routes before you go live
+
+**Do not skip this one.** The path is sent as it arrives. The query string is dropped
+before anything parses it, and the \`Referer\` is reduced to an origin \u2014 but the path
+itself is data, and on a lot of sites the path carries secrets:
+
+\`\`\`
+/reveal/<single-use-token>     /join/<invite-code>
+/confirm/<token>               /upload/<ticket>
+\`\`\`
+
+Read the project's routes. For each one, decide:
+
+\`\`\`ts
+app.use(entreprenoid({
+  // Collapse identifiers so analytics never sees a per-user value, and so one
+  // route does not become ten thousand rows.
+  routeTemplate: (path) => path.replace(/\\/\\d+(?=\\/|$)/g, "/:id"),
+
+  // Replace any segment that is a token, code or personal identifier.
+  redactPatterns: [/^[A-Za-z0-9_-]{20,}$/],
+
+  // Traffic you do not want counted: health checks, your own office, previews.
+  isInternal: (req) => req.path.startsWith("/_health"),
+}));
+\`\`\`
+
+\u26A0\uFE0F **A default backstop already runs, and you should not rely on it.** Segments that
+look like credentials \u2014 uuids, cuids, JWTs, long hex, dense mixed-case strings \u2014 are
+replaced with \`[redacted]\` before the event is sent, and the event records that it
+happened. It cannot catch a short token like \`/j/aB3xK9\`, and it does not know which of
+this project's ids are sensitive. **Only the routes tell you that.** Set
+\`redactHighEntropyPaths: false\` to turn the backstop off; that never disables
+\`redactPatterns\`, which are yours.
+
+If you are unsure whether a path segment is a secret, treat it as one and say so in your
+summary to the user.
+
+## Step 5 \u2014 verify
+
+Start the app and make one request. Within a few seconds the dashboard should show it.
+If nothing arrives:
+
+- check the key is set in the server's environment, not the client's
+- check \`ENTREPRENOID_INGEST_URL\` ends in \`/v1/events\`
+- set \`ENTREPRENOID_DEBUG=true\` and read the startup line
+
+**Do not add retry logic, queues or error handling around the SDK.** It already buffers,
+retries with backoff, and fails open. Wrapping it in a try/catch is harmless; awaiting it
+is not, and would put analytics on your critical path.
+`;
+}
+
+// src/express.ts
+function header(req, name) {
+  const value = req.headers[name];
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function headerString(res, name) {
+  const value = res.getHeader(name);
+  if (value === void 0 || value === null) return void 0;
+  return Array.isArray(value) ? value[0] : String(value);
+}
+function entreprenoid(options = {}) {
+  const config = resolveConfig(options);
+  const collector = options.collector ?? createCollector(config);
+  const twin = options.twin;
+  return function entreprenoidMiddleware(req, res, next) {
+    if (config.disabled && !twin) {
+      next();
+      return;
+    }
+    const startedAt = Date.now();
+    const startedHr = process.hrtime.bigint();
+    let recorded = false;
+    let served;
+    const record = () => {
+      if (recorded) return;
+      recorded = true;
+      safe(() => {
+        const observed = observeRequest(
+          {
+            method: req.method ?? "GET",
+            url: req.originalUrl ?? req.url ?? "/",
+            host: header(req, "host"),
+            protocol: req.secure || req.protocol === "https" ? "https" : "http",
+            userAgent: header(req, "user-agent"),
+            referer: header(req, "referer") ?? header(req, "referrer")
+          },
+          config
+        );
+        const finished = res.writableFinished !== false;
+        const latencyMs = Number(process.hrtime.bigint() - startedHr) / 1e6;
+        const event = {
+          ...observed,
+          eventId: newEventId(),
+          siteId: config.siteId,
+          observedAt: new Date(startedAt).toISOString(),
+          response: finished ? observeResponse({
+            status: res.statusCode,
+            contentType: headerString(res, "content-type"),
+            contentLength: headerString(res, "content-length"),
+            latencyMs,
+            observation: "measured"
+          }) : observeResponse({ latencyMs, observation: "unknown" }),
+          ...served ? { serve: served } : {},
+          sdk: {
+            name: SDK_NAME,
+            version: SDK_VERSION,
+            adapter: "express",
+            runtime: runtimeName()
+          }
+        };
+        collector.record(event);
+      });
+    };
+    safe(() => {
+      res.once("finish", record);
+      res.once("close", record);
+    });
+    if (!twin) {
+      next();
+      return;
+    }
+    const path = normalisePath(req.originalUrl ?? req.url ?? "/", config.redactPatterns);
+    if (twin.discovery && DISCOVERY_PATHS.includes(path)) {
+      const method = (req.method ?? "GET").toUpperCase();
+      if (method === "GET" || method === "HEAD") {
+        void (async () => {
+          try {
+            const body = path === "/install.md" ? renderInstallMd() : path === "/llms.txt" ? renderLlmsTxt(twin.discovery) : await renderLlmsFullTxt(twin.discovery, twin.resolve);
+            res.setHeader("content-type", "text/markdown; charset=utf-8");
+            res.setHeader("cache-control", twin.cacheControl ?? "public, max-age=3600, s-maxage=86400");
+            res.statusCode = 200;
+            served = { decision: "served", reason: "md_path", format: "text/markdown; charset=utf-8" };
+            if (method === "HEAD") res.end();
+            else res.end(body);
+          } catch {
+            served = { decision: "error", reason: "resolver_error" };
+            if (!res.headersSent) next();
+          }
+        })();
+        return;
+      }
+    }
+    const decision = decideTwin({
+      method: req.method ?? "GET",
+      path,
+      accept: header(req, "accept")
+    });
+    if (decision.action === "pass") {
+      if (twin.advertise !== false) {
+        void Promise.resolve().then(() => twin.resolve(path)).then((found) => {
+          if (found && !res.headersSent) {
+            safe(() => res.setHeader("link", advertiseHeader(path)));
+            served = { decision: "advertised", reason: "no_twin" };
+          }
+        }).catch(() => void 0).finally(() => next());
+        return;
+      }
+      served = { decision: "fell_through", reason: decision.reason };
+      next();
+      return;
+    }
+    void Promise.resolve().then(() => twin.resolve(decision.lookupPath)).then((found) => {
+      if (!found) {
+        served = { decision: "fell_through", reason: "no_twin" };
+        next();
+        return;
+      }
+      const built = buildTwinResponse(found, decision, twin);
+      served = {
+        decision: "served",
+        reason: decision.reason,
+        format: built.headers["content-type"] ?? "text/markdown"
+      };
+      for (const [name, value] of Object.entries(built.headers)) {
+        res.setHeader(name, value);
+      }
+      res.statusCode = built.status;
+      if ((req.method ?? "GET").toUpperCase() === "HEAD") res.end();
+      else res.end(built.body);
+    }).catch(() => {
+      served = { decision: "error", reason: "resolver_error" };
+      if (!res.headersSent) next();
+    });
+  };
+}
+
+// src/next.ts
+function proxy(options = {}) {
+  const config = resolveConfig(options);
+  const collector = options.collector ?? createCollector(config);
+  return async (request) => {
+    const startedAt = Date.now();
+    let served;
+    let twinResponse;
+    if (options.twin) {
+      try {
+        const url = new URL(request.url);
+        const decision = decideTwin({
+          method: request.method,
+          path: normalisePath(url.pathname),
+          accept: request.headers.get("accept")
+        });
+        if (decision.action === "serve") {
+          const found = await options.twin.resolve(decision.lookupPath);
+          if (found) {
+            const built = buildTwinResponse(found, decision, options.twin);
+            served = {
+              decision: "served",
+              reason: decision.reason,
+              format: built.headers["content-type"] ?? "text/markdown"
+            };
+            twinResponse = new Response(
+              request.method.toUpperCase() === "HEAD" ? null : built.body,
+              { status: built.status, headers: built.headers }
+            );
+          } else {
+            served = { decision: "fell_through", reason: "no_twin" };
+          }
+        } else {
+          served = { decision: "fell_through", reason: decision.reason };
+        }
+      } catch {
+        served = { decision: "error", reason: "resolver_error" };
+      }
+    }
+    const record = () => {
+      safe(() => {
+        if (config.disabled) return;
+        const url = new URL(request.url);
+        const observed = observeRequest(
+          {
+            method: request.method,
+            url: url.pathname + url.search,
+            host: url.host,
+            protocol: url.protocol === "https:" ? "https" : "http",
+            userAgent: request.headers.get("user-agent") ?? void 0,
+            referer: request.headers.get("referer") ?? void 0
+          },
+          config
+        );
+        const event = {
+          ...observed,
+          eventId: newEventId(),
+          // ⚠️ Emitted so a post-response observation CAN be merged later.
+          // Nothing merges it today, and the docblock above says so plainly
+          // rather than letting the field imply otherwise.
+          requestId: newEventId(),
+          siteId: config.siteId,
+          observedAt: new Date(startedAt).toISOString(),
+          ...served ? { serve: served } : {},
+          // ⚠️ **The response object is present ONLY when we built it.**
+          //
+          // If the twin was served, this proxy IS the responder and measured it.
+          // Otherwise the route has not run yet and there is nothing to
+          // observe — so the key is OMITTED, not set to a guess, not set to
+          // `observation: "unknown"` with a status (which the schema refuses),
+          // and not set to a latency-only object (we did not wait for the
+          // response, so we did not measure a latency either).
+          ...twinResponse ? {
+            response: observeResponse({
+              status: twinResponse.status,
+              contentType: twinResponse.headers.get("content-type"),
+              contentLength: twinResponse.headers.get("content-length"),
+              latencyMs: Date.now() - startedAt,
+              observation: "measured"
+            })
+          } : {},
+          sdk: {
+            name: SDK_NAME,
+            version: SDK_VERSION,
+            // ⚠️ `next-proxy`, which is the name the WIRE SCHEMA already uses
+            // in its own docblock (`event.ts:157`). Its own name matters here
+            // more than for any other adapter: this is the one whose events
+            // legitimately carry no response, and the dashboard must not
+            // present an adapter's blind spot as a fact about the traffic.
+            adapter: "next-proxy",
+            runtime: runtimeName()
+          }
+        };
+        collector.record(event);
+      });
+    };
+    if (options.after) {
+      try {
+        options.after(record);
+      } catch {
+        record();
+      }
+    } else {
+      record();
+    }
+    return twinResponse;
+  };
+}
+
+exports.BoundedQueue = BoundedQueue;
+exports.CAMPAIGN_PARAMS = CAMPAIGN_PARAMS;
+exports.DEFAULTS = DEFAULTS;
+exports.DEFAULT_TWIN_CACHE_CONTROL = DEFAULT_TWIN_CACHE_CONTROL;
+exports.DEFAULT_TWIN_CONTENT_TYPE = DEFAULT_TWIN_CONTENT_TYPE;
+exports.EntreprenoidConfigError = EntreprenoidConfigError;
+exports.MARKDOWN_TYPES = MARKDOWN_TYPES;
+exports.MAX_BODY_BYTES = MAX_BODY_BYTES;
+exports.REDACTED = REDACTED;
+exports.UNSET_SITE_ID = UNSET_SITE_ID;
+exports.advertiseHeader = advertiseHeader;
+exports.buildTwinResponse = buildTwinResponse;
+exports.createBreaker = createBreaker;
+exports.createCollector = createCollector;
+exports.decideTwin = decideTwin;
+exports.encodeBatch = encodeBatch;
+exports.entreprenoid = entreprenoid;
+exports.fetchTransport = fetchTransport;
+exports.looksLikeSecret = looksLikeSecret;
+exports.newEventId = newEventId;
+exports.normalisePath = normalisePath;
+exports.observe = observe;
+exports.observeRequest = observeRequest;
+exports.observeResponse = observeResponse;
+exports.outcomeForStatus = outcomeForStatus;
+exports.parseAccept = parseAccept;
+exports.prefersMarkdown = prefersMarkdown;
+exports.proxy = proxy;
+exports.redact = redact;
+exports.redactPath = redactPath;
+exports.referrerOrigin = referrerOrigin;
+exports.renderInstallMd = renderInstallMd;
+exports.renderLlmsFullTxt = renderLlmsFullTxt;
+exports.renderLlmsTxt = renderLlmsTxt;
+exports.resolveConfig = resolveConfig;
+exports.runtimeName = runtimeName;
+exports.safe = safe;
+exports.safeAsync = safeAsync;
+exports.stripMdSuffix = stripMdSuffix;
+exports.twinPathFor = twinPathFor;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map