@iorg1/trackking-next 0.4.0 → 0.5.0

package/README.md

@@ -117,6 +117,45 @@ server-side). Route templates support `:name` (one path segment) and `*` (the
 rest of the path). For full control, pass `resolveEvent: (req) => string | null`
 instead of `eventRoute` — return the event name, or `null` to pass through.
 
+### Conversions
+
+A **conversion** is an event that gets attributed to the campaign the visitor
+landed with. Page views already carry the landing query string, and the collector
+turns it into a `campaign` label (`utm_campaign`, Google's auto-appended
+`gad_campaignid`, a bare `gclid`, …). A conversion adds the request's client IP +
+User-Agent; the collector hashes them into the same cookieless daily visitor id
+the page view got, discards the IP, and looks up that visitor's landing campaign
+for the day. Nothing is stored on the device, so a click and its conversion are
+linked only when they happen on the same day.
+
+Three ways to record one:
+
+```ts
+// 1. From a route handler or server action, where the action actually completes.
+//    Use @iorg1/trackking-generic and pass the request headers:
+import { headers } from "next/headers";
+import { trackConversion } from "@iorg1/trackking-generic";
+await trackConversion("report-ordered", { headers: await headers(), path: "/order" });
+
+// 2. From your middleware — e.g. when the thank-you page is requested.
+//    (A page request repeats on reload, so prefer 1 when you can.)
+import { track, trackConversion } from "@iorg1/trackking-next";
+export function middleware(req: NextRequest, event: NextFetchEvent) {
+  if (req.nextUrl.pathname === "/order/confirmed") trackConversion(req, event, "order");
+  track(req, event);
+  return NextResponse.next();
+}
+
+// 3. From the browser, through the first-party event route:
+navigator.sendBeacon("/data/signup?conversion=1");
+// …or with a body: { conversion: true, props: { plan: "pro" } }
+```
+
+If your code already knows the campaign (carried in a hidden form field, say),
+pass `campaign: "…"` and the collector skips the lookup. Plain event beacons stay
+identity-free unless you set `identifyEvents: true`, in which case they, too, are
+attributed to the visitor's campaign.
+
 ## Options
 
 ```ts
@@ -128,6 +167,7 @@ createTrackingMiddleware({
   trustedProxyHops: 1,                       // trust the right x-forwarded-for entry (see below)
   eventRoute: "/data/:event",                // first-party client-event route (see above)
   resolveEvent: (req) => …,                  // …or fully custom event extraction (overrides eventRoute)
+  identifyEvents: false,                     // attach visitor identity to plain event beacons too (see Conversions)
   eventEndpoint: process.env.TRACKKING_EVENT_ENDPOINT,
   debug: process.env.NODE_ENV !== "production", // verbose logging (see below)
 });
@@ -184,18 +224,27 @@ your server logs.
 
 ## What gets sent
 
-**Page views** — a single JSON object: `{ path, host, referrer, userAgent, ip,
-headers }`. The collector hashes `ip` into a daily-rotating visitor id **and
+**Page views** — a single JSON object: `{ path, query, host, referrer, userAgent,
+ip, headers }`. The collector hashes `ip` into a daily-rotating visitor id **and
 discards it** — the raw IP is never stored. The referrer is truncated to its
-host. `headers` is a small bag of low-entropy request headers (`Accept-Language`,
-`Accept`, the `Sec-Fetch-*` fetch-metadata set, and `Sec-CH-UA*` client hints)
-that help the collector tell real browsers from bots — it is **not** a device
-fingerprint, and no cookies or client identifiers are involved.
+host. `query` is the landing query string; the collector derives the campaign
+label from it and stores it with secret-looking parameter values (`token`,
+`code`, `email`, …) and, by default, click-id values (`gclid`, `fbclid`, …)
+redacted. `headers` is a small bag of low-entropy request headers
+(`Accept-Language`, `Accept`, the `Sec-Fetch-*` fetch-metadata set, and
+`Sec-CH-UA*` client hints) that help the collector tell real browsers from bots —
+it is **not** a device fingerprint, and no cookies or client identifiers are
+involved.
 
 **Events** (if you use the event route) — `{ name, path, props }`, carrying no
 visitor identity. `props` is an optional small, flat bag of non-PII metadata,
 re-sanitized by the collector.
 
+**Conversions** — the same, plus `conversion: true` and the request's `ip` +
+`userAgent`, which the collector hashes into the daily visitor id (IP discarded)
+to attribute the conversion to a campaign. Plain events carry identity only with
+`identifyEvents: true`.
+
 No personal identifiers are persisted.
 
 ## License

package/dist/index.cjs

@@ -27,7 +27,8 @@ __export(index_exports, {
   handleEvent: () => handleEvent,
   matchEventRoute: () => matchEventRoute,
   resolveEventName: () => resolveEventName,
-  track: () => track
+  track: () => track,
+  trackConversion: () => trackConversion
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -76,8 +77,13 @@ function parseEventBody(body) {
   if (b.props && typeof b.props === "object" && !Array.isArray(b.props)) {
     out.props = b.props;
   }
+  if (b.conversion === true) out.conversion = true;
+  if (typeof b.campaign === "string" && b.campaign.trim()) out.campaign = b.campaign.trim();
   return out;
 }
+function isTruthyParam(value) {
+  return value !== null && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
 
 // src/middleware.ts
 function trustedProxyHops(config) {
@@ -136,6 +142,9 @@ function buildEvent(req, config = {}) {
   const ipFn = config.getClientIp ?? ((r) => getClientIp(r, trustedProxyHops(config)));
   return {
     path: req.nextUrl.pathname,
+    // The landing query string is what campaign attribution is derived from
+    // (utm_*, gclid, gad_*). The collector redacts secret-looking values.
+    query: req.nextUrl.search ? req.nextUrl.search.slice(1) : null,
     host: req.nextUrl.host || req.headers.get("host"),
     referrer: req.headers.get("referer"),
     userAgent: req.headers.get("user-agent"),
@@ -206,6 +215,10 @@ function resolveEventName(req, config = {}) {
   if (!template) return null;
   return matchEventRoute(req.nextUrl.pathname, template);
 }
+function identityOf(req, config) {
+  const ipFn = config.getClientIp ?? ((r) => getClientIp(r, trustedProxyHops(config)));
+  return { ip: ipFn(req), userAgent: req.headers.get("user-agent") };
+}
 async function sendClientEvent(payload, endpoint, apiKey, debug) {
   try {
     const res = await fetch(endpoint, {
@@ -227,7 +240,8 @@ async function handleEvent(req, event, config = {}) {
   if (req.method !== "GET" && req.method !== "HEAD") {
     body = await req.json().catch(() => null);
   }
-  const { path, props } = parseEventBody(body);
+  const { path, props, conversion: bodyConversion, campaign } = parseEventBody(body);
+  const conversion = bodyConversion === true || isTruthyParam(req.nextUrl.searchParams.get("conversion"));
   const referrerPath = (() => {
     const ref = req.headers.get("referer");
     if (!ref) return void 0;
@@ -238,6 +252,9 @@ async function handleEvent(req, event, config = {}) {
     }
   })();
   const payload = { name, path: path ?? referrerPath, props };
+  if (conversion) payload.conversion = true;
+  if (campaign) payload.campaign = campaign;
+  if (conversion || config.identifyEvents) Object.assign(payload, identityOf(req, config));
   const endpoint = eventEndpointFor(config);
   const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
   if (endpoint && apiKey) {
@@ -248,6 +265,27 @@ async function handleEvent(req, event, config = {}) {
   }
   return import_server.NextResponse.json({});
 }
+function trackConversion(req, event, name, options = {}) {
+  const { path, props, campaign, ...config } = options;
+  const endpoint = eventEndpointFor(config);
+  const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
+  const debug = isDebug(config);
+  const trimmed = name.trim();
+  if (!endpoint || !apiKey || !trimmed) {
+    if (debug) log("conversion skipped: not configured (endpoint/apiKey) or empty name");
+    return;
+  }
+  const payload = {
+    name: trimmed,
+    path: path ?? req.nextUrl.pathname,
+    props,
+    conversion: true,
+    ...identityOf(req, config)
+  };
+  if (campaign) payload.campaign = campaign;
+  if (debug) log("tracking conversion:", payload);
+  event.waitUntil(sendClientEvent(payload, endpoint, apiKey, debug));
+}
 function createTrackingMiddleware(config = {}) {
   return async function middleware(req, event) {
     const eventResponse = await handleEvent(req, event, config);
@@ -265,5 +303,6 @@ function createTrackingMiddleware(config = {}) {
   handleEvent,
   matchEventRoute,
   resolveEventName,
-  track
+  track,
+  trackConversion
 });

package/dist/index.d.cts

@@ -9,6 +9,13 @@ import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
 interface TrackkingEvent {
     /** Pathname only (no query string), e.g. "/en/pricing". */
     path: string;
+    /**
+     * Raw query string without the leading "?", or null. The collector derives the
+     * `campaign` label from it (utm_campaign, Google's gad_campaignid, a gclid, …)
+     * and stores it with secret-looking parameter values — and, by default,
+     * click-id values — redacted.
+     */
+    query?: string | null;
     /** Host of the tracked site, used by the collector to drop self-referrals. */
     host: string | null;
     /** Raw `Referer` header value, or null. Truncated to its host by the collector. */
@@ -67,6 +74,14 @@ interface TrackkingConfig {
      * untouched. Overrides `eventRoute`.
      */
     resolveEvent?: (req: NextRequest) => string | null;
+    /**
+     * Attach the visitor identity — the request's client IP and User-Agent, which
+     * the collector hashes into the same daily visitor id page views get and then
+     * discards — to *every* first-party event beacon, so plain events can be
+     * attributed to the campaign the visitor landed with. Default false: events
+     * stay identity-free unless they are conversions, which always carry it.
+     */
+    identifyEvents?: boolean;
     /** Override how the client IP is extracted from the request. */
     getClientIp?: (req: NextRequest) => string | null;
     /**
@@ -86,6 +101,19 @@ interface TrackkingConfig {
      */
     debug?: boolean;
 }
+/** What a conversion records besides its name. */
+interface ConversionOptions {
+    /** The route the conversion relates to. Defaults to the request's pathname. */
+    path?: string;
+    /** Small, flat bag of non-PII metadata (re-sanitized by the collector). */
+    props?: Record<string, string | number | boolean>;
+    /**
+     * Campaign label to record instead of letting the collector attribute the
+     * conversion from the visitor's landing page view — for a flow that carried
+     * the campaign itself, e.g. in a hidden form field.
+     */
+    campaign?: string;
+}
 
 /**
  * Best-effort client IP. Behind a proxy (Vercel, Caddy, nginx) the real visitor
@@ -123,6 +151,12 @@ declare function resolveEventName(req: NextRequest, config?: TrackkingConfig): s
  * null when the request is not an event beacon — the caller should then proceed
  * with normal page-view tracking.
  *
+ * A beacon becomes a *conversion* when its body says `{ conversion: true }` or
+ * the URL carries `?conversion=1`. Conversions always travel with the visitor
+ * identity (client IP + User-Agent, hashed and discarded by the collector) so
+ * they can be attributed to the campaign the visitor landed with; plain events
+ * only do when `identifyEvents` is set.
+ *
  *   export async function middleware(req, event) {
  *     const res = await handleEvent(req, event, config);
  *     if (res) return res;              // it was a /data/<event> beacon
@@ -131,6 +165,25 @@ declare function resolveEventName(req: NextRequest, config?: TrackkingConfig): s
  *   }
  */
 declare function handleEvent(req: NextRequest, event: NextFetchEvent, config?: TrackkingConfig): Promise<NextResponse | null>;
+/**
+ * Record a conversion for the current visitor from inside your middleware — for
+ * example when the "thank you" page is requested. The collector attributes it
+ * to the campaign the visitor landed with today (last click) through the same
+ * cookieless daily hash page views use; nothing is stored on the device.
+ * Fire-and-forget; never throws.
+ *
+ *   export function middleware(req: NextRequest, event: NextFetchEvent) {
+ *     if (req.nextUrl.pathname === "/order/confirmed") trackConversion(req, event, "order");
+ *     track(req, event);
+ *     return NextResponse.next();
+ *   }
+ *
+ * A page request is repeatable (reloads, back button), so prefer recording
+ * conversions where the action actually completes — a route handler or server
+ * action — with `trackConversion` from @iorg1/trackking-generic, passing the
+ * request headers. This middleware variant is for when that isn't possible.
+ */
+declare function trackConversion(req: NextRequest, event: NextFetchEvent, name: string, options?: ConversionOptions & TrackkingConfig): void;
 /**
  * Returns a complete Next.js middleware function for the common case where
  * tracking is the only thing your middleware does. It also serves the
@@ -155,4 +208,4 @@ declare function matchEventRoute(pathname: string, template: string): string | n
  */
 declare function deriveEventEndpoint(base: string | undefined): string | undefined;
 
-export { type TrackkingConfig, type TrackkingEvent, buildEvent, createTrackingMiddleware, deriveEventEndpoint, getClientIp, handleEvent, matchEventRoute, resolveEventName, track };
+export { type ConversionOptions, type TrackkingConfig, type TrackkingEvent, buildEvent, createTrackingMiddleware, deriveEventEndpoint, getClientIp, handleEvent, matchEventRoute, resolveEventName, track, trackConversion };

package/dist/index.d.ts

@@ -9,6 +9,13 @@ import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
 interface TrackkingEvent {
     /** Pathname only (no query string), e.g. "/en/pricing". */
     path: string;
+    /**
+     * Raw query string without the leading "?", or null. The collector derives the
+     * `campaign` label from it (utm_campaign, Google's gad_campaignid, a gclid, …)
+     * and stores it with secret-looking parameter values — and, by default,
+     * click-id values — redacted.
+     */
+    query?: string | null;
     /** Host of the tracked site, used by the collector to drop self-referrals. */
     host: string | null;
     /** Raw `Referer` header value, or null. Truncated to its host by the collector. */
@@ -67,6 +74,14 @@ interface TrackkingConfig {
      * untouched. Overrides `eventRoute`.
      */
     resolveEvent?: (req: NextRequest) => string | null;
+    /**
+     * Attach the visitor identity — the request's client IP and User-Agent, which
+     * the collector hashes into the same daily visitor id page views get and then
+     * discards — to *every* first-party event beacon, so plain events can be
+     * attributed to the campaign the visitor landed with. Default false: events
+     * stay identity-free unless they are conversions, which always carry it.
+     */
+    identifyEvents?: boolean;
     /** Override how the client IP is extracted from the request. */
     getClientIp?: (req: NextRequest) => string | null;
     /**
@@ -86,6 +101,19 @@ interface TrackkingConfig {
      */
     debug?: boolean;
 }
+/** What a conversion records besides its name. */
+interface ConversionOptions {
+    /** The route the conversion relates to. Defaults to the request's pathname. */
+    path?: string;
+    /** Small, flat bag of non-PII metadata (re-sanitized by the collector). */
+    props?: Record<string, string | number | boolean>;
+    /**
+     * Campaign label to record instead of letting the collector attribute the
+     * conversion from the visitor's landing page view — for a flow that carried
+     * the campaign itself, e.g. in a hidden form field.
+     */
+    campaign?: string;
+}
 
 /**
  * Best-effort client IP. Behind a proxy (Vercel, Caddy, nginx) the real visitor
@@ -123,6 +151,12 @@ declare function resolveEventName(req: NextRequest, config?: TrackkingConfig): s
  * null when the request is not an event beacon — the caller should then proceed
  * with normal page-view tracking.
  *
+ * A beacon becomes a *conversion* when its body says `{ conversion: true }` or
+ * the URL carries `?conversion=1`. Conversions always travel with the visitor
+ * identity (client IP + User-Agent, hashed and discarded by the collector) so
+ * they can be attributed to the campaign the visitor landed with; plain events
+ * only do when `identifyEvents` is set.
+ *
  *   export async function middleware(req, event) {
  *     const res = await handleEvent(req, event, config);
  *     if (res) return res;              // it was a /data/<event> beacon
@@ -131,6 +165,25 @@ declare function resolveEventName(req: NextRequest, config?: TrackkingConfig): s
  *   }
  */
 declare function handleEvent(req: NextRequest, event: NextFetchEvent, config?: TrackkingConfig): Promise<NextResponse | null>;
+/**
+ * Record a conversion for the current visitor from inside your middleware — for
+ * example when the "thank you" page is requested. The collector attributes it
+ * to the campaign the visitor landed with today (last click) through the same
+ * cookieless daily hash page views use; nothing is stored on the device.
+ * Fire-and-forget; never throws.
+ *
+ *   export function middleware(req: NextRequest, event: NextFetchEvent) {
+ *     if (req.nextUrl.pathname === "/order/confirmed") trackConversion(req, event, "order");
+ *     track(req, event);
+ *     return NextResponse.next();
+ *   }
+ *
+ * A page request is repeatable (reloads, back button), so prefer recording
+ * conversions where the action actually completes — a route handler or server
+ * action — with `trackConversion` from @iorg1/trackking-generic, passing the
+ * request headers. This middleware variant is for when that isn't possible.
+ */
+declare function trackConversion(req: NextRequest, event: NextFetchEvent, name: string, options?: ConversionOptions & TrackkingConfig): void;
 /**
  * Returns a complete Next.js middleware function for the common case where
  * tracking is the only thing your middleware does. It also serves the
@@ -155,4 +208,4 @@ declare function matchEventRoute(pathname: string, template: string): string | n
  */
 declare function deriveEventEndpoint(base: string | undefined): string | undefined;
 
-export { type TrackkingConfig, type TrackkingEvent, buildEvent, createTrackingMiddleware, deriveEventEndpoint, getClientIp, handleEvent, matchEventRoute, resolveEventName, track };
+export { type ConversionOptions, type TrackkingConfig, type TrackkingEvent, buildEvent, createTrackingMiddleware, deriveEventEndpoint, getClientIp, handleEvent, matchEventRoute, resolveEventName, track, trackConversion };

package/dist/index.js

@@ -43,8 +43,13 @@ function parseEventBody(body) {
   if (b.props && typeof b.props === "object" && !Array.isArray(b.props)) {
     out.props = b.props;
   }
+  if (b.conversion === true) out.conversion = true;
+  if (typeof b.campaign === "string" && b.campaign.trim()) out.campaign = b.campaign.trim();
   return out;
 }
+function isTruthyParam(value) {
+  return value !== null && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
 
 // src/middleware.ts
 function trustedProxyHops(config) {
@@ -103,6 +108,9 @@ function buildEvent(req, config = {}) {
   const ipFn = config.getClientIp ?? ((r) => getClientIp(r, trustedProxyHops(config)));
   return {
     path: req.nextUrl.pathname,
+    // The landing query string is what campaign attribution is derived from
+    // (utm_*, gclid, gad_*). The collector redacts secret-looking values.
+    query: req.nextUrl.search ? req.nextUrl.search.slice(1) : null,
     host: req.nextUrl.host || req.headers.get("host"),
     referrer: req.headers.get("referer"),
     userAgent: req.headers.get("user-agent"),
@@ -173,6 +181,10 @@ function resolveEventName(req, config = {}) {
   if (!template) return null;
   return matchEventRoute(req.nextUrl.pathname, template);
 }
+function identityOf(req, config) {
+  const ipFn = config.getClientIp ?? ((r) => getClientIp(r, trustedProxyHops(config)));
+  return { ip: ipFn(req), userAgent: req.headers.get("user-agent") };
+}
 async function sendClientEvent(payload, endpoint, apiKey, debug) {
   try {
     const res = await fetch(endpoint, {
@@ -194,7 +206,8 @@ async function handleEvent(req, event, config = {}) {
   if (req.method !== "GET" && req.method !== "HEAD") {
     body = await req.json().catch(() => null);
   }
-  const { path, props } = parseEventBody(body);
+  const { path, props, conversion: bodyConversion, campaign } = parseEventBody(body);
+  const conversion = bodyConversion === true || isTruthyParam(req.nextUrl.searchParams.get("conversion"));
   const referrerPath = (() => {
     const ref = req.headers.get("referer");
     if (!ref) return void 0;
@@ -205,6 +218,9 @@ async function handleEvent(req, event, config = {}) {
     }
   })();
   const payload = { name, path: path ?? referrerPath, props };
+  if (conversion) payload.conversion = true;
+  if (campaign) payload.campaign = campaign;
+  if (conversion || config.identifyEvents) Object.assign(payload, identityOf(req, config));
   const endpoint = eventEndpointFor(config);
   const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
   if (endpoint && apiKey) {
@@ -215,6 +231,27 @@ async function handleEvent(req, event, config = {}) {
   }
   return NextResponse.json({});
 }
+function trackConversion(req, event, name, options = {}) {
+  const { path, props, campaign, ...config } = options;
+  const endpoint = eventEndpointFor(config);
+  const apiKey = config.apiKey ?? process.env.TRACKKING_API_KEY;
+  const debug = isDebug(config);
+  const trimmed = name.trim();
+  if (!endpoint || !apiKey || !trimmed) {
+    if (debug) log("conversion skipped: not configured (endpoint/apiKey) or empty name");
+    return;
+  }
+  const payload = {
+    name: trimmed,
+    path: path ?? req.nextUrl.pathname,
+    props,
+    conversion: true,
+    ...identityOf(req, config)
+  };
+  if (campaign) payload.campaign = campaign;
+  if (debug) log("tracking conversion:", payload);
+  event.waitUntil(sendClientEvent(payload, endpoint, apiKey, debug));
+}
 function createTrackingMiddleware(config = {}) {
   return async function middleware(req, event) {
     const eventResponse = await handleEvent(req, event, config);
@@ -231,5 +268,6 @@ export {
   handleEvent,
   matchEventRoute,
   resolveEventName,
-  track
+  track,
+  trackConversion
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@iorg1/trackking-next",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/iorg1/trackking.git",
     "directory": "packages/middleware"
   },
-  "description": "Cookieless, server-side page-view tracking for Next.js. Drop-in middleware that beacons visits to a Trackking collector — no cookies, no client-side script.",
+  "description": "Cookieless, server-side page-view tracking for Next.js. Drop-in middleware that beacons visits to a Trackking collector \u2014 no cookies, no client-side script.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",