@punchline-analytics/next 0.1.0 → 0.2.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 +19 -4
- package/dist/index.js +127 -11
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -22,6 +22,9 @@ interface EdgeEvent {
|
|
|
22
22
|
mintedHandoff?: string;
|
|
23
23
|
clicks?: Record<string, string>;
|
|
24
24
|
accept: string | null;
|
|
25
|
+
query?: string;
|
|
26
|
+
visitorId?: string;
|
|
27
|
+
consent?: true;
|
|
25
28
|
ip: string;
|
|
26
29
|
userAgent: string;
|
|
27
30
|
gpc: boolean;
|
|
@@ -47,6 +50,16 @@ interface Dsn {
|
|
|
47
50
|
siteId: string;
|
|
48
51
|
secret: string;
|
|
49
52
|
}
|
|
53
|
+
interface TrackResult {
|
|
54
|
+
/** Time spent on the request path, or null if the request wasn't tracked. */
|
|
55
|
+
overheadMs: number | null;
|
|
56
|
+
/**
|
|
57
|
+
* A Set-Cookie value for the response: a new visitor cookie, or one that
|
|
58
|
+
* clears it (Global Privacy Control, or the site stopped remembering this
|
|
59
|
+
* visitor). Only when the site remembers visitors (its visitor modes).
|
|
60
|
+
*/
|
|
61
|
+
setCookie?: string;
|
|
62
|
+
}
|
|
50
63
|
/** On Vercel, x-forwarded-for is set by the platform to the real client IP. */
|
|
51
64
|
declare function readVercelFacts(request: Request): RequestFacts;
|
|
52
65
|
/** https://<siteId>:<secret>@<host>/<path>. http is allowed only for localhost. */
|
|
@@ -76,10 +89,12 @@ declare function punchline(options?: PunchlineOptions): (request: NextRequest, e
|
|
|
76
89
|
/** For sites with their own proxy: call `track(request, event)` inside it. */
|
|
77
90
|
declare function createTracker(options?: PunchlineOptions): {
|
|
78
91
|
serverTiming: boolean;
|
|
79
|
-
/**
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
92
|
+
/**
|
|
93
|
+
* Returns the time spent on the request path (null if it wasn't tracked),
|
|
94
|
+
* and a Set-Cookie value to add to the response when the site remembers
|
|
95
|
+
* visitors (a new visitor cookie, or one that clears it).
|
|
96
|
+
*/
|
|
97
|
+
track(request: NextRequest, event: Pick<NextFetchEvent, "waitUntil">): TrackResult;
|
|
83
98
|
/** Whether "Serve AI agents markdown" is on for this site (off until the settings load). */
|
|
84
99
|
markdownOn(event: Pick<NextFetchEvent, "waitUntil">): boolean;
|
|
85
100
|
/** 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
|
|
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
|
|
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,7 @@ 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 } : {},
|
|
559
670
|
ip: (facts.ip || "unknown").slice(0, 45),
|
|
560
671
|
userAgent: h.get("user-agent") ?? "",
|
|
561
672
|
gpc: h.get("sec-gpc") === "1",
|
|
@@ -585,8 +696,9 @@ function punchline(options = {}) {
|
|
|
585
696
|
if (await tracker.isInternal(request)) return NextResponse.next();
|
|
586
697
|
const markdown = await tracker.serveMarkdown(request, event);
|
|
587
698
|
if (markdown) return new NextResponse(markdown.body, markdown);
|
|
588
|
-
const { overheadMs } = tracker.track(request, event);
|
|
699
|
+
const { overheadMs, setCookie } = tracker.track(request, event);
|
|
589
700
|
const response = NextResponse.next();
|
|
701
|
+
if (setCookie) response.headers.append("Set-Cookie", setCookie);
|
|
590
702
|
if (tracker.markdownOn(event) && isPagePath(request)) response.headers.append("Link", markdownLink(request.url));
|
|
591
703
|
if (overheadMs !== null) response.headers.set("Server-Timing", tracker.serverTiming ? `${COUNTED_TIMING}, punchline;dur=${overheadMs.toFixed(3)}` : COUNTED_TIMING);
|
|
592
704
|
return response;
|
|
@@ -617,7 +729,11 @@ function createTracker2(options = {}) {
|
|
|
617
729
|
})();
|
|
618
730
|
return {
|
|
619
731
|
serverTiming: options.serverTiming ?? (process.env.PUNCHLINE_SERVER_TIMING || process.env.AGENTLENS_SERVER_TIMING) === "1",
|
|
620
|
-
/**
|
|
732
|
+
/**
|
|
733
|
+
* Returns the time spent on the request path (null if it wasn't tracked),
|
|
734
|
+
* and a Set-Cookie value to add to the response when the site remembers
|
|
735
|
+
* visitors (a new visitor cookie, or one that clears it).
|
|
736
|
+
*/
|
|
621
737
|
track(request, event) {
|
|
622
738
|
return tracker.track(request, (p) => event.waitUntil(p));
|
|
623
739
|
},
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@punchline-analytics/next",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.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://
|
|
7
|
+
"homepage": "https://punchlineanalytics.com/docs/install-nextjs",
|
|
8
8
|
"keywords": [
|
|
9
9
|
"analytics",
|
|
10
10
|
"ai-agents",
|