@shware/analytics 8.16.0 → 9.0.1

package/dist/track/index.d.cts

@@ -6,7 +6,24 @@ export interface TrackOptions {
   onError?: (error: unknown) => void;
 }
 export declare function track<T extends EventName = EventName>(name: TrackName<T>, properties?: TrackProperties<T>, options?: TrackOptions): void;
+/**
+ * Sends the event now, with whatever is queued, and resolves once it has been sent or lost — or,
+ * when no visitor could be created to send it with, at once, the event left queued for the next
+ * send. It never rejects: tracking must not fail the step that awaits it.
+ */
 export declare function trackAsync<T extends EventName = EventName>(name: TrackName<T>, properties?: TrackProperties<T>, options?: TrackOptions): Promise<void>;
+/**
+ * Sends the queue by beacon, now: for when the page is hidden or left, the last moment its
+ * script is sure to run — what PostHog's `requestQueue.unload()` and GA4 do on the same events.
+ * Call it before the engagement beacon: a new session's `session_start` is in this queue.
+ *
+ * Nothing can be awaited here, so the events go with the tags they have settled on (the last
+ * built ones otherwise), and without the server's ids: their third-party trackers are not fired,
+ * as an id-less browser event could not be deduplicated against the server's. When no beacon can
+ * take them — a visitor the server does not know yet, no `sendBeacon`, a refused body — they stay
+ * queued for the usual send, which also creates the visitor.
+ */
+export declare function sendPendingEvents(): void;
 export declare function sendBeacon<T extends EventName = EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
 //#endregion
 //# sourceMappingURL=index.d.cts.map

package/dist/track/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/track/index.ts"],"mappings":";;iBASiB;EACf;EACA,aAAa,WAAW;EACxB,WAAW;;wBAyLG,MAAM,UAAU,YAAY,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS;wBAiBW,WAAW,UAAU,YAAY,WACrD,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS,eAA6B;wBAOxB,WAAW,UAAU,YAAY,WAC/C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/track/index.ts"],"mappings":";;iBASiB;EACf;EACA,aAAa,WAAW;EACxB,WAAW;;wBA6KG,MAAM,UAAU,YAAY,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS;;;;;;wBAgBW,WAAW,UAAU,YAAY,WACrD,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS,eAA6B;;;;;;;;;;;;wBAyDxB;wBAwBA,WAAW,UAAU,YAAY,WAC/C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}

package/dist/track/index.d.mts

@@ -6,7 +6,24 @@ export interface TrackOptions {
   onError?: (error: unknown) => void;
 }
 export declare function track<T extends EventName = EventName>(name: TrackName<T>, properties?: TrackProperties<T>, options?: TrackOptions): void;
+/**
+ * Sends the event now, with whatever is queued, and resolves once it has been sent or lost — or,
+ * when no visitor could be created to send it with, at once, the event left queued for the next
+ * send. It never rejects: tracking must not fail the step that awaits it.
+ */
 export declare function trackAsync<T extends EventName = EventName>(name: TrackName<T>, properties?: TrackProperties<T>, options?: TrackOptions): Promise<void>;
+/**
+ * Sends the queue by beacon, now: for when the page is hidden or left, the last moment its
+ * script is sure to run — what PostHog's `requestQueue.unload()` and GA4 do on the same events.
+ * Call it before the engagement beacon: a new session's `session_start` is in this queue.
+ *
+ * Nothing can be awaited here, so the events go with the tags they have settled on (the last
+ * built ones otherwise), and without the server's ids: their third-party trackers are not fired,
+ * as an id-less browser event could not be deduplicated against the server's. When no beacon can
+ * take them — a visitor the server does not know yet, no `sendBeacon`, a refused body — they stay
+ * queued for the usual send, which also creates the visitor.
+ */
+export declare function sendPendingEvents(): void;
 export declare function sendBeacon<T extends EventName = EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
 //#endregion
 //# sourceMappingURL=index.d.mts.map

package/dist/track/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/track/index.ts"],"mappings":";;iBASiB;EACf;EACA,aAAa,WAAW;EACxB,WAAW;;wBAyLG,MAAM,UAAU,YAAY,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS;wBAiBW,WAAW,UAAU,YAAY,WACrD,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS,eAA6B;wBAOxB,WAAW,UAAU,YAAY,WAC/C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/track/index.ts"],"mappings":";;iBASiB;EACf;EACA,aAAa,WAAW;EACxB,WAAW;;wBA6KG,MAAM,UAAU,YAAY,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS;;;;;;wBAgBW,WAAW,UAAU,YAAY,WACrD,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B,UAAS,eAA6B;;;;;;;;;;;;wBAyDxB;wBAwBA,WAAW,UAAU,YAAY,WAC/C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}

package/dist/track/index.mjs

@@ -38,145 +38,211 @@ async function captureTags() {
 	}
 }
 /**
-* The `session_start` a failed batch took down with it, kept for the next batch of the same
-* session. `fetch` has already retried the transient failures by the time a batch fails here;
-* what remains is a batch the server rejected outright — one invalid event fails the whole batch,
-* and `session_start` with it — or a network that stayed down past the retries. Neither is a
-* reason to lose the session's one attribution record, so it goes out again, with the tags and
-* timestamp of the moment the session actually began, under the same session id. Held in memory
-* only: a reload loses it, and with it the session_start — the same as before this existed.
+* The events not yet sent, and the only place they are: a batch leaves it at the moment it is
+* handed to `fetch` or to a beacon, never earlier. So when the page is hidden or left,
+* everything still unsent is right here for `sendPendingEvents`.
 */
-let pendingStart;
-async function sendEvents(events) {
-	/** The announcement this batch carries, if any, so the catch below can hold it back. */
-	let announcement;
+const list = [];
+const batchSize = 10;
+const delay = 2e3;
+let timer = null;
+/**
+* Queues an event, preceded by a `session_start` when it is the one that opens a session.
+*
+* The session is decided here, when the event happens, as GA4 and PostHog decide it: the
+* `session_start` then sits in the queue right before the event that opened the session, so
+* wherever that event goes — a batch, a beacon, a retry — its announcement has gone ahead of it.
+* It carries that event's tags and time, as GA4 derives it from the hit that started the
+* session: the landing page is where the session began, whatever the page has navigated to by
+* the time the batch goes out.
+*/
+function enqueue(name, properties, options) {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const tags = captureTags();
+	const { id: session_id, started } = getSession().touch(Date.parse(timestamp));
+	const item = (fields) => {
+		const result = {
+			...fields,
+			tags,
+			timestamp,
+			session_id
+		};
+		tags.then((settled) => result.settled = settled);
+		return result;
+	};
+	if (started) list.push(item({
+		name: "session_start",
+		properties: {},
+		options: { enableThirdPartyTracking: false }
+	}));
+	const event = item({
+		name,
+		properties,
+		options
+	});
+	list.push(event);
+	return event;
+}
+/**
+* Sends the queue. Everything that has to be awaited is awaited first, and only then are the
+* events taken off the queue and handed to `fetch` in the same synchronous step — so there is
+* no moment at which an event is neither queued nor sent.
+*/
+async function flush() {
+	if (timer) {
+		clearTimeout(timer);
+		timer = null;
+	}
+	if (list.length === 0) return;
+	let events = [];
 	try {
-		if (events.length === 0) return;
-		const opening = events[0];
-		const { id: session_id, started } = getSession().touch(Date.parse(opening.timestamp), Date.parse(events[events.length - 1].timestamp));
-		if (started || pendingStart?.session_id === session_id) {
-			const start = pendingStart?.session_id === session_id ? pendingStart.item : {
-				name: "session_start",
-				properties: {},
-				options: { enableThirdPartyTracking: false },
-				tags: opening.tags,
-				timestamp: opening.timestamp
-			};
-			pendingStart = void 0;
-			announcement = {
-				session_id,
-				item: start
-			};
-			events.unshift(start);
-		}
 		await getTokenBucket().removeTokens();
 		const visitor_id = (await getVisitor()).id;
+		const headers = await config.getHeaders();
+		await Promise.all(list.map((event) => event.tags));
+		events = list.splice(0);
+		if (events.length === 0) return;
 		const dto = await Promise.all(events.map(async (event) => ({
 			name: event.name,
 			properties: event.properties,
 			tags: await event.tags,
 			visitor_id,
-			session_id,
+			session_id: event.session_id,
 			platform: config.platform,
 			environment: config.environment,
 			timestamp: event.timestamp
 		})));
+		const body = JSON.stringify(dto);
 		const response = await fetch(`${config.endpoint}/events`, {
 			method: "POST",
 			credentials: "include",
-			keepalive: true,
-			headers: await config.getHeaders(),
-			body: JSON.stringify(dto)
+			keepalive: body.length < 6e4,
+			headers,
+			body
 		});
 		if (!response.ok) throw new Error(`Failed to send track event: ${response.status} ${await response.text()}`);
 		const data = await response.json();
-		let index = 0;
-		while (events.length > 0) {
-			const event = events.shift();
-			if (!event) {
-				index++;
-				continue;
-			}
-			const { options, name, properties } = event;
+		events.forEach((event, index) => {
 			const eventId = data.at(index)?.id;
-			options.onSucceed?.(eventId ? { id: eventId } : void 0);
-			index++;
-			if (options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(name)) continue;
+			event.options.onSucceed?.(eventId ? { id: eventId } : void 0);
+			if (event.options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(event.name)) return;
 			config.thirdPartyTrackers.forEach((tracker) => {
 				try {
-					tracker(name, properties, eventId);
+					tracker(event.name, event.properties, eventId);
 				} catch (e) {
 					if (e instanceof Error) console.log(e.message);
 				}
 			});
-		}
+		});
 	} catch (e) {
 		if (e instanceof Error) console.log(e.message);
-		if (announcement) pendingStart = announcement;
-		events.forEach((event) => event.options.onError?.(e));
-	}
-}
-const batch = 10;
-const delay = 2e3;
-const list = [];
-let timer = null;
-/**
-* Both paths into a send go through here, so a batch that fills up cancels the timer the
-* previous push armed rather than leaving it to wake up on its own with nothing to send.
-*/
-function flush() {
-	if (timer) {
-		clearTimeout(timer);
-		timer = null;
+		const starts = events.filter((event) => event.name === "session_start");
+		list.unshift(...starts);
+		events.filter((event) => event.name !== "session_start").forEach((event) => event.options.onError?.(e));
 	}
-	if (list.length === 0) return;
-	const copy = [...list];
-	list.length = 0;
-	sendEvents(copy);
 }
 function track(name, properties, options = defaultOptions) {
-	list.push({
-		name,
-		properties,
-		options,
-		tags: captureTags(),
-		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	});
-	if (list.length >= batch) {
+	enqueue(name, properties, options);
+	if (list.length >= batchSize) {
 		flush();
 		return;
 	}
 	if (timer) clearTimeout(timer);
-	timer = setTimeout(flush, delay);
+	timer = setTimeout(() => void flush(), delay);
 }
+/**
+* Sends the event now, with whatever is queued, and resolves once it has been sent or lost — or,
+* when no visitor could be created to send it with, at once, the event left queued for the next
+* send. It never rejects: tracking must not fail the step that awaits it.
+*/
 async function trackAsync(name, properties, options = defaultOptions) {
-	await sendEvents([{
-		name,
-		properties,
-		options,
-		tags: captureTags(),
-		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	}]);
+	let settle;
+	const settled = new Promise((resolve) => {
+		settle = resolve;
+	});
+	const event = enqueue(name, properties, {
+		...options,
+		onSucceed: (response) => {
+			options.onSucceed?.(response);
+			settle();
+		},
+		onError: (error) => {
+			options.onError?.(error);
+			settle();
+		}
+	});
+	await flush();
+	if (list.includes(event)) return;
+	await settled;
 }
-function sendBeacon(name, properties) {
+/**
+* The visitor id a beacon can carry. It is persisted, so a returning visitor already has one
+* before `getVisitor` has finished its round trip for this page. Requiring the in-memory copy
+* threw away exactly the events a beacon exists for: everything a visit accrues before its first
+* batch comes back, which for a short visit is the whole of it. A visitor the server has never
+* seen has none: the server would reject its events.
+*/
+function beaconVisitorId() {
 	const stored = config.storage.getItem(keys.visitor_id);
-	const visitor_id = cache.visitor?.id ?? (stored && stored !== "undefined" ? stored : void 0);
+	return cache.visitor?.id ?? (stored && stored !== "undefined" ? stored : void 0);
+}
+function beacon(dto) {
+	if (typeof navigator === "undefined" || !("sendBeacon" in navigator)) return false;
+	const blob = new Blob([JSON.stringify(dto)], { type: "text/plain;charset=UTF-8" });
+	return navigator.sendBeacon(`${config.endpoint}/events`, blob);
+}
+/**
+* Sends the queue by beacon, now: for when the page is hidden or left, the last moment its
+* script is sure to run — what PostHog's `requestQueue.unload()` and GA4 do on the same events.
+* Call it before the engagement beacon: a new session's `session_start` is in this queue.
+*
+* Nothing can be awaited here, so the events go with the tags they have settled on (the last
+* built ones otherwise), and without the server's ids: their third-party trackers are not fired,
+* as an id-less browser event could not be deduplicated against the server's. When no beacon can
+* take them — a visitor the server does not know yet, no `sendBeacon`, a refused body — they stay
+* queued for the usual send, which also creates the visitor.
+*/
+function sendPendingEvents() {
+	if (list.length === 0) return;
+	const visitor_id = beaconVisitorId();
+	const dto = list.map((event) => ({
+		name: event.name,
+		properties: event.properties,
+		tags: event.settled ?? cache.tags ?? {},
+		visitor_id: visitor_id ?? "",
+		session_id: event.session_id,
+		platform: config.platform,
+		environment: config.environment,
+		timestamp: event.timestamp
+	}));
+	if (!visitor_id || !beacon(dto)) {
+		flush();
+		return;
+	}
+	if (timer) {
+		clearTimeout(timer);
+		timer = null;
+	}
+	list.splice(0).forEach((event) => event.options.onSucceed?.(void 0));
+}
+function sendBeacon(name, properties) {
+	const visitor_id = beaconVisitorId();
 	if (!visitor_id) return;
-	const dto = [{
+	const session_id = getSession().extend();
+	if (!session_id) return;
+	if (beacon([{
 		name,
 		properties,
 		tags: cache.tags ?? {},
 		visitor_id,
-		session_id: getSession().extend(),
+		session_id,
 		platform: config.platform,
 		environment: config.environment,
 		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	}];
-	const blob = new Blob([JSON.stringify(dto)], { type: "application/json" });
-	if (navigator.sendBeacon(`${config.endpoint}/events`, blob)) return;
+	}])) return;
 	console.warn("Failed to send beacon", name, properties);
 }
 //#endregion
-export { sendBeacon, track, trackAsync };
+export { sendBeacon, sendPendingEvents, track, trackAsync };
 
 //# sourceMappingURL=index.mjs.map

package/dist/track/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/track/index.ts"],"sourcesContent":["import { TokenBucket, fetch } from '@shware/utils';\nimport { keys } from '../constants/storage';\nimport type { CreateTrackEventDTO } from '../schema/index';\nimport { cache, config } from '../setup/index';\nimport { getSession } from '../setup/session';\nimport { IGNORED_EVENTS } from '../third-parties/ignored-events';\nimport { getVisitor } from '../visitor/index';\nimport type { EventName, TrackEventResponse, TrackName, TrackProperties, TrackTags } from './types';\n\nexport interface TrackOptions {\n  enableThirdPartyTracking?: boolean;\n  onSucceed?: (response?: TrackEventResponse[number]) => void;\n  onError?: (error: unknown) => void;\n}\n\nconst defaultOptions: TrackOptions = {};\n\nlet tokenBucket: TokenBucket | undefined;\n\n/**\n * The rate limiter, built on the first send rather than at module scope: its\n * constructor starts a refill `setInterval`, and Cloudflare Workers refuse to\n * set a timer outside a request handler for the same reason they refuse to\n * generate random values there — see `setup/session.ts`.\n */\nfunction getTokenBucket() {\n  return (tokenBucket ??= new TokenBucket({ rate: 1, capacity: 20, requested: 2 }));\n}\n\ntype Item = {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  name: TrackName<any>;\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  properties: TrackProperties<any>;\n  tags: Promise<TrackTags>;\n  timestamp: string;\n  options: TrackOptions;\n};\n\n/**\n * Tags belong to the moment the event happened, not to the moment its batch goes out: a queued\n * event waits up to `delay` ms, and a single page app can navigate in that window, which would\n * stamp every pending event with the URL of the page the user has already left.\n *\n * The promise then sits in the queue with nothing awaiting it, so a failure has to be absorbed\n * here — an unhandled rejection would surface as a global error long before `sendEvents` could\n * catch it. Falling back to the last built tags keeps the event, minus whatever changed since.\n */\nasync function captureTags(): Promise<TrackTags> {\n  try {\n    return await config.getTags();\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    return cache.tags ?? {};\n  }\n}\n\n/**\n * The `session_start` a failed batch took down with it, kept for the next batch of the same\n * session. `fetch` has already retried the transient failures by the time a batch fails here;\n * what remains is a batch the server rejected outright — one invalid event fails the whole batch,\n * and `session_start` with it — or a network that stayed down past the retries. Neither is a\n * reason to lose the session's one attribution record, so it goes out again, with the tags and\n * timestamp of the moment the session actually began, under the same session id. Held in memory\n * only: a reload loses it, and with it the session_start — the same as before this existed.\n */\nlet pendingStart: { session_id: string; item: Item } | undefined;\n\nasync function sendEvents(events: Item[]) {\n  /** The announcement this batch carries, if any, so the catch below can hold it back. */\n  let announcement: { session_id: string; item: Item } | undefined;\n  try {\n    if (events.length === 0) return;\n\n    // One read-modify-write of the stored session for the whole batch: it answers which session\n    // these events belong to and whether this batch is the one that started it. Timed by the\n    // events themselves rather than by this moment — a tab frozen in the background can hold a\n    // batch for far longer than `delay`, and those events belong to the session they happened in.\n    const opening = events[0];\n    const { id: session_id, started } = getSession().touch(\n      Date.parse(opening.timestamp),\n      Date.parse(events[events.length - 1].timestamp)\n    );\n    if (started || pendingStart?.session_id === session_id) {\n      // `session_start` is derived from the event that opened the session, as GA4 derives it\n      // from the hit that did: when that event happened is when the session began, and the page\n      // it was captured on is where. Neither is read now — this batch goes out up to `delay` ms\n      // later, a batch held in a frozen tab far later still, and a landing page that redirects\n      // inside that window would stamp the session's one attribution record with the URL the utm\n      // parameters were already stripped from.\n      const start: Item =\n        pendingStart?.session_id === session_id\n          ? pendingStart.item\n          : {\n              name: 'session_start',\n              properties: {},\n              options: { enableThirdPartyTracking: false },\n              tags: opening.tags,\n              timestamp: opening.timestamp,\n            };\n      pendingStart = undefined;\n      announcement = { session_id, item: start };\n      events.unshift(start);\n    }\n\n    await getTokenBucket().removeTokens();\n\n    const visitor_id = (await getVisitor()).id;\n\n    const dto: CreateTrackEventDTO = await Promise.all(\n      events.map(async (event) => ({\n        name: event.name,\n        properties: event.properties,\n        tags: await event.tags,\n        visitor_id,\n        session_id,\n        platform: config.platform,\n        environment: config.environment,\n        timestamp: event.timestamp,\n      }))\n    );\n\n    const response = await fetch(`${config.endpoint}/events`, {\n      method: 'POST',\n      credentials: 'include',\n      // Survive the page being unloaded mid-flight: a batch waits up to `delay` ms, so closing\n      // the tab inside that window would otherwise abort the request and lose every event in it.\n      // The body stays far under keepalive's 64KB in-flight budget at 100 events per batch.\n      keepalive: true,\n      headers: await config.getHeaders(),\n      body: JSON.stringify(dto),\n    });\n\n    if (!response.ok) {\n      throw new Error(`Failed to send track event: ${response.status} ${await response.text()}`);\n    }\n\n    const data = (await response.json()) as TrackEventResponse;\n\n    let index = 0;\n    while (events.length > 0) {\n      const event = events.shift();\n      if (!event) {\n        index++;\n        continue;\n      }\n      const { options, name, properties } = event;\n      const eventId = data.at(index)?.id;\n      options.onSucceed?.(eventId ? { id: eventId } : undefined);\n      index++;\n      // An explicit false, not falsiness: a caller passing `{ onSucceed }` replaces the options\n      // object wholesale, and leaving the flag out must not silently switch forwarding off.\n      if (options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(name)) {\n        continue;\n      }\n      config.thirdPartyTrackers.forEach((tracker) => {\n        try {\n          tracker(name, properties, eventId);\n        } catch (e: unknown) {\n          // A third-party script does not get to take the rest of the batch with it. This loop is\n          // still draining `events` with `shift`, so a throw would escape to the catch below and\n          // report failure to whatever is left in the queue — for events the server has already\n          // accepted, and after the ones ahead of them were told they succeeded.\n          if (e instanceof Error) console.log(e.message);\n        }\n      });\n    }\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    // The other events are reported lost and stay lost; `session_start` alone is worth carrying\n    // over, because it is the session's only attribution record — a session without one has no\n    // channel, and its every later event drops out of an attribution join.\n    if (announcement) pendingStart = announcement;\n    events.forEach((event) => event.options.onError?.(e));\n  }\n}\n\nconst batch = 10;\nconst delay = 2000;\nconst list: Item[] = [];\nlet timer: ReturnType<typeof setTimeout> | null = null;\n\n/**\n * Both paths into a send go through here, so a batch that fills up cancels the timer the\n * previous push armed rather than leaving it to wake up on its own with nothing to send.\n */\nfunction flush() {\n  if (timer) {\n    clearTimeout(timer);\n    timer = null;\n  }\n  if (list.length === 0) return;\n  const copy = [...list];\n  list.length = 0;\n  void sendEvents(copy);\n}\n\nexport function track<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  list.push({\n    name,\n    properties,\n    options,\n    tags: captureTags(),\n    timestamp: new Date().toISOString(),\n  });\n  if (list.length >= batch) {\n    flush();\n    return;\n  }\n  if (timer) clearTimeout(timer);\n  timer = setTimeout(flush, delay);\n}\n\nexport async function trackAsync<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  await sendEvents([\n    { name, properties, options, tags: captureTags(), timestamp: new Date().toISOString() },\n  ]);\n}\n\nexport function sendBeacon<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>\n) {\n  // The visitor id is persisted, so a returning visitor already has one before `getVisitor` has\n  // finished its round trip for this page. Requiring the in-memory copy threw away exactly the\n  // events this function exists for: everything a visit accrues before its first batch comes\n  // back, which for a short visit is the whole of it.\n  const stored = config.storage.getItem(keys.visitor_id);\n  const visitor_id = cache.visitor?.id ?? (stored && stored !== 'undefined' ? stored : undefined);\n  if (!visitor_id) return;\n\n  const dto: CreateTrackEventDTO = [\n    {\n      name,\n      properties,\n      // Tags are worth less than the event carrying them: an empty set still reports the\n      // engagement, and every field in `tagsSchema` is optional.\n      tags: cache.tags ?? {},\n      visitor_id,\n      session_id: getSession().extend(),\n      platform: config.platform,\n      environment: config.environment,\n      timestamp: new Date().toISOString(),\n    },\n  ];\n  const blob = new Blob([JSON.stringify(dto)], { type: 'application/json' });\n  const success = navigator.sendBeacon(`${config.endpoint}/events`, blob);\n  if (success) return;\n  console.warn('Failed to send beacon', name, properties);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/track/index.ts"],"sourcesContent":["import { TokenBucket, fetch } from '@shware/utils';\nimport { keys } from '../constants/storage';\nimport type { CreateTrackEventDTO } from '../schema/index';\nimport { cache, config } from '../setup/index';\nimport { getSession } from '../setup/session';\nimport { IGNORED_EVENTS } from '../third-parties/ignored-events';\nimport { getVisitor } from '../visitor/index';\nimport type { EventName, TrackEventResponse, TrackName, TrackProperties, TrackTags } from './types';\n\nexport interface TrackOptions {\n  enableThirdPartyTracking?: boolean;\n  onSucceed?: (response?: TrackEventResponse[number]) => void;\n  onError?: (error: unknown) => void;\n}\n\nconst defaultOptions: TrackOptions = {};\n\nlet tokenBucket: TokenBucket | undefined;\n\n/**\n * The rate limiter, built on the first send rather than at module scope: its\n * constructor starts a refill `setInterval`, and Cloudflare Workers refuse to\n * set a timer outside a request handler for the same reason they refuse to\n * generate random values there — see `setup/session.ts`.\n */\nfunction getTokenBucket() {\n  return (tokenBucket ??= new TokenBucket({ rate: 1, capacity: 20, requested: 2 }));\n}\n\ntype Item = {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  name: TrackName<any>;\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  properties: TrackProperties<any>;\n  tags: Promise<TrackTags>;\n  /** `tags` once settled: a page being hidden can await nothing, and sends what it has. */\n  settled?: TrackTags;\n  /** Decided when the event happens, as GA4 and PostHog decide it, never when it is sent. */\n  session_id: string;\n  timestamp: string;\n  options: TrackOptions;\n};\n\n/**\n * Tags belong to the moment the event happened, not to the moment its batch goes out: a queued\n * event waits up to `delay` ms, and a single page app can navigate in that window, which would\n * stamp every pending event with the URL of the page the user has already left.\n *\n * The promise then sits in the queue with nothing awaiting it, so a failure has to be absorbed\n * here — an unhandled rejection would surface as a global error long before `sendEvents` could\n * catch it. Falling back to the last built tags keeps the event, minus whatever changed since.\n */\nasync function captureTags(): Promise<TrackTags> {\n  try {\n    return await config.getTags();\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    return cache.tags ?? {};\n  }\n}\n\n/**\n * The events not yet sent, and the only place they are: a batch leaves it at the moment it is\n * handed to `fetch` or to a beacon, never earlier. So when the page is hidden or left,\n * everything still unsent is right here for `sendPendingEvents`.\n */\nconst list: Item[] = [];\nconst batchSize = 10;\nconst delay = 2000;\nlet timer: ReturnType<typeof setTimeout> | null = null;\n\n/**\n * Queues an event, preceded by a `session_start` when it is the one that opens a session.\n *\n * The session is decided here, when the event happens, as GA4 and PostHog decide it: the\n * `session_start` then sits in the queue right before the event that opened the session, so\n * wherever that event goes — a batch, a beacon, a retry — its announcement has gone ahead of it.\n * It carries that event's tags and time, as GA4 derives it from the hit that started the\n * session: the landing page is where the session began, whatever the page has navigated to by\n * the time the batch goes out.\n */\nfunction enqueue(name: Item['name'], properties: Item['properties'], options: TrackOptions): Item {\n  const timestamp = new Date().toISOString();\n  const tags = captureTags();\n  const { id: session_id, started } = getSession().touch(Date.parse(timestamp));\n  const item = (fields: Pick<Item, 'name' | 'properties' | 'options'>): Item => {\n    const result: Item = { ...fields, tags, timestamp, session_id };\n    void tags.then((settled) => (result.settled = settled));\n    return result;\n  };\n  if (started) {\n    const options = { enableThirdPartyTracking: false };\n    list.push(item({ name: 'session_start', properties: {}, options }));\n  }\n  const event = item({ name, properties, options });\n  list.push(event);\n  return event;\n}\n\n/**\n * Sends the queue. Everything that has to be awaited is awaited first, and only then are the\n * events taken off the queue and handed to `fetch` in the same synchronous step — so there is\n * no moment at which an event is neither queued nor sent.\n */\nasync function flush() {\n  if (timer) {\n    clearTimeout(timer);\n    timer = null;\n  }\n  if (list.length === 0) return;\n\n  let events: Item[] = [];\n  try {\n    await getTokenBucket().removeTokens();\n    const visitor_id = (await getVisitor()).id;\n    const headers = await config.getHeaders();\n    // Settled before the events leave the queue; those queued meanwhile are a microtask away.\n    await Promise.all(list.map((event) => event.tags));\n\n    events = list.splice(0);\n    if (events.length === 0) return;\n    const dto: CreateTrackEventDTO = await Promise.all(\n      events.map(async (event) => ({\n        name: event.name,\n        properties: event.properties,\n        tags: await event.tags,\n        visitor_id,\n        session_id: event.session_id,\n        platform: config.platform,\n        environment: config.environment,\n        timestamp: event.timestamp,\n      }))\n    );\n\n    const body = JSON.stringify(dto);\n    const response = await fetch(`${config.endpoint}/events`, {\n      method: 'POST',\n      credentials: 'include',\n      // keepalive lets the request survive the page being unloaded mid-flight, within a 64KB\n      // budget shared by every such request of the page; a body that could not fit goes as a\n      // plain POST rather than failing outright.\n      keepalive: body.length < 60_000,\n      headers,\n      body,\n    });\n\n    if (!response.ok) {\n      throw new Error(`Failed to send track event: ${response.status} ${await response.text()}`);\n    }\n\n    const data = (await response.json()) as TrackEventResponse;\n\n    events.forEach((event, index) => {\n      const eventId = data.at(index)?.id;\n      event.options.onSucceed?.(eventId ? { id: eventId } : undefined);\n      // An explicit false, not falsiness: a caller passing `{ onSucceed }` replaces the options\n      // object wholesale, and leaving the flag out must not silently switch forwarding off.\n      if (event.options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(event.name)) {\n        return;\n      }\n      config.thirdPartyTrackers.forEach((tracker) => {\n        try {\n          tracker(event.name, event.properties, eventId);\n        } catch (e: unknown) {\n          // A third-party script does not get to take the rest of the batch with it.\n          if (e instanceof Error) console.log(e.message);\n        }\n      });\n    });\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    // `fetch` has already retried the transient failures by the time a batch fails here; what\n    // remains is a batch the server rejected outright — one invalid event fails the whole batch\n    // — or a network that stayed down past the retries. The other events are reported lost;\n    // `session_start` alone goes back on the queue for the next send, because it is the\n    // session's only attribution record: a session without one has no channel, and its every\n    // later event drops out of an attribution join.\n    const starts = events.filter((event) => event.name === 'session_start');\n    list.unshift(...starts);\n    events\n      .filter((event) => event.name !== 'session_start')\n      .forEach((event) => event.options.onError?.(e));\n  }\n}\n\nexport function track<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  enqueue(name, properties, options);\n  if (list.length >= batchSize) {\n    void flush();\n    return;\n  }\n  if (timer) clearTimeout(timer);\n  timer = setTimeout(() => void flush(), delay);\n}\n\n/**\n * Sends the event now, with whatever is queued, and resolves once it has been sent or lost — or,\n * when no visitor could be created to send it with, at once, the event left queued for the next\n * send. It never rejects: tracking must not fail the step that awaits it.\n */\nexport async function trackAsync<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  let settle!: () => void;\n  const settled = new Promise<void>((resolve) => {\n    settle = resolve;\n  });\n  const event = enqueue(name, properties, {\n    ...options,\n    onSucceed: (response) => {\n      options.onSucceed?.(response);\n      settle();\n    },\n    onError: (error) => {\n      options.onError?.(error);\n      settle();\n    },\n  });\n  await flush();\n  // Still queued: this send could not take it — no visitor id to send it with yet. It waits for\n  // the next send, but the caller, who may be holding a navigation on this, does not.\n  if (list.includes(event)) return;\n  await settled;\n}\n\n/**\n * The visitor id a beacon can carry. It is persisted, so a returning visitor already has one\n * before `getVisitor` has finished its round trip for this page. Requiring the in-memory copy\n * threw away exactly the events a beacon exists for: everything a visit accrues before its first\n * batch comes back, which for a short visit is the whole of it. A visitor the server has never\n * seen has none: the server would reject its events.\n */\nfunction beaconVisitorId(): string | undefined {\n  const stored = config.storage.getItem(keys.visitor_id);\n  return cache.visitor?.id ?? (stored && stored !== 'undefined' ? stored : undefined);\n}\n\nfunction beacon(dto: CreateTrackEventDTO): boolean {\n  // Not every runtime with a `navigator` has it: React Native has neither beacons nor pages.\n  if (typeof navigator === 'undefined' || !('sendBeacon' in navigator)) return false;\n  // text/plain keeps a cross-origin beacon a CORS simple request: as application/json it needs a\n  // preflight, which a page being closed often cannot complete, and the beacon is then dropped.\n  // The server reads it as JSON (`zBeaconJson` in @shware/http).\n  const blob = new Blob([JSON.stringify(dto)], { type: 'text/plain;charset=UTF-8' });\n  return navigator.sendBeacon(`${config.endpoint}/events`, blob);\n}\n\n/**\n * Sends the queue by beacon, now: for when the page is hidden or left, the last moment its\n * script is sure to run — what PostHog's `requestQueue.unload()` and GA4 do on the same events.\n * Call it before the engagement beacon: a new session's `session_start` is in this queue.\n *\n * Nothing can be awaited here, so the events go with the tags they have settled on (the last\n * built ones otherwise), and without the server's ids: their third-party trackers are not fired,\n * as an id-less browser event could not be deduplicated against the server's. When no beacon can\n * take them — a visitor the server does not know yet, no `sendBeacon`, a refused body — they stay\n * queued for the usual send, which also creates the visitor.\n */\nexport function sendPendingEvents() {\n  if (list.length === 0) return;\n  const visitor_id = beaconVisitorId();\n  const dto: CreateTrackEventDTO = list.map((event) => ({\n    name: event.name,\n    properties: event.properties,\n    tags: event.settled ?? cache.tags ?? {},\n    visitor_id: visitor_id ?? '',\n    session_id: event.session_id,\n    platform: config.platform,\n    environment: config.environment,\n    timestamp: event.timestamp,\n  }));\n  if (!visitor_id || !beacon(dto)) {\n    void flush();\n    return;\n  }\n  if (timer) {\n    clearTimeout(timer);\n    timer = null;\n  }\n  list.splice(0).forEach((event) => event.options.onSucceed?.(undefined));\n}\n\nexport function sendBeacon<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>\n) {\n  const visitor_id = beaconVisitorId();\n  if (!visitor_id) return;\n  // No stored session means no event was ever queued from this storage, so there is no session\n  // to report for — and one started here could never be announced. See `Session.extend`.\n  const session_id = getSession().extend();\n  if (!session_id) return;\n\n  const dto: CreateTrackEventDTO = [\n    {\n      name,\n      properties,\n      // Tags are worth less than the event carrying them: an empty set still reports the\n      // engagement, and every field in `tagsSchema` is optional.\n      tags: cache.tags ?? {},\n      visitor_id,\n      session_id,\n      platform: config.platform,\n      environment: config.environment,\n      timestamp: new Date().toISOString(),\n    },\n  ];\n  if (beacon(dto)) return;\n  console.warn('Failed to send beacon', name, properties);\n}\n"],"mappings":"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"}

package/dist/track/types.d.cts

@@ -124,15 +124,18 @@ export interface PageInfo {
    */
   source_url?: string;
 }
+/**
+ * Ad click ids and the ad platforms' first-party cookies, each under the name of where it was
+ * read: a URL parameter keeps the parameter's own name (`fbclid`, `gclid`, `ScCid` — jsonb keys
+ * are case-sensitive, so in SQL that is `tags->>'ScCid'`), a cookie keeps the cookie's name and
+ * so starts with an underscore (`_fbc`, `_gcl_aw`, `__oppref`). One source per key, never a
+ * fallback from one to the other, so a value always says where it came from.
+ *
+ * The URL parameters are this page's click and name the visit's channel (`CLICK_ID_CHANNELS`);
+ * the cookies outlive the click and only ever feed the conversion senders, which take the URL
+ * parameter first and the cookie when the page carries none (`server/click-ids`).
+ */
 export interface AdvertisingInfo {
-  /**
-   * Meta pixel fields
-   * ref: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters#fbc
-   * Stored in the _fbc/_fbp browser cookie under your domain
-   * ref: https://www.facebook.com/business/help/2360940870872492?checkpoint_src=any
-   */
-  fbc?: string;
-  fbp?: string;
   fbclid?: string;
   ad_id?: string;
   ad_name?: string;
@@ -141,26 +144,55 @@ export interface AdvertisingInfo {
   campaign_id?: string;
   campaign_name?: string;
   placement?: string;
-  /** Google Analytics fields */
+  /**
+   * Meta click id cookie, `fb.<subdomainIndex>.<creationTime>.<fbclid>`, set server-side by
+   * `resolveClickIdCookies`.
+   * ref: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+   */
+  _fbc?: string;
+  /** Meta browser id cookie, `fb.<subdomainIndex>.<creationTime>.<random>`, set by the pixel. */
+  _fbp?: string;
+  /** @deprecated Renamed to `_fbc` in 9.0.0; still read from clients on an older version. */
+  fbc?: string;
+  /** @deprecated Renamed to `_fbp` in 9.0.0; still read from clients on an older version. */
+  fbp?: string;
   gclid?: string;
   gclsrc?: string;
   gad_source?: string;
   gad_campaignid?: string;
-  /** Reddit Ads fields */
+  wbraid?: string;
+  gbraid?: string;
+  dclid?: string;
+  /** gtag's click cookie, `GCL.<seconds>.<gclid>`; see `parseGcl`. */
+  _gcl_aw?: string;
+  /** gtag's web-to-app click cookie, `GCL.<seconds>.<wbraid>`; see `parseGcl`. */
+  _gcl_gb?: string;
+  msclkid?: string;
+  /** The UET tag's click cookie, `_uet<msclkid>`; see `parseUetMsclkid`. */
+  _uetmsclkid?: string;
   rdt_cid?: string;
+  /** Reddit click id cookie, set server-side by `resolveClickIdCookies`. */
+  _rdt_cid?: string;
+  /** The Reddit pixel's browser id cookie, `<timestamp>.<uuid>`. */
+  _rdt_uuid?: string;
+  /** @deprecated Renamed to `_rdt_uuid` in 9.0.0; still read from clients on an older version. */
   rdt_uuid?: string;
-  /** LinkedIn Ads fields: get click id from url params or first-party cookie */
   li_fat_id?: string;
-  dclid?: string;
+  /**
+   * The Insight Tag's click cookie. The cookie itself is named `li_fat_id`, like the URL
+   * parameter; the underscore is ours, to keep the two apart.
+   */
+  _li_fat_id?: string;
+  oppref?: string;
+  /** The pixel's copy of the last `oppref`, kept 30 days. */
+  __oppref?: string;
+  /** The pixel's browser reference, a random id kept 365 days. */
+  __obref?: string;
   ko_click_id?: string;
-  msclkid?: string;
   ScCid?: string;
   ttclid?: string;
   twclid?: string;
-  wbraid?: string;
-  gbraid?: string;
   yclid?: string;
-  oppref?: string;
   epik?: string;
 }
 /**

package/dist/track/types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.cts","names":["GAUserProvidedData"],"sources":["../../src/track/types.ts"],"mappings":";;YAEY;YACA,YAAY;YAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;YAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;YAEpB;YACA;iBAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe,yBAAyBA;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;YAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;iBAGe;;EAEf;EACA;;iBAGe;EACf;EACA;EACA;;;;;;;;;;iBAWe;EACf;EACA;EACA;;;;;;;EAOA;;;;;;EAMA;;iBAGe;;;;;;;EAOf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;EAEA;EACA;EACA;EAGA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;iBAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;iBAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;YAGU;;EAEV"}
+{"version":3,"file":"types.d.cts","names":["GAUserProvidedData"],"sources":["../../src/track/types.ts"],"mappings":";;YAEY;YACA,YAAY;YAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;YAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;YAEpB;YACA;iBAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe,yBAAyBA;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;YAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;iBAGe;;EAEf;EACA;;iBAGe;EACf;EACA;EACA;;;;;;;;;;iBAWe;EACf;EACA;EACA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;;iBAce;EAEf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;EAMA;;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;EAEA;;EAEA;EAEA;;EAEA;;EAEA;;EAEA;EAEA;;;;;EAKA;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;iBAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;iBAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;YAGU;;EAEV"}

package/dist/track/types.d.mts

@@ -124,15 +124,18 @@ export interface PageInfo {
    */
   source_url?: string;
 }
+/**
+ * Ad click ids and the ad platforms' first-party cookies, each under the name of where it was
+ * read: a URL parameter keeps the parameter's own name (`fbclid`, `gclid`, `ScCid` — jsonb keys
+ * are case-sensitive, so in SQL that is `tags->>'ScCid'`), a cookie keeps the cookie's name and
+ * so starts with an underscore (`_fbc`, `_gcl_aw`, `__oppref`). One source per key, never a
+ * fallback from one to the other, so a value always says where it came from.
+ *
+ * The URL parameters are this page's click and name the visit's channel (`CLICK_ID_CHANNELS`);
+ * the cookies outlive the click and only ever feed the conversion senders, which take the URL
+ * parameter first and the cookie when the page carries none (`server/click-ids`).
+ */
 export interface AdvertisingInfo {
-  /**
-   * Meta pixel fields
-   * ref: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters#fbc
-   * Stored in the _fbc/_fbp browser cookie under your domain
-   * ref: https://www.facebook.com/business/help/2360940870872492?checkpoint_src=any
-   */
-  fbc?: string;
-  fbp?: string;
   fbclid?: string;
   ad_id?: string;
   ad_name?: string;
@@ -141,26 +144,55 @@ export interface AdvertisingInfo {
   campaign_id?: string;
   campaign_name?: string;
   placement?: string;
-  /** Google Analytics fields */
+  /**
+   * Meta click id cookie, `fb.<subdomainIndex>.<creationTime>.<fbclid>`, set server-side by
+   * `resolveClickIdCookies`.
+   * ref: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+   */
+  _fbc?: string;
+  /** Meta browser id cookie, `fb.<subdomainIndex>.<creationTime>.<random>`, set by the pixel. */
+  _fbp?: string;
+  /** @deprecated Renamed to `_fbc` in 9.0.0; still read from clients on an older version. */
+  fbc?: string;
+  /** @deprecated Renamed to `_fbp` in 9.0.0; still read from clients on an older version. */
+  fbp?: string;
   gclid?: string;
   gclsrc?: string;
   gad_source?: string;
   gad_campaignid?: string;
-  /** Reddit Ads fields */
+  wbraid?: string;
+  gbraid?: string;
+  dclid?: string;
+  /** gtag's click cookie, `GCL.<seconds>.<gclid>`; see `parseGcl`. */
+  _gcl_aw?: string;
+  /** gtag's web-to-app click cookie, `GCL.<seconds>.<wbraid>`; see `parseGcl`. */
+  _gcl_gb?: string;
+  msclkid?: string;
+  /** The UET tag's click cookie, `_uet<msclkid>`; see `parseUetMsclkid`. */
+  _uetmsclkid?: string;
   rdt_cid?: string;
+  /** Reddit click id cookie, set server-side by `resolveClickIdCookies`. */
+  _rdt_cid?: string;
+  /** The Reddit pixel's browser id cookie, `<timestamp>.<uuid>`. */
+  _rdt_uuid?: string;
+  /** @deprecated Renamed to `_rdt_uuid` in 9.0.0; still read from clients on an older version. */
   rdt_uuid?: string;
-  /** LinkedIn Ads fields: get click id from url params or first-party cookie */
   li_fat_id?: string;
-  dclid?: string;
+  /**
+   * The Insight Tag's click cookie. The cookie itself is named `li_fat_id`, like the URL
+   * parameter; the underscore is ours, to keep the two apart.
+   */
+  _li_fat_id?: string;
+  oppref?: string;
+  /** The pixel's copy of the last `oppref`, kept 30 days. */
+  __oppref?: string;
+  /** The pixel's browser reference, a random id kept 365 days. */
+  __obref?: string;
   ko_click_id?: string;
-  msclkid?: string;
   ScCid?: string;
   ttclid?: string;
   twclid?: string;
-  wbraid?: string;
-  gbraid?: string;
   yclid?: string;
-  oppref?: string;
   epik?: string;
 }
 /**

package/dist/track/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":["GAUserProvidedData"],"sources":["../../src/track/types.ts"],"mappings":";;YAEY;YACA,YAAY;YAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;YAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;YAEpB;YACA;iBAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe,yBAAyBA;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;YAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;iBAGe;;EAEf;EACA;;iBAGe;EACf;EACA;EACA;;;;;;;;;;iBAWe;EACf;EACA;EACA;;;;;;;EAOA;;;;;;EAMA;;iBAGe;;;;;;;EAOf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;EAEA;EACA;EACA;EAGA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;iBAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;iBAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;YAGU;;EAEV"}
+{"version":3,"file":"types.d.mts","names":["GAUserProvidedData"],"sources":["../../src/track/types.ts"],"mappings":";;YAEY;YACA,YAAY;YAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;YAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;YAEpB;YACA;iBAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe,yBAAyBA;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;YAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;iBAGe;;EAEf;EACA;;iBAGe;EACf;EACA;EACA;;;;;;;;;;iBAWe;EACf;EACA;EACA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;;iBAce;EAEf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;EAMA;;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;EAEA;;EAEA;EAEA;;EAEA;;EAEA;;EAEA;EAEA;;;;;EAKA;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;iBAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;iBAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;YAGU;;EAEV"}