@analitikisler/ai-tag-debugger 0.0.0-stage → 0.5.2

package/src/checks.js

@@ -0,0 +1,213 @@
+// Deterministic checks that compare captured hits with the measurement plan.
+// They run without any API call; the AI model only explains the results.
+
+import { messages } from "./i18n.js";
+
+const NON_GOOGLE_AD_PLATFORMS = new Set(["meta", "tiktok"]);
+const EMAIL = /[A-Z0-9._%+-]+(@|%40)[A-Z0-9.-]+\.[A-Z]{2,}/i;
+const SEVERITY_ORDER = { broken: 0, risk: 1, warning: 2, info: 3, ok: 4 };
+
+/**
+ * @typedef {{ platform: string, name: string, required_params?: string[], journeys?: string[], allow_multiple?: boolean }} PlanEvent
+ * @typedef {{ consent_mode?: boolean, events: PlanEvent[] }} Plan
+ * @typedef {{ severity: "broken"|"risk"|"warning"|"info"|"ok", check: string, journey: string, viewport: string, platform?: string, event?: string, step?: string, detail: string, evidence?: string }} Finding
+ */
+
+const key = (platform, name) => `${platform}:${name}`;
+
+function expectedIn(planEvent, journeyId) {
+  return !planEvent.journeys || planEvent.journeys.includes(journeyId);
+}
+
+function isConsentCommand(entry, kind) {
+  return Array.isArray(entry.value) && entry.value[0] === "consent" && entry.value[1] === kind;
+}
+
+/** The step at which the visitor gave ad consent, from the run or from Consent Mode updates. */
+export function consentGrantedStep(run) {
+  const fromUpdate = run.dataLayerLog.find(
+    (e) => isConsentCommand(e, "update") && e.value[2]?.ad_storage === "granted",
+  );
+  const candidates = [run.consentStep, fromUpdate?.step].filter((s) => s !== null && s !== undefined);
+  return candidates.length ? Math.min(...candidates) : null;
+}
+
+/**
+ * @param {Plan} plan
+ * @param {{ journeyId: string, viewport: string, completed: boolean, note?: string, hits: any[], steps: any[], consentStep: number|null, dataLayerLog: any[] }} run
+ * @param {{ lang?: string }} [opts] Report language for the finding texts.
+ * @returns {Finding[]}
+ */
+export function checkRun(plan, run, { lang = "en" } = {}) {
+  const d = messages(lang).detail;
+  const findings = [];
+  const base = { journey: run.journeyId, viewport: run.viewport };
+  // Platforms are compared in lower case ("GA4" in a plan is ga4). Planned events for
+  // providers the user chose not to check are left out, and listed in one info line.
+  plan = { ...plan, events: plan.events.map((e) => ({ ...e, platform: String(e.platform ?? "").toLowerCase() })) };
+  if (run.providers) {
+    const skipped = plan.events.filter((e) => !run.providers.includes(e.platform) && expectedIn(e, run.journeyId));
+    plan = { ...plan, events: plan.events.filter((e) => run.providers.includes(e.platform)) };
+    if (skipped.length) findings.push({ ...base, severity: "info", check: "planned_out_of_scope", detail: d.plannedOutOfScope(skipped.map((e) => key(e.platform, e.name))) });
+  }
+  const stepLabel = (i) => run.steps[i]?.label ?? `step ${i}`;
+  const planByKey = new Map(plan.events.map((e) => [key(e.platform, e.name), e]));
+
+  if (!run.completed) {
+    findings.push({ ...base, severity: "warning", check: "journey_incomplete", detail: d.journeyIncomplete(run.note) });
+  }
+
+  // Expected events that never fired.
+  for (const ev of plan.events) {
+    if (!expectedIn(ev, run.journeyId)) continue;
+    const fired = run.hits.some((h) => h.platform === ev.platform && h.name === ev.name);
+    if (!fired) {
+      findings.push({
+        ...base,
+        severity: run.completed ? "broken" : "info",
+        check: "missing_event",
+        platform: ev.platform,
+        event: ev.name,
+        detail: run.completed ? d.missingEvent(ev.platform, ev.name) : d.missingEventEarly(ev.name),
+      });
+    }
+  }
+
+  // Required parameters missing on events that did fire (reported once per event).
+  const paramsReported = new Set();
+  for (const hit of run.hits) {
+    const ev = planByKey.get(key(hit.platform, hit.name));
+    if (!ev?.required_params?.length) continue;
+    const missing = ev.required_params.filter((p) => hit.params[p] === undefined || hit.params[p] === "");
+    const reportKey = `${key(hit.platform, hit.name)}|${missing.join(",")}`;
+    if (missing.length && !paramsReported.has(reportKey)) {
+      paramsReported.add(reportKey);
+      findings.push({
+        ...base,
+        severity: "broken",
+        check: "missing_params",
+        platform: hit.platform,
+        event: hit.name,
+        step: stepLabel(hit.step),
+        detail: d.missingParams(hit.name, missing),
+        evidence: JSON.stringify(hit.params),
+      });
+    }
+  }
+
+  // The same event sent more than once by a single action.
+  const perStep = new Map();
+  for (const hit of run.hits) {
+    const k = `${hit.step}|${key(hit.platform, hit.name)}`;
+    perStep.set(k, [...(perStep.get(k) ?? []), hit]);
+  }
+  for (const [, hits] of perStep) {
+    const ev = planByKey.get(key(hits[0].platform, hits[0].name));
+    if (hits.length < 2 || ev?.allow_multiple) continue;
+    findings.push({
+      ...base,
+      severity: "warning",
+      check: "duplicate",
+      platform: hits[0].platform,
+      event: hits[0].name,
+      step: stepLabel(hits[0].step),
+      detail: d.duplicate(hits[0].name, hits.length),
+    });
+  }
+
+  // Consent.
+  const granted = consentGrantedStep(run);
+  const firstHitStep = run.hits.length ? Math.min(...run.hits.map((h) => h.step)) : null;
+  if (plan.consent_mode) {
+    const defaultEntry = run.dataLayerLog.find((e) => isConsentCommand(e, "default"));
+    if (!defaultEntry) {
+      findings.push({ ...base, severity: "risk", check: "consent_default_missing", detail: d.consentDefaultMissing() });
+    } else if (firstHitStep !== null && defaultEntry.step > firstHitStep) {
+      findings.push({ ...base, severity: "risk", check: "consent_default_late", detail: d.consentDefaultLate() });
+    }
+  }
+  const beforeConsent = new Map();
+  for (const hit of run.hits) {
+    const early = granted === null || hit.step < granted;
+    if (!early) continue;
+    const adPlatform = NON_GOOGLE_AD_PLATFORMS.has(hit.platform);
+    const googleClaimsGranted = hit.consent?.ad_storage === "granted" || hit.consent?.analytics_storage === "granted";
+    if (adPlatform || googleClaimsGranted) {
+      const k = key(hit.platform, hit.name);
+      if (!beforeConsent.has(k)) beforeConsent.set(k, hit);
+    }
+  }
+  for (const [, hit] of beforeConsent) {
+    findings.push({
+      ...base,
+      severity: "risk",
+      check: "before_consent",
+      platform: hit.platform,
+      event: hit.name,
+      step: stepLabel(hit.step),
+      detail: granted === null ? d.beforeConsentNever(hit.platform, hit.name) : d.beforeConsent(hit.platform, hit.name),
+    });
+  }
+
+  // Personal data in hits.
+  const piiSeen = new Set();
+  for (const hit of run.hits) {
+    let url = hit.url;
+    try {
+      url = decodeURIComponent(hit.url);
+    } catch { /* malformed % sequence, e.g. "50%": search the raw URL */ }
+    const haystack = url + " " + JSON.stringify(hit.params);
+    if (piiSeen.has(key(hit.platform, hit.name))) continue;
+    // User data for ad matching is redacted at capture; userData.plain lists the fields that were not hashed.
+    if (hit.userData?.plain?.length) {
+      piiSeen.add(key(hit.platform, hit.name));
+      findings.push({ ...base, severity: "risk", check: "pii", platform: hit.platform, event: hit.name, step: stepLabel(hit.step), detail: d.piiUnhashed(hit.platform, hit.name, hit.userData.plain) });
+    } else if (EMAIL.test(haystack)) {
+      piiSeen.add(key(hit.platform, hit.name));
+      findings.push({ ...base, severity: "risk", check: "pii", platform: hit.platform, event: hit.name, step: stepLabel(hit.step), detail: d.pii(hit.platform, hit.name) });
+    }
+  }
+
+  // Unhashed user data in the dataLayer. Valid for GTM enhanced conversions (Google hashes it
+  // before sending), but every other tag on the page can read it too.
+  const plainPush = run.dataLayerLog.find((e) => e.userData?.plain?.length);
+  if (plainPush) {
+    findings.push({ ...base, severity: "warning", check: "pii_datalayer", step: stepLabel(plainPush.step), detail: d.piiDataLayer(plainPush.userData.plain) });
+  }
+
+  // Events that are not in the plan.
+  const unplanned = [...new Set(run.hits.filter((h) => !planByKey.has(key(h.platform, h.name))).map((h) => key(h.platform, h.name)))];
+  if (unplanned.length) {
+    findings.push({ ...base, severity: "info", check: "unplanned_events", detail: d.unplanned(unplanned) });
+  }
+
+  // Planned events that fired cleanly.
+  const problemKeys = new Set(findings.filter((f) => f.event).map((f) => key(f.platform, f.event)));
+  const okKeys = [...new Set(run.hits.map((h) => key(h.platform, h.name)))].filter((k) => planByKey.has(k) && !problemKeys.has(k));
+  if (okKeys.length) {
+    findings.push({ ...base, severity: "ok", check: "matches_plan", detail: d.matches(okKeys) });
+  }
+
+  return findings.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+}
+
+export function summarize(findings) {
+  const counts = { broken: 0, risk: 0, warning: 0, info: 0, ok: 0 };
+  for (const f of findings) counts[f.severity] += 1;
+  return counts;
+}
+
+/**
+ * Merges the same problem seen on several journeys or viewports into one
+ * finding with a list of places, so the report reads as a list of problems.
+ */
+export function groupFindings(findings) {
+  const groups = new Map();
+  for (const f of findings) {
+    const k = f.severity === "ok" ? `ok|${f.journey}|${f.viewport}` : [f.severity, f.check, f.platform, f.event, f.detail].join("|");
+    const where = { journey: f.journey, viewport: f.viewport, step: f.step };
+    if (groups.has(k)) groups.get(k).where.push(where);
+    else groups.set(k, { severity: f.severity, check: f.check, platform: f.platform, event: f.event, detail: f.detail, evidence: f.evidence, where: [where] });
+  }
+  return [...groups.values()].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+}

package/src/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig, runAudit } from "./audit.js";
+import { LANGUAGES, messages } from "./i18n.js";
+import { PROVIDERS } from "./providers.js";
+import { JOURNEY_PRESETS } from "./journeys.js";
+import { PROVIDERS as TRACKING_PROVIDERS, DEFAULT_PROVIDERS } from "./parsers.js";
+
+const USAGE = `ai-tag-debugger: an open-source AI agent that QA-tests your analytics and ad tracking.
+
+Usage:
+  ai-tag-debugger run --site <url> --journey purchase [options]   Audit ready-made journeys, no config needed.
+  ai-tag-debugger run --site <url> --goal "<what to do>"          Audit a journey you describe in plain language.
+  ai-tag-debugger run --config <file> [options]                   Run an audit from a config file.
+  ai-tag-debugger mcp [--http] [--port <n>]       Start the MCP server for Claude, ChatGPT, Gemini and other chat apps.
+
+Run options:
+  --site <url>         The site to audit (overrides "site" in the config).
+  --config <file>      Audit config (JSON). See examples/demo.config.json.
+  --journey <id>       Run this journey (repeatable): a journey id from the config, or a ready-made
+                       journey: ${Object.keys(JOURNEY_PRESETS).join(", ")}.
+  --goal "<text>"      Run a journey you describe in plain language (repeatable).
+  --events <names>     Only check these events, comma separated, e.g. purchase,add_to_cart.
+  --max-steps <n>      Most AI steps per journey (default 30). Lower it to cap API usage.
+  --out <dir>          Where to write report.html, report.md, timeline.csv and capture.json (default: reports/<timestamp>).
+  --provider <name>    AI provider: ${Object.keys(PROVIDERS).join(", ")} (default: whichever API key is set).
+  --model <id>         Model id (defaults: ${Object.entries(PROVIDERS).filter(([, p]) => p.defaultModel).map(([k, p]) => `${k} ${p.defaultModel}`).join(", ")}).
+  --base-url <url>     API address for --provider openai-compatible (Kimi, GLM, DeepSeek, OpenRouter, Ollama...).
+  --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")} (default: en, or "language" in the config).
+  --providers <list>   Tracking providers to check, comma separated (default: ${DEFAULT_PROVIDERS.join(",")}).
+                       Choose from ${Object.keys(TRACKING_PROVIDERS).join(", ")}. Requests to the
+                       others are still answered locally, but only counted ("providers" in the config).
+  --viewport <name>    Only run this viewport: desktop or mobile (repeatable).
+  --allow-host <host>  Let journeys visit this host too, e.g. a hosted checkout (repeatable). By default the
+                       browser stays on the audited site and its subdomains ("allowed_hosts" in the config).
+  --scripted           Replay each journey's fixed "steps" instead of letting the AI browse.
+  --no-ai              Use no AI model at all (requires --scripted). The report then has no explanations.
+  --fail-on <level>    Exit with code 1 when findings reach this level: broken, risk, warning or never (default: broken).
+  --headed             Show the browser window.
+  --keep-bodies        Store tracking requests as sent. By default, emails, phone numbers and user ids sent
+                       for ad matching are redacted in the report and capture.json ("keep_bodies" in the config).
+  --no-branding        Leave the Analitik İşler logo and credit line out of the reports ("branding": false in the config).
+
+MCP options:
+  --http               Serve over Streamable HTTP instead of stdio (for apps that connect to a URL).
+  --port <n>           HTTP port (default 8787).
+  --host <addr>        HTTP host (default 127.0.0.1).
+  --token <secret>     Secret URL path segment, at least 16 characters (default: random, printed at start).
+  --allow-private-network  Over HTTP, let audits open localhost and private network addresses (blocked by default).
+  --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports).
+  --public-url <url>   The HTTPS address your tunnel or host gives this server, so audits can link to their reports.
+
+  -h, --help           Show this help.
+
+API keys: set one of ${Object.values(PROVIDERS).map((p) => p.env).join(", ")}.
+Any OpenAI-compatible API: --provider openai-compatible --base-url <url> --model <id>, with the key in OPENAI_COMPATIBLE_API_KEY.`;
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      config: { type: "string" },
+      site: { type: "string" },
+      goal: { type: "string", multiple: true },
+      events: { type: "string", multiple: true },
+      "max-steps": { type: "string" },
+      out: { type: "string" },
+      journey: { type: "string", multiple: true },
+      viewport: { type: "string", multiple: true },
+      providers: { type: "string", multiple: true },
+      "allow-host": { type: "string", multiple: true },
+      "allow-private-network": { type: "boolean", default: false },
+      scripted: { type: "boolean", default: false },
+      "no-ai": { type: "boolean", default: false },
+      provider: { type: "string" },
+      model: { type: "string" },
+      "base-url": { type: "string" },
+      lang: { type: "string" },
+      "fail-on": { type: "string", default: "broken" },
+      headed: { type: "boolean", default: false },
+      "no-branding": { type: "boolean", default: false },
+      "keep-bodies": { type: "boolean", default: false },
+      http: { type: "boolean", default: false },
+      port: { type: "string" },
+      host: { type: "string" },
+      token: { type: "string" },
+      reports: { type: "string" },
+      "public-url": { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+  const command = positionals[0];
+
+  if (command === "mcp" && !values.help) {
+    const { startMcp } = await import("./mcp.js");
+    await startMcp({ http: values.http, port: values.port ? Number(values.port) : undefined, host: values.host, token: values.token, reportsDir: values.reports, publicUrl: values["public-url"], allowPrivateNetwork: values["allow-private-network"] });
+    return;
+  }
+  if (values.help || command !== "run" || (!values.config && !values.site)) {
+    console.log(USAGE);
+    process.exit(values.help ? 0 : 2);
+  }
+  if (values["no-ai"] && !values.scripted) {
+    throw new Error("--no-ai needs --scripted: without an AI model, journeys must have fixed steps.");
+  }
+  const levels = ["broken", "risk", "warning"];
+  const failOn = values["fail-on"];
+  if (failOn !== "never" && !levels.includes(failOn)) throw new Error(`--fail-on must be one of ${levels.join(", ")}, never.`);
+
+  const loaded = values.config ? await loadConfig(values.config) : { config: {}, plan: null, gtmContainer: null };
+  if (values.site) loaded.config = { ...loaded.config, site: values.site };
+  if (values["keep-bodies"]) loaded.config = { ...loaded.config, keep_bodies: true };
+  if (values["allow-host"]?.length) loaded.config = { ...loaded.config, allowed_hosts: [...(loaded.config.allowed_hosts ?? []), ...values["allow-host"]] };
+  try {
+    new URL(loaded.config.site);
+  } catch {
+    throw new Error(`"${loaded.config.site}" is not a full URL. Use e.g. https://www.example.com`);
+  }
+  const maxSteps = values["max-steps"] ? Number(values["max-steps"]) : undefined;
+  if (maxSteps !== undefined && !(Number.isInteger(maxSteps) && maxSteps > 0)) throw new Error("--max-steps must be a positive whole number.");
+  const result = await runAudit({
+    ...loaded,
+    journeys: values.journey,
+    goals: values.goal,
+    events: (values.events ?? []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean),
+    maxSteps,
+    viewports: values.viewport,
+    providers: values.providers?.length ? values.providers.flatMap((p) => p.split(",")) : undefined,
+    scripted: values.scripted,
+    ai: !values["no-ai"],
+    provider: values.provider,
+    model: values.model,
+    baseUrl: values["base-url"],
+    lang: values.lang,
+    headed: values.headed,
+    branding: values["no-branding"] ? false : undefined,
+    outDir: values.out,
+    log: (msg) => console.log(msg),
+  });
+
+  console.log(`\n${messages(result.lang).ui.counts(result.counts)}`);
+  const rel = path.relative(process.cwd(), result.reportPath);
+  console.log(`Report: ${rel.startsWith("..") ? result.reportPath : rel}`);
+
+  if (failOn !== "never") {
+    const threshold = levels.indexOf(failOn);
+    if (levels.slice(0, threshold + 1).some((l) => result.counts[l] > 0)) process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(2);
+});

package/src/egress.js

@@ -0,0 +1,134 @@
+// A small local proxy that all browser traffic goes through when private addresses
+// are blocked (MCP over HTTP). It resolves each host once, refuses private
+// addresses, and connects to exactly the address it checked. Chromium never
+// resolves the host itself, so a DNS answer that changes between the check and
+// the connection (DNS rebinding) can't reach a private address. It covers plain
+// HTTP, HTTPS and WebSocket (ws:// and wss://) traffic alike.
+import { createServer, request as httpRequest } from "node:http";
+import { connect as netConnect, isIP } from "node:net";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isPrivateAddress } from "./guard.js";
+
+const HOP_HEADERS = ["proxy-connection", "proxy-authorization", "connection", "keep-alive", "te", "trailer", "transfer-encoding", "upgrade"];
+
+/** Splits "host:port" or "[v6]:port". */
+function splitHostPort(value, defaultPort) {
+  const m = value.match(/^\[([^\]]+)\](?::(\d+))?$/) ?? value.match(/^([^:]+)(?::(\d+))?$/);
+  if (!m) return null;
+  return { host: m[1], port: Number(m[2] ?? defaultPort) };
+}
+
+/**
+ * @param {{ isBlocked?: (ip: string) => boolean, lookup?: (host: string) => Promise<{ address: string, family: number }[]> }} [opts]
+ *   isBlocked: which resolved addresses to refuse (default: private ones). lookup: injectable for tests.
+ * @returns {Promise<{ url: string, refused: string[], close: () => Promise<void> }>}
+ */
+export async function startEgressProxy(opts = {}) {
+  const isBlocked = opts.isBlocked ?? isPrivateAddress;
+  const lookup = opts.lookup ?? ((host) => dnsLookup(host, { all: true, verbatim: true }));
+  const refused = [];
+
+  /** The one address to connect to, or throws when the host is refused or unresolvable. */
+  async function resolve(host) {
+    const bare = host.replace(/^\[|\]$/g, "");
+    const addrs = isIP(bare) ? [{ address: bare, family: isIP(bare) }] : await lookup(bare);
+    if (!addrs.length) throw new Error(`${host} did not resolve`);
+    if (bare === "localhost" || bare.endsWith(".localhost") || addrs.some((a) => isBlocked(a.address))) {
+      refused.push(host);
+      throw Object.assign(new Error(`${host} is a private network address`), { refused: true });
+    }
+    return addrs[0];
+  }
+
+  const sockets = new Set();
+  const track = (s) => {
+    sockets.add(s);
+    s.on("close", () => sockets.delete(s));
+    s.on("error", () => s.destroy());
+    return s;
+  };
+
+  const server = createServer(async (req, res) => {
+    // Plain http:// requests arrive with an absolute URL.
+    let target;
+    try {
+      target = new URL(req.url);
+      if (target.protocol !== "http:") throw new Error("only http");
+    } catch {
+      res.writeHead(400).end();
+      return;
+    }
+    let addr;
+    try {
+      addr = await resolve(target.hostname);
+    } catch (err) {
+      res.writeHead(err.refused ? 403 : 502).end();
+      return;
+    }
+    const headers = { ...req.headers };
+    for (const h of HOP_HEADERS) delete headers[h];
+    const upstream = httpRequest(
+      { host: addr.address, family: addr.family, port: Number(target.port) || 80, method: req.method, path: target.pathname + target.search, headers, setHost: false },
+      (up) => {
+        res.writeHead(up.statusCode ?? 502, up.headers);
+        up.pipe(res);
+      },
+    );
+    upstream.on("error", () => (res.headersSent ? res.destroy() : res.writeHead(502).end()));
+    req.pipe(upstream);
+  });
+
+  // HTTPS and WebSockets: a CONNECT tunnel to the checked address.
+  server.on("connect", async (req, client, head) => {
+    track(client);
+    const target = splitHostPort(req.url, 443);
+    let addr;
+    try {
+      if (!target) throw new Error("bad target");
+      addr = await resolve(target.host);
+    } catch (err) {
+      client.end(`HTTP/1.1 ${err.refused ? "403 Forbidden" : "502 Bad Gateway"}\r\n\r\n`);
+      return;
+    }
+    const upstream = track(netConnect({ host: addr.address, port: target.port, family: addr.family }, () => {
+      client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      if (head?.length) upstream.write(head);
+      upstream.pipe(client);
+      client.pipe(upstream);
+    }));
+    upstream.on("error", () => client.destroy());
+  });
+
+  // A ws:// upgrade sent as a plain proxied request, in case the browser doesn't tunnel it.
+  server.on("upgrade", async (req, client, head) => {
+    track(client);
+    let target;
+    let addr;
+    try {
+      target = new URL(req.url);
+      addr = await resolve(target.hostname);
+    } catch {
+      client.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+      return;
+    }
+    const upstream = track(netConnect({ host: addr.address, port: Number(target.port) || 80, family: addr.family }, () => {
+      const headers = Object.entries(req.headers).filter(([k]) => !k.startsWith("proxy-")).map(([k, v]) => `${k}: ${v}`);
+      upstream.write(`${req.method} ${target.pathname}${target.search} HTTP/1.1\r\n${headers.join("\r\n")}\r\n\r\n`);
+      if (head?.length) upstream.write(head);
+      upstream.pipe(client);
+      client.pipe(upstream);
+    }));
+    upstream.on("error", () => client.destroy());
+  });
+  server.on("connection", track);
+
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    refused,
+    close: async () => {
+      for (const s of sockets) s.destroy();
+      await new Promise((r) => server.close(() => r()));
+    },
+  };
+}

package/src/glossary.js

@@ -0,0 +1,139 @@
+// What each tracking request parameter means, for the "?" tips in the report's Network tab.
+// Keys are the raw request parameter names; [en, tr].
+
+const G = {
+  // GA4 (Measurement Protocol v2, as sent by gtag.js)
+  v: ["Protocol version. Always 2 for GA4.", "Protokol sürümü. GA4 için her zaman 2."],
+  tid: ["Measurement ID (G-…): which GA4 property the request goes to.", "Ölçüm kimliği (G-…). İsteğin hangi GA4 mülküne gittiğini gösterir."],
+  gtm: ["Hash of the Google tag or GTM container that sent it.", "Etiketi gönderen Google etiketi ya da GTM kapsayıcısının özeti."],
+  _p: ["Page load ID. Every request from the same page load has the same value.", "Sayfa yükleme kimliği. Aynı sayfadaki tüm istekler aynı değeri taşır."],
+  gcs: ["Consent Mode state. G1xy: x is ad_storage, y is analytics_storage (1 granted, 0 denied).", "Consent Mode durumu. G1xy: x reklam, y analitik depolama (1 izin var, 0 yok)."],
+  gcd: ["Consent Mode detail: the default and update value of each consent type.", "Consent Mode ayrıntısı: her izin türü için varsayılan ve güncelleme değerleri."],
+  npa: ["Non-personalized ads. 1 means personalization is off.", "Kişiselleştirilmemiş reklam. 1 ise kişiselleştirme kapalı."],
+  dma: ["EU Digital Markets Act flag.", "AB Dijital Pazarlar Yasası işareti."],
+  dma_cps: ["Consent purposes sent under the Digital Markets Act.", "Dijital Pazarlar Yasası kapsamında gönderilen izin amaçları."],
+  cid: ["Client ID: the anonymous ID of this browser (the _ga cookie).", "Client ID: tarayıcıyı tanımlayan anonim kimlik (_ga çerezi)."],
+  uid: ["User ID set by the site for a logged-in user.", "Site tarafından giriş yapmış kullanıcıya verilen kullanıcı kimliği."],
+  ul: ["Browser language.", "Tarayıcı dili."],
+  sr: ["Screen resolution.", "Ekran çözünürlüğü."],
+  _s: ["Sequence number of this request within the page load.", "Bu sayfa yüklemesindeki istek sıra numarası."],
+  sid: ["Session ID.", "Oturum kimliği."],
+  sct: ["Number of sessions for this user.", "Bu kullanıcının oturum sayısı."],
+  seg: ["Engaged session (1 = yes).", "Etkileşimli oturum (1 = evet)."],
+  dl: ["Page URL (page_location).", "Sayfa adresi (page_location)."],
+  dr: ["Previous page (page_referrer).", "Önceki sayfa (page_referrer)."],
+  dt: ["Page title (page_title).", "Sayfa başlığı (page_title)."],
+  en: ["Event name.", "Olay adı (event_name)."],
+  _et: ["Engagement time in milliseconds.", "Etkileşim süresi, milisaniye."],
+  cu: ["Currency.", "Para birimi (currency)."],
+  _ee: ["Enhanced conversions or user-provided data is enabled.", "Gelişmiş dönüşümler ya da kullanıcı verisi açık."],
+  _fv: ["First visit: this is the user's first session.", "İlk ziyaret: kullanıcının ilk oturumu."],
+  _ss: ["Session start: this request starts a new session.", "Oturum başlangıcı: bu istek yeni bir oturum başlatır."],
+  _nsi: ["New session ID was created.", "Yeni oturum kimliği oluşturuldu."],
+  _dbg: ["Debug mode is on (shows in GA4 DebugView).", "Hata ayıklama modu açık (GA4 DebugView'da görünür)."],
+  tfd: ["Time from page load to this request, in milliseconds.", "Sayfa yüklemesinden bu isteğe kadar geçen süre, milisaniye."],
+  are: ["Ads remarketing enabled.", "Reklam yeniden pazarlaması açık."],
+  frm: ["Request sent from inside a frame.", "İstek bir çerçeve içinden gönderildi."],
+  pscdl: ["Privacy sandbox cookie deprecation label.", "Privacy Sandbox çerez kullanımdan kaldırma etiketi."],
+  tag_exp: ["Google tag experiments this request is part of.", "Bu isteğin dahil olduğu Google etiketi deneyleri."],
+  // Meta Pixel
+  id: ["Meta Pixel ID.", "Meta piksel kimliği."],
+  ev: ["Meta event name.", "Meta olay adı."],
+  rl: ["Previous page (referrer).", "Önceki sayfa (referrer)."],
+  if: ["Whether the request came from inside an iframe.", "İstek bir iframe içinden mi geldi."],
+  ts: ["Time sent (Unix milliseconds).", "Gönderim zamanı (Unix ms)."],
+  sw: ["Screen width.", "Ekran genişliği."],
+  sh: ["Screen height.", "Ekran yüksekliği."],
+  ec: ["Number of events the pixel has sent on this page.", "Bu sayfada pikselin gönderdiği olay sayısı."],
+  o: ["Pixel setting flags.", "Piksel ayar bayrakları."],
+  fbp: ["Meta browser ID (the _fbp cookie).", "Meta tarayıcı kimliği (_fbp çerezi)."],
+  fbc: ["Meta click ID (the _fbc cookie, from fbclid).", "Meta tıklama kimliği (_fbc çerezi, fbclid'den)."],
+  eid: ["Event ID, used to deduplicate against the server-side (Conversions API) event.", "Olay kimliği. Sunucu tarafı (CAPI) olayla eşleştirmek için kullanılır."],
+  it: ["When the pixel loaded.", "Pikselin yüklendiği zaman."],
+  coo: ["Whether third-party cookies are off.", "Üçüncü taraf çerezler kapalı mı."],
+  rqm: ["Request method.", "İstek yöntemi."],
+  r: ["Pixel release channel.", "Piksel sürüm kanalı."],
+  a: ["Integration the pixel was installed with (e.g. tmgoogletagmanager).", "Pikselin kurulduğu entegrasyon (ör. tmgoogletagmanager)."],
+  udff: ["Hashed user data for advanced matching.", "Gelişmiş eşleştirme için karma (hash) kullanıcı verisi."],
+  // TikTok Pixel
+  event: ["TikTok event name.", "TikTok olay adı."],
+  pixel_code: ["TikTok Pixel ID.", "TikTok piksel kimliği."],
+  event_id: ["Event ID, used to deduplicate against the Events API.", "Olay kimliği. Events API ile eşleştirme için."],
+  "context.page.url": ["Page URL.", "Sayfa adresi."],
+  "context.page.referrer": ["Previous page.", "Önceki sayfa."],
+  "context.user.ttp": ["TikTok browser ID (the _ttp cookie).", "TikTok tarayıcı kimliği (_ttp çerezi)."],
+  "context.pixel.code": ["TikTok Pixel ID.", "TikTok piksel kimliği."],
+  "context.ad.callback": ["TikTok click ID (ttclid).", "TikTok tıklama kimliği (ttclid)."],
+  timestamp: ["Time sent.", "Gönderim zamanı."],
+  // Google Ads
+  label: ["Conversion label: which conversion action this is.", "Dönüşüm etiketi: hangi dönüşüm işlemi olduğunu gösterir."],
+  value: ["Conversion value.", "Dönüşüm değeri."],
+  currency_code: ["Currency.", "Para birimi."],
+  oid: ["Order (transaction) ID, used to deduplicate conversions.", "Sipariş (işlem) kimliği. Dönüşümleri tekilleştirmek için."],
+  gclaw: ["Google click ID (gclid) from the ad click.", "Reklam tıklamasından gelen Google tıklama kimliği (gclid)."],
+  gcl_ctr: ["Number of conversions counted for this click.", "Bu tıklama için sayılan dönüşüm sayısı."],
+  url: ["Page URL.", "Sayfa adresi."],
+  ref: ["Previous page.", "Önceki sayfa."],
+  guid: ["Whether Google user ID matching is on.", "Google kullanıcı kimliği eşleştirmesi açık mı."],
+  rnd: ["Random number to stop caching.", "Önbelleğe almayı önlemek için rastgele sayı."],
+  em: ["Hashed email for enhanced conversions.", "Gelişmiş dönüşümler için karma (hash) e-posta."],
+  // X Pixel
+  txn_id: ["X Pixel ID.", "X piksel kimliği."],
+  events: ["Events in this request.", "Bu istekteki olaylar."],
+  tw_sale_amount: ["Conversion value.", "Dönüşüm değeri."],
+  tw_order_quantity: ["Quantity.", "Adet."],
+  tw_document_href: ["Page URL.", "Sayfa adresi."],
+  p_id: ["Pixel type.", "Piksel türü."],
+};
+
+const PATTERNS = [
+  [/^ep\.(.+)$/, (m) => [`Text event parameter: ${m[1]}.`, `Metin olay parametresi: ${m[1]}.`]],
+  [/^epn\.(.+)$/, (m) => [`Number event parameter: ${m[1]}.`, `Sayısal olay parametresi: ${m[1]}.`]],
+  [/^up\.(.+)$/, (m) => [`Text user property: ${m[1]}.`, `Metin kullanıcı özelliği: ${m[1]}.`]],
+  [/^upn\.(.+)$/, (m) => [`Number user property: ${m[1]}.`, `Sayısal kullanıcı özelliği: ${m[1]}.`]],
+  [/^pr(\d+)$/, (m) => [`Item ${m[1]}, fields separated by ~. Decoded below.`, `${m[1]}. ürün, ~ ile ayrılmış alanlar. Çözülmüş hali aşağıda.`]],
+  [/^cd\[(.+)\]$/, (m) => [`Custom data: ${m[1]}.`, `Özel veri: ${m[1]}.`]],
+  [/^ud\[(.+)\]$/, (m) => [`Advanced matching user data: ${m[1]} (should be hashed).`, `Gelişmiş eşleştirme kullanıcı verisi: ${m[1]} (karma olmalı).`]],
+  [/^properties\.(.+)$/, (m) => [`Event property: ${m[1]}.`, `Olay özelliği: ${m[1]}.`]],
+];
+
+/** The tip for a request parameter in the report language, or null. */
+export function paramTip(key, lang = "en") {
+  const i = lang === "tr" ? 1 : 0;
+  if (Object.hasOwn(G, key)) return G[key][i];
+  for (const [re, fn] of PATTERNS) {
+    const m = key.match(re);
+    if (m) return fn(m)[i];
+  }
+  return null;
+}
+
+// Parameters that describe the event itself; the rest (session, device, page, consent) are collapsed.
+const EVENT_KEYS = /^(en|ev|event|label|value|currency_code|oid|cu|ep\..*|epn\..*|pr\d+|cd\[.*\]|properties\..*|eid|event_id|events|tw_sale_amount|tw_order_quantity)$/;
+export const isEventParam = (key) => EVENT_KEYS.test(key);
+
+// GA4 item string fields (pr1=…): two-letter keys, plus kN/vN custom item parameters.
+const ITEM_FIELDS = {
+  id: "item_id", nm: "item_name", br: "item_brand", ca: "item_category", c2: "item_category2", c3: "item_category3", c4: "item_category4", c5: "item_category5",
+  va: "item_variant", pr: "price", qt: "quantity", cp: "coupon", ds: "discount", af: "affiliation", lp: "index", ln: "item_list_name", li: "item_list_id", lo: "location_id",
+  pi: "promotion_id", pn: "promotion_name", cn: "creative_name", cs: "creative_slot",
+};
+
+/**
+ * Decodes a GA4 item string ("nmShoe~id42~pr10~qt1~k0size~v0XL") into
+ * { fields: [[item_name, "Shoe"], …], custom: [["size", "XL"]] }.
+ */
+export function decodeGa4Item(s) {
+  const fields = [];
+  const names = {};
+  const values = {};
+  for (const part of String(s).split("~")) {
+    const m = part.match(/^([a-z][a-z0-9])(.*)$/);
+    if (!m) continue;
+    const [, k, v] = m;
+    if (/^k\d$/.test(k)) names[k[1]] = v;
+    else if (/^v\d$/.test(k)) values[k[1]] = v;
+    else fields.push([ITEM_FIELDS[k] ?? k, v]);
+  }
+  return { fields, custom: Object.entries(values).map(([n, v]) => [names[n] ?? `custom_${n}`, v]) };
+}