@punchline-analytics/next 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -22,6 +22,14 @@ interface EdgeEvent {
22
22
  mintedHandoff?: string;
23
23
  clicks?: Record<string, string>;
24
24
  accept: string | null;
25
+ query?: string;
26
+ browserHeaders?: {
27
+ fetch: boolean;
28
+ hints: boolean;
29
+ lang: boolean;
30
+ };
31
+ visitorId?: string;
32
+ consent?: true;
25
33
  ip: string;
26
34
  userAgent: string;
27
35
  gpc: boolean;
@@ -47,6 +55,16 @@ interface Dsn {
47
55
  siteId: string;
48
56
  secret: string;
49
57
  }
58
+ interface TrackResult {
59
+ /** Time spent on the request path, or null if the request wasn't tracked. */
60
+ overheadMs: number | null;
61
+ /**
62
+ * A Set-Cookie value for the response: a new visitor cookie, or one that
63
+ * clears it (Global Privacy Control, or the site stopped remembering this
64
+ * visitor). Only when the site remembers visitors (its visitor modes).
65
+ */
66
+ setCookie?: string;
67
+ }
50
68
  /** On Vercel, x-forwarded-for is set by the platform to the real client IP. */
51
69
  declare function readVercelFacts(request: Request): RequestFacts;
52
70
  /** https://<siteId>:<secret>@<host>/<path>. http is allowed only for localhost. */
@@ -76,10 +94,12 @@ declare function punchline(options?: PunchlineOptions): (request: NextRequest, e
76
94
  /** For sites with their own proxy: call `track(request, event)` inside it. */
77
95
  declare function createTracker(options?: PunchlineOptions): {
78
96
  serverTiming: boolean;
79
- /** Returns the time spent on the request path, or null if it wasn't tracked. */
80
- track(request: NextRequest, event: Pick<NextFetchEvent, "waitUntil">): {
81
- overheadMs: number | null;
82
- };
97
+ /**
98
+ * Returns the time spent on the request path (null if it wasn't tracked),
99
+ * and a Set-Cookie value to add to the response when the site remembers
100
+ * visitors (a new visitor cookie, or one that clears it).
101
+ */
102
+ track(request: NextRequest, event: Pick<NextFetchEvent, "waitUntil">): TrackResult;
83
103
  /** Whether "Serve AI agents markdown" is on for this site (off until the settings load). */
84
104
  markdownOn(event: Pick<NextFetchEvent, "waitUntil">): boolean;
85
105
  /** The proxy's own HTML fetch for a markdown answer. */
package/dist/index.js CHANGED
@@ -12,6 +12,64 @@ var CLICK_ID_PARAMS = ["gclid", "gbraid", "wbraid", "fbclid"];
12
12
  var CLICK_ID = /^[A-Za-z0-9_.-]{8,500}$/;
13
13
  var HANDOFF_PARAM = "pl_ho";
14
14
  var HANDOFF_TOKEN = /^[A-Za-z0-9]{24}$/;
15
+ var VISITOR_COOKIE = "_pl_vid";
16
+ var CONSENT_COOKIE = "_pl_consent";
17
+ var VISITOR_ID = /^[A-Za-z0-9]{22}$/;
18
+ var VISITOR_COOKIE_MAX_AGE_S = 395 * 24 * 60 * 60;
19
+
20
+ // ../schema/src/url-params.ts
21
+ var SENSITIVE_PARAM = /^(e-?mail|mail|email_?address|phone|tel|mobile|name|first_?name|last_?name|full_?name|address|zip|postcode|dob|birthday|ssn|uid|user_?id|userid|user|username|login|customer_?id|account_?id|member_?id|contact_?id|token|access_?token|id_?token|refresh_?token|auth|authorization|code_?verifier|password|passwd|pwd|pass|secret|api_?key|key|session|session_?id|sid|jwt|otp|reset_?token|ip)$/i;
22
+
23
+ // ../schema/src/beacon.ts
24
+ var CONSENT_REGION = /* @__PURE__ */ new Set([
25
+ "AT",
26
+ "BE",
27
+ "BG",
28
+ "HR",
29
+ "CY",
30
+ "CZ",
31
+ "DK",
32
+ "EE",
33
+ "FI",
34
+ "FR",
35
+ "DE",
36
+ "GR",
37
+ "HU",
38
+ "IE",
39
+ "IT",
40
+ "LV",
41
+ "LT",
42
+ "LU",
43
+ "MT",
44
+ "NL",
45
+ "PL",
46
+ "PT",
47
+ "RO",
48
+ "SK",
49
+ "SI",
50
+ "ES",
51
+ "SE",
52
+ "IS",
53
+ "LI",
54
+ "NO",
55
+ "GB",
56
+ "CH"
57
+ ]);
58
+
59
+ // ../schema/src/visitor-modes.ts
60
+ var VISITOR_MODES_OFF = { remember: false, fullUrls: false, consentRegion: "consent" };
61
+ function parseVisitorModes(raw) {
62
+ const r = raw && typeof raw === "object" ? raw : {};
63
+ return { remember: r.remember === true, fullUrls: r.fullUrls === true, consentRegion: r.consentRegion === "always" ? "always" : "consent" };
64
+ }
65
+ function inConsentRegion(country) {
66
+ return !country || CONSENT_REGION.has(country.toUpperCase());
67
+ }
68
+ function visitorModeFor(modes, v) {
69
+ if (v.gpc) return { remember: false, fullUrls: false };
70
+ const allowed = !inConsentRegion(v.country) || modes.consentRegion === "always" || v.consent;
71
+ return { remember: modes.remember && allowed, fullUrls: modes.fullUrls && allowed };
72
+ }
15
73
 
16
74
  // ../privacy/src/url.ts
17
75
  var UTM_VALUE_MAX_LENGTH = 200;
@@ -61,6 +119,22 @@ function truncateAccept(accept) {
61
119
  function redactEmails(value) {
62
120
  return value.replace(EMAIL, "[email]");
63
121
  }
122
+ var CREDENTIAL_PARAM = /(^|[_.-])(token|access[_-]?token|id[_-]?token|refresh[_-]?token|password|passwd|pass|pwd|secret|key|api[_-]?key|apikey|auth|authorization|code|session|sessionid|sid|sig|signature|otp|jwt|nonce|state|ticket|hash|pl_ho)$/i;
123
+ var QUERY_MAX_LENGTH = 1024;
124
+ function redactQuery(search, max = QUERY_MAX_LENGTH) {
125
+ const raw = search.startsWith("?") ? search.slice(1) : search;
126
+ if (!raw) return null;
127
+ let params;
128
+ try {
129
+ params = new URLSearchParams(raw);
130
+ } catch {
131
+ return null;
132
+ }
133
+ const out = new URLSearchParams();
134
+ for (const [k, v] of params) out.append(redactEmails(k).slice(0, 100), SENSITIVE_PARAM.test(k) || CREDENTIAL_PARAM.test(k) ? "[redacted]" : redactEmails(v).slice(0, 500));
135
+ const text = out.toString();
136
+ return text ? text.slice(0, max) : null;
137
+ }
64
138
  function safeDecode(path) {
65
139
  try {
66
140
  return decodeURIComponent(path);
@@ -332,6 +406,7 @@ function createSiteConfig(fetchTimeoutMs = 3e3, now = Date.now) {
332
406
  let allowed = [];
333
407
  let markdown = MARKDOWN_OFF;
334
408
  let clickIds = [];
409
+ let visitors = VISITOR_MODES_OFF;
335
410
  let nextAt = 0;
336
411
  let inFlight = false;
337
412
  let known = false;
@@ -353,6 +428,11 @@ function createSiteConfig(fetchTimeoutMs = 3e3, now = Date.now) {
353
428
  if (!known && pending) await Promise.race([pending, new Promise((r) => setTimeout(r, maxWaitMs))]);
354
429
  return markdown;
355
430
  },
431
+ /** The site's visitor modes (off until known), and whether they're known yet. */
432
+ visitors(dsn, waitUntil) {
433
+ config.allowed(dsn, waitUntil);
434
+ return { modes: visitors, known };
435
+ },
356
436
  /** Ad click ID parameters the site opted in to capture (none until known). */
357
437
  clickIds(dsn, waitUntil) {
358
438
  config.allowed(dsn, waitUntil);
@@ -370,6 +450,7 @@ function createSiteConfig(fetchTimeoutMs = 3e3, now = Date.now) {
370
450
  const v = Array.isArray(body.params) ? body.params : [];
371
451
  allowed = v.filter((p) => typeof p?.name === "string" && (p.mode === "presence" || p.mode === "value")).slice(0, 20);
372
452
  markdown = parseMarkdownSettings(body.markdown);
453
+ visitors = parseVisitorModes(body.visitors);
373
454
  clickIds = Array.isArray(body.clickIds) ? body.clickIds.filter((c) => ["gclid", "gbraid", "wbraid", "fbclid"].includes(c)) : [];
374
455
  nextAt = now() + 3e5;
375
456
  known = true;
@@ -401,13 +482,7 @@ async function toMarkdownResponse(html, pageUrl) {
401
482
  return new Response(htmlToMarkdown(text, pageUrl), { status: 200, headers });
402
483
  }
403
484
  async function withShareLink(md, pageUrl) {
404
- const bytes = crypto.getRandomValues(new Uint8Array(24));
405
- const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
406
- let token = "";
407
- while (token.length < 24) {
408
- for (const b of bytes) if (b < 248 && token.length < 24) token += ALPHABET[b % 62];
409
- if (token.length < 24) crypto.getRandomValues(bytes);
410
- }
485
+ const token = randomBase62(24);
411
486
  const u = new URL(pageUrl);
412
487
  const link = `${u.origin}${u.pathname}?${HANDOFF_PARAM}=${token}`;
413
488
  const body = `${(await md.text()).replace(/\s+$/, "")}
@@ -423,6 +498,38 @@ Share link to this page: ${link}
423
498
  const tokenHash = Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
424
499
  return { response: new Response(body, { status: md.status, headers }), tokenHash };
425
500
  }
501
+ function randomBase62(n) {
502
+ const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
503
+ const bytes = crypto.getRandomValues(new Uint8Array(n));
504
+ let out = "";
505
+ while (out.length < n) {
506
+ for (const b of bytes) if (b < 248 && out.length < n) out += ALPHABET[b % 62];
507
+ if (out.length < n) crypto.getRandomValues(bytes);
508
+ }
509
+ return out;
510
+ }
511
+ function readCookie(header, name) {
512
+ for (const part of (header ?? "").split(";")) {
513
+ const i = part.indexOf("=");
514
+ if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
515
+ }
516
+ return null;
517
+ }
518
+ function rememberVisitor(request, event, visitors) {
519
+ const cookie = request.headers.get("cookie");
520
+ const existing = readCookie(cookie, VISITOR_COOKIE);
521
+ const consent = readCookie(cookie, CONSENT_COOKIE) === "1";
522
+ const mode = visitorModeFor(visitors.modes, { country: event.country ?? null, consent, gpc: event.gpc });
523
+ const secure = new URL(request.url).protocol === "https:" ? "; Secure" : "";
524
+ if (mode.remember) {
525
+ const id = existing && VISITOR_ID.test(existing) ? existing : randomBase62(22);
526
+ event.visitorId = id;
527
+ if (consent) event.consent = true;
528
+ return id === existing ? void 0 : `${VISITOR_COOKIE}=${id}; Max-Age=${VISITOR_COOKIE_MAX_AGE_S}; Path=/; SameSite=Lax${secure}`;
529
+ }
530
+ if (consent) event.consent = true;
531
+ return existing !== null && (visitors.known || event.gpc) ? `${VISITOR_COOKIE}=; Max-Age=0; Path=/; SameSite=Lax${secure}` : void 0;
532
+ }
426
533
  function readVercelFacts(request) {
427
534
  const h = request.headers;
428
535
  const vercelSignals = {};
@@ -461,7 +568,9 @@ function createTracker(options) {
461
568
  try {
462
569
  const config = resolveDsn();
463
570
  if (!config || !shouldTrack(request)) return { overheadMs: null };
464
- const event = buildEvent(request, config.siteId, options.readFacts(request), Date.now(), siteConfig.allowed(config, waitUntil), siteConfig.clickIds(config, waitUntil));
571
+ const facts = options.readFacts(request);
572
+ const event = buildEvent(request, config.siteId, facts, Date.now(), siteConfig.allowed(config, waitUntil), siteConfig.clickIds(config, waitUntil));
573
+ const setCookie = rememberVisitor(request, event, siteConfig.visitors(config, waitUntil));
465
574
  const send = (e) => fetch(config.collectorUrl, {
466
575
  method: "POST",
467
576
  headers: { authorization: `Bearer ${config.secret}`, "content-type": "application/json" },
@@ -476,7 +585,7 @@ function createTracker(options) {
476
585
  () => event
477
586
  ).then(send) : send(event);
478
587
  waitUntil(sent.catch(onError));
479
- return { overheadMs: performance.now() - start };
588
+ return { overheadMs: performance.now() - start, ...setCookie ? { setCookie } : {} };
480
589
  } catch (err) {
481
590
  onError(err);
482
591
  return { overheadMs: null };
@@ -539,6 +648,7 @@ function shouldTrack(request) {
539
648
  function buildEvent(request, siteId, facts, now = Date.now(), allowed = [], clickTypes = []) {
540
649
  const h = request.headers;
541
650
  const { host, path, utm, params, handoff, clicks } = sanitizeUrl(request.url, allowed, clickTypes);
651
+ const query = redactQuery(new URL(request.url).search);
542
652
  const signature = h.get("signature");
543
653
  const signatureInput = h.get("signature-input");
544
654
  const signatureAgent = h.get("signature-agent");
@@ -556,6 +666,9 @@ function buildEvent(request, siteId, facts, now = Date.now(), allowed = [], clic
556
666
  ...handoff ? { handoff } : {},
557
667
  ...clicks ? { clicks } : {},
558
668
  accept: truncateAccept(h.get("accept")),
669
+ ...query ? { query } : {},
670
+ // Presence only, never values: scripts that borrow a browser's name rarely send these (R15).
671
+ browserHeaders: { fetch: h.has("sec-fetch-dest") || h.has("sec-fetch-mode"), hints: h.has("sec-ch-ua"), lang: h.has("accept-language") },
559
672
  ip: (facts.ip || "unknown").slice(0, 45),
560
673
  userAgent: h.get("user-agent") ?? "",
561
674
  gpc: h.get("sec-gpc") === "1",
@@ -585,8 +698,9 @@ function punchline(options = {}) {
585
698
  if (await tracker.isInternal(request)) return NextResponse.next();
586
699
  const markdown = await tracker.serveMarkdown(request, event);
587
700
  if (markdown) return new NextResponse(markdown.body, markdown);
588
- const { overheadMs } = tracker.track(request, event);
701
+ const { overheadMs, setCookie } = tracker.track(request, event);
589
702
  const response = NextResponse.next();
703
+ if (setCookie) response.headers.append("Set-Cookie", setCookie);
590
704
  if (tracker.markdownOn(event) && isPagePath(request)) response.headers.append("Link", markdownLink(request.url));
591
705
  if (overheadMs !== null) response.headers.set("Server-Timing", tracker.serverTiming ? `${COUNTED_TIMING}, punchline;dur=${overheadMs.toFixed(3)}` : COUNTED_TIMING);
592
706
  return response;
@@ -617,7 +731,11 @@ function createTracker2(options = {}) {
617
731
  })();
618
732
  return {
619
733
  serverTiming: options.serverTiming ?? (process.env.PUNCHLINE_SERVER_TIMING || process.env.AGENTLENS_SERVER_TIMING) === "1",
620
- /** Returns the time spent on the request path, or null if it wasn't tracked. */
734
+ /**
735
+ * Returns the time spent on the request path (null if it wasn't tracked),
736
+ * and a Set-Cookie value to add to the response when the site remembers
737
+ * visitors (a new visitor cookie, or one that clears it).
738
+ */
621
739
  track(request, event) {
622
740
  return tracker.track(request, (p) => event.waitUntil(p));
623
741
  },
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@punchline-analytics/next",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "See which visitors are AI agents: Next.js middleware/proxy for Punchline Analytics. Forwards a minimal, privacy-reduced event per page request.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
- "homepage": "https://punchline-site-tawny.vercel.app/docs/install-nextjs",
7
+ "homepage": "https://punchlineanalytics.com/docs/install-nextjs",
8
8
  "keywords": [
9
9
  "analytics",
10
10
  "ai-agents",