tracklane 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# tracklane
+
+> TODO: one-line description of the library.
+
+ESM-only TypeScript library. Documentation: https://brunobertolini.github.io/tracklane
+
+## Install
+
+```bash
+pnpm add tracklane
+```
+
+## Usage
+
+```ts
+import { format } from 'tracklane';
+
+format('  hello  ', { prefix: '> ' }); // '> hello'
+```
+
+## License
+
+MIT © Bruno Bertolini

package/dist/browser-BQNJ4qUq.d.ts

@@ -0,0 +1,124 @@
+import { c as UserData, i as EventData, n as ConsentState, o as ProviderDefault, r as EventBinding, s as TrackingError } from "./vocabulary-ByyXHVWd.js";
+//#region src/providers/ga4.browser.d.ts
+/** Optional configuration for the GA4 browser provider. */
+interface Ga4BrowserConfig {
+  /**
+   * How this property spells each canonical event. Rarely needed: the
+   * canonical vocabulary already is GA4's.
+   */
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * Google Analytics 4 in the browser, through `gtag.js`.
+ *
+ * **This provider does not load Google's tag.** The tag belongs on the page,
+ * installed the way Google documents it — a snippet in the HTML, or a tag
+ * manager. This library talks to the tag that is already there; it never
+ * injects a third-party script into your page, and it never issues the
+ * property configuration that would emit a second page view.
+ *
+ * Which also means the initial consent declaration is not ours to make:
+ * Google requires it before the property is configured, and the snippet that
+ * configures the property is yours. Use {@link ConsentState} through
+ * `consent()` for changes after that.
+ *
+ * @param measurementId - The `G-` id of the data stream, matching the tag on
+ * the page.
+ * @param config - Rarely needed event name overrides.
+ * @returns A provider for `createTracking` from `tracklane/browser`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/browser';
+ *
+ * // Google's own snippet is already in the page.
+ * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+ *
+ * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+ * ```
+ */
+declare function ga4(measurementId: string, config?: Ga4BrowserConfig): BrowserProvider;
+//#endregion
+//#region src/browser.d.ts
+/**
+ * Everything the browser needs beyond the event itself.
+ *
+ * There is one field, and that is the point: in the browser each vendor tag
+ * reads its own cookies and holds its own session, so the only thing left
+ * for the host to supply is the value that ties this hit to a server-side
+ * one.
+ */
+interface TrackOptions {
+  /**
+   * The value that lets a vendor recognise this hit and a server-side hit as
+   * one event. The library never invents it — the browser and the server do
+   * not share a process, so only a value the host already owns (an order id)
+   * can match on both sides.
+   */
+  dedupId?: string;
+}
+/**
+ * A destination for browser events.
+ *
+ * This is the whole contract, and it is what a provider written outside this
+ * package implements — the ones shipped here get no shortcut.
+ */
+interface BrowserProvider<Target = string> {
+  /** The vendor's fixed name. Registering one twice is an error. */
+  name: string;
+  /** What happens to a canonical event this vendor has no binding for. */
+  default: ProviderDefault;
+  /** How this vendor spells each canonical event. */
+  events?: Record<string, EventBinding<Target>>;
+  /** Loads the vendor tag. Runs once, at creation. */
+  install?(): void | Promise<void>;
+  track(name: Target, data: EventData, options: TrackOptions): void;
+  /** Absent where the vendor keeps no user of its own. */
+  identify?(user: UserData, traits?: Record<string, unknown>): void;
+  /** Absent where the vendor documents no consent command. */
+  consent?(command: "default" | "update", state: ConsentState): void;
+}
+/** Options accepted by {@link createTracking}. */
+interface BrowserTrackingOptions {
+  providers: readonly BrowserProvider[];
+  /**
+   * The one diagnostic channel. Without it the library is silent, exactly as
+   * a hand-written vendor call is.
+   */
+  onError?: (error: TrackingError) => void;
+}
+/** What {@link createTracking} returns. */
+interface BrowserTracking {
+  /** Sends one event to every configured vendor. Never throws. */
+  track(name: string, data?: EventData, options?: TrackOptions): void;
+  /** Forwards the user to the vendors that hold one, and to nobody else. */
+  identify(user: UserData, traits?: Record<string, unknown>): void;
+  /**
+   * Forwards a consent declaration to every vendor that documents a command
+   * for it. It never decides, stores or withholds anything.
+   */
+  consent(command: "default" | "update", state: ConsentState): void;
+}
+/**
+ * Creates the browser tracking surface.
+ *
+ * Providers install eagerly, which is what pasting a vendor snippet does and
+ * what lets each vendor record its own initial page view. Every vendor
+ * shipped here queues its own commands until its script lands, so nothing is
+ * lost to loading and this library needs no queue of its own.
+ *
+ * @param options - The providers to send to, and an optional error channel.
+ * @returns The `track`, `identify` and `consent` calls.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/browser';
+ *
+ * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+ * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+ * ```
+ */
+declare function createTracking(options: BrowserTrackingOptions): BrowserTracking;
+//#endregion
+export { createTracking as a, TrackOptions as i, BrowserTracking as n, Ga4BrowserConfig as o, BrowserTrackingOptions as r, ga4 as s, BrowserProvider as t };
+//# sourceMappingURL=browser-BQNJ4qUq.d.ts.map

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+import { a as createTracking, i as TrackOptions, n as BrowserTracking, o as Ga4BrowserConfig, r as BrowserTrackingOptions, s as ga4, t as BrowserProvider } from "./browser-BQNJ4qUq.js";
+export { BrowserProvider, BrowserTracking, BrowserTrackingOptions, type Ga4BrowserConfig, TrackOptions, createTracking, ga4 };

package/dist/browser.js

@@ -0,0 +1,141 @@
+import { i as resolveEvent, n as makeReporter, r as messageOf, t as assertUniqueProviders } from "./dispatch-DK2GBnkt.js";
+//#region src/providers/ga4.browser.ts
+function gtagWindow() {
+	return typeof window === "undefined" ? void 0 : window;
+}
+/**
+* Sends a command, or fails the way a hand-written call would.
+*
+* Writing `gtag(…)` on a page without Google's snippet throws, and this
+* library replicates that rather than swallowing it: a silent no-op is how a
+* host ends up believing it is measuring something.
+*/
+function push(...args) {
+	const gtag = gtagWindow()?.gtag;
+	if (!gtag) throw new Error("ga4: window.gtag is not defined — add Google's tag to the page before creating tracking");
+	gtag(...args);
+}
+/**
+* Google Analytics 4 in the browser, through `gtag.js`.
+*
+* **This provider does not load Google's tag.** The tag belongs on the page,
+* installed the way Google documents it — a snippet in the HTML, or a tag
+* manager. This library talks to the tag that is already there; it never
+* injects a third-party script into your page, and it never issues the
+* property configuration that would emit a second page view.
+*
+* Which also means the initial consent declaration is not ours to make:
+* Google requires it before the property is configured, and the snippet that
+* configures the property is yours. Use {@link ConsentState} through
+* `consent()` for changes after that.
+*
+* @param measurementId - The `G-` id of the data stream, matching the tag on
+* the page.
+* @param config - Rarely needed event name overrides.
+* @returns A provider for `createTracking` from `tracklane/browser`.
+*
+* @example
+* ```ts
+* import { createTracking, ga4 } from 'tracklane/browser';
+*
+* // Google's own snippet is already in the page.
+* const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+*
+* track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+* ```
+*/
+function ga4(measurementId, config = {}) {
+	const { events } = config;
+	return {
+		name: "ga4",
+		default: "passthrough",
+		...events ? { events } : {},
+		track(name, data, _options) {
+			push("event", name, {
+				...data,
+				send_to: measurementId
+			});
+		},
+		identify(user, traits) {
+			if (user.userId !== void 0) push("set", { user_id: user.userId });
+			if (traits) push("set", "user_properties", traits);
+		},
+		consent(command, state) {
+			push("consent", command, state);
+		}
+	};
+}
+//#endregion
+//#region src/browser.ts
+/**
+* Creates the browser tracking surface.
+*
+* Providers install eagerly, which is what pasting a vendor snippet does and
+* what lets each vendor record its own initial page view. Every vendor
+* shipped here queues its own commands until its script lands, so nothing is
+* lost to loading and this library needs no queue of its own.
+*
+* @param options - The providers to send to, and an optional error channel.
+* @returns The `track`, `identify` and `consent` calls.
+*
+* @example
+* ```ts
+* import { createTracking, ga4 } from 'tracklane/browser';
+*
+* const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+* track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+* ```
+*/
+function createTracking(options) {
+	const { providers } = options;
+	assertUniqueProviders(providers);
+	const report = makeReporter(options.onError);
+	const fail = (provider, event, cause) => {
+		report({
+			provider,
+			event,
+			severity: "error",
+			message: messageOf(cause),
+			cause
+		});
+	};
+	for (const provider of providers) try {
+		const installing = provider.install?.();
+		Promise.resolve(installing).catch((cause) => {
+			fail(provider.name, "install", cause);
+		});
+	} catch (cause) {
+		fail(provider.name, "install", cause);
+	}
+	return {
+		track(name, data = {}, trackOptions = {}) {
+			for (const provider of providers) {
+				const target = resolveEvent(provider, name);
+				if (target === void 0) continue;
+				try {
+					provider.track(target, data, trackOptions);
+				} catch (cause) {
+					fail(provider.name, name, cause);
+				}
+			}
+		},
+		identify(user, traits) {
+			for (const provider of providers) try {
+				provider.identify?.(user, traits);
+			} catch (cause) {
+				fail(provider.name, "identify", cause);
+			}
+		},
+		consent(command, state) {
+			for (const provider of providers) try {
+				provider.consent?.(command, state);
+			} catch (cause) {
+				fail(provider.name, "consent", cause);
+			}
+		}
+	};
+}
+//#endregion
+export { createTracking, ga4 };
+
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","names":[],"sources":["../src/providers/ga4.browser.ts","../src/browser.ts"],"sourcesContent":["import type { BrowserProvider, TrackOptions } from '../browser.js';\nimport type { ConsentState, EventBinding, EventData, UserData } from '../vocabulary.js';\n\ninterface GtagWindow {\n  gtag?: (...args: unknown[]) => void;\n}\n\n/** Optional configuration for the GA4 browser provider. */\nexport interface Ga4BrowserConfig {\n  /**\n   * How this property spells each canonical event. Rarely needed: the\n   * canonical vocabulary already is GA4's.\n   */\n  events?: Record<string, EventBinding<string>>;\n}\n\n// Server rendering reaches this module with no browser at all, where\n// `window` is a ReferenceError rather than `undefined`.\nfunction gtagWindow(): GtagWindow | undefined {\n  return typeof window === 'undefined' ? undefined : (window as unknown as GtagWindow);\n}\n\n/**\n * Sends a command, or fails the way a hand-written call would.\n *\n * Writing `gtag(…)` on a page without Google's snippet throws, and this\n * library replicates that rather than swallowing it: a silent no-op is how a\n * host ends up believing it is measuring something.\n */\nfunction push(...args: unknown[]): void {\n  const gtag = gtagWindow()?.gtag;\n\n  if (!gtag) {\n    throw new Error(\n      \"ga4: window.gtag is not defined — add Google's tag to the page before creating tracking\",\n    );\n  }\n\n  gtag(...args);\n}\n\n/**\n * Google Analytics 4 in the browser, through `gtag.js`.\n *\n * **This provider does not load Google's tag.** The tag belongs on the page,\n * installed the way Google documents it — a snippet in the HTML, or a tag\n * manager. This library talks to the tag that is already there; it never\n * injects a third-party script into your page, and it never issues the\n * property configuration that would emit a second page view.\n *\n * Which also means the initial consent declaration is not ours to make:\n * Google requires it before the property is configured, and the snippet that\n * configures the property is yours. Use {@link ConsentState} through\n * `consent()` for changes after that.\n *\n * @param measurementId - The `G-` id of the data stream, matching the tag on\n * the page.\n * @param config - Rarely needed event name overrides.\n * @returns A provider for `createTracking` from `tracklane/browser`.\n *\n * @example\n * ```ts\n * import { createTracking, ga4 } from 'tracklane/browser';\n *\n * // Google's own snippet is already in the page.\n * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });\n *\n * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });\n * ```\n */\nexport function ga4(measurementId: string, config: Ga4BrowserConfig = {}): BrowserProvider {\n  const { events } = config;\n\n  return {\n    name: 'ga4',\n    // The canonical names already are GA4's, so every event passes through\n    // under its own name unless the host says otherwise.\n    default: 'passthrough',\n    ...(events ? { events } : {}),\n\n    track(name: string, data: EventData, _options: TrackOptions): void {\n      // GA4 documents no browser-to-server deduplication, so `dedupId` maps\n      // to nothing here. That is the exact translation of \"this concept does\n      // not exist in this vendor\" — inventing a param would imply a merge\n      // the platform never performs.\n      //\n      // `send_to` is written after the host's data on purpose: without it,\n      // gtag sends to every configured property on the page, so the\n      // addressing is the adapter's to own and not the host's to override.\n      push('event', name, { ...data, send_to: measurementId });\n    },\n\n    identify(user: UserData, traits?: Record<string, unknown>): void {\n      // GA4 documents no browser slot for email, phone or names. They map to\n      // nothing, which is what \"this concept does not exist here\" means.\n      if (user.userId !== undefined) push('set', { user_id: user.userId });\n      if (traits) push('set', 'user_properties', traits);\n    },\n\n    consent(command: 'default' | 'update', state: ConsentState): void {\n      // Verbatim: the library's consent vocabulary is Google's own spelling,\n      // so there is nothing to translate and no chance to expand a signal\n      // the host did not declare.\n      push('consent', command, state);\n    },\n  };\n}\n","import { assertUniqueProviders, makeReporter, messageOf, resolveEvent } from './dispatch.js';\n\nexport { type Ga4BrowserConfig, ga4 } from './providers/ga4.browser.js';\n\nimport type {\n  ConsentState,\n  EventBinding,\n  EventData,\n  ProviderDefault,\n  TrackingError,\n  UserData,\n} from './vocabulary.js';\n\n/**\n * Everything the browser needs beyond the event itself.\n *\n * There is one field, and that is the point: in the browser each vendor tag\n * reads its own cookies and holds its own session, so the only thing left\n * for the host to supply is the value that ties this hit to a server-side\n * one.\n */\nexport interface TrackOptions {\n  /**\n   * The value that lets a vendor recognise this hit and a server-side hit as\n   * one event. The library never invents it — the browser and the server do\n   * not share a process, so only a value the host already owns (an order id)\n   * can match on both sides.\n   */\n  dedupId?: string;\n}\n\n/**\n * A destination for browser events.\n *\n * This is the whole contract, and it is what a provider written outside this\n * package implements — the ones shipped here get no shortcut.\n */\nexport interface BrowserProvider<Target = string> {\n  /** The vendor's fixed name. Registering one twice is an error. */\n  name: string;\n  /** What happens to a canonical event this vendor has no binding for. */\n  default: ProviderDefault;\n  /** How this vendor spells each canonical event. */\n  events?: Record<string, EventBinding<Target>>;\n  /** Loads the vendor tag. Runs once, at creation. */\n  install?(): void | Promise<void>;\n  track(name: Target, data: EventData, options: TrackOptions): void;\n  /** Absent where the vendor keeps no user of its own. */\n  identify?(user: UserData, traits?: Record<string, unknown>): void;\n  /** Absent where the vendor documents no consent command. */\n  consent?(command: 'default' | 'update', state: ConsentState): void;\n}\n\n/** Options accepted by {@link createTracking}. */\nexport interface BrowserTrackingOptions {\n  providers: readonly BrowserProvider[];\n  /**\n   * The one diagnostic channel. Without it the library is silent, exactly as\n   * a hand-written vendor call is.\n   */\n  onError?: (error: TrackingError) => void;\n}\n\n/** What {@link createTracking} returns. */\nexport interface BrowserTracking {\n  /** Sends one event to every configured vendor. Never throws. */\n  track(name: string, data?: EventData, options?: TrackOptions): void;\n  /** Forwards the user to the vendors that hold one, and to nobody else. */\n  identify(user: UserData, traits?: Record<string, unknown>): void;\n  /**\n   * Forwards a consent declaration to every vendor that documents a command\n   * for it. It never decides, stores or withholds anything.\n   */\n  consent(command: 'default' | 'update', state: ConsentState): void;\n}\n\n/**\n * Creates the browser tracking surface.\n *\n * Providers install eagerly, which is what pasting a vendor snippet does and\n * what lets each vendor record its own initial page view. Every vendor\n * shipped here queues its own commands until its script lands, so nothing is\n * lost to loading and this library needs no queue of its own.\n *\n * @param options - The providers to send to, and an optional error channel.\n * @returns The `track`, `identify` and `consent` calls.\n *\n * @example\n * ```ts\n * import { createTracking, ga4 } from 'tracklane/browser';\n *\n * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });\n * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });\n * ```\n */\nexport function createTracking(options: BrowserTrackingOptions): BrowserTracking {\n  const { providers } = options;\n  assertUniqueProviders(providers);\n\n  const report = makeReporter(options.onError);\n\n  const fail = (provider: string, event: string, cause: unknown): void => {\n    report({ provider, event, severity: 'error', message: messageOf(cause), cause });\n  };\n\n  for (const provider of providers) {\n    try {\n      const installing = provider.install?.();\n      // An async loader that rejects would otherwise become an unhandled\n      // rejection — the silent failure this channel exists to prevent.\n      void Promise.resolve(installing).catch((cause: unknown) => {\n        fail(provider.name, 'install', cause);\n      });\n    } catch (cause) {\n      fail(provider.name, 'install', cause);\n    }\n  }\n\n  return {\n    track(name, data = {}, trackOptions = {}) {\n      for (const provider of providers) {\n        const target = resolveEvent(provider, name);\n        if (target === undefined) continue;\n\n        try {\n          provider.track(target, data, trackOptions);\n        } catch (cause) {\n          fail(provider.name, name, cause);\n        }\n      }\n    },\n\n    identify(user, traits) {\n      for (const provider of providers) {\n        try {\n          provider.identify?.(user, traits);\n        } catch (cause) {\n          fail(provider.name, 'identify', cause);\n        }\n      }\n    },\n\n    consent(command, state) {\n      for (const provider of providers) {\n        try {\n          provider.consent?.(command, state);\n        } catch (cause) {\n          fail(provider.name, 'consent', cause);\n        }\n      }\n    },\n  };\n}\n"],"mappings":";;AAkBA,SAAS,aAAqC;CAC5C,OAAO,OAAO,WAAW,cAAc,KAAA,IAAa;AACtD;;;;;;;;AASA,SAAS,KAAK,GAAG,MAAuB;CACtC,MAAM,OAAO,WAAW,CAAC,EAAE;CAE3B,IAAI,CAAC,MACH,MAAM,IAAI,MACR,yFACF;CAGF,KAAK,GAAG,IAAI;AACd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,IAAI,eAAuB,SAA2B,CAAC,GAAoB;CACzF,MAAM,EAAE,WAAW;CAEnB,OAAO;EACL,MAAM;EAGN,SAAS;EACT,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;EAE3B,MAAM,MAAc,MAAiB,UAA8B;GASjE,KAAK,SAAS,MAAM;IAAE,GAAG;IAAM,SAAS;GAAc,CAAC;EACzD;EAEA,SAAS,MAAgB,QAAwC;GAG/D,IAAI,KAAK,WAAW,KAAA,GAAW,KAAK,OAAO,EAAE,SAAS,KAAK,OAAO,CAAC;GACnE,IAAI,QAAQ,KAAK,OAAO,mBAAmB,MAAM;EACnD;EAEA,QAAQ,SAA+B,OAA2B;GAIhE,KAAK,WAAW,SAAS,KAAK;EAChC;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;ACXA,SAAgB,eAAe,SAAkD;CAC/E,MAAM,EAAE,cAAc;CACtB,sBAAsB,SAAS;CAE/B,MAAM,SAAS,aAAa,QAAQ,OAAO;CAE3C,MAAM,QAAQ,UAAkB,OAAe,UAAyB;EACtE,OAAO;GAAE;GAAU;GAAO,UAAU;GAAS,SAAS,UAAU,KAAK;GAAG;EAAM,CAAC;CACjF;CAEA,KAAK,MAAM,YAAY,WACrB,IAAI;EACF,MAAM,aAAa,SAAS,UAAU;EAGtC,QAAa,QAAQ,UAAU,CAAC,CAAC,OAAO,UAAmB;GACzD,KAAK,SAAS,MAAM,WAAW,KAAK;EACtC,CAAC;CACH,SAAS,OAAO;EACd,KAAK,SAAS,MAAM,WAAW,KAAK;CACtC;CAGF,OAAO;EACL,MAAM,MAAM,OAAO,CAAC,GAAG,eAAe,CAAC,GAAG;GACxC,KAAK,MAAM,YAAY,WAAW;IAChC,MAAM,SAAS,aAAa,UAAU,IAAI;IAC1C,IAAI,WAAW,KAAA,GAAW;IAE1B,IAAI;KACF,SAAS,MAAM,QAAQ,MAAM,YAAY;IAC3C,SAAS,OAAO;KACd,KAAK,SAAS,MAAM,MAAM,KAAK;IACjC;GACF;EACF;EAEA,SAAS,MAAM,QAAQ;GACrB,KAAK,MAAM,YAAY,WACrB,IAAI;IACF,SAAS,WAAW,MAAM,MAAM;GAClC,SAAS,OAAO;IACd,KAAK,SAAS,MAAM,YAAY,KAAK;GACvC;EAEJ;EAEA,QAAQ,SAAS,OAAO;GACtB,KAAK,MAAM,YAAY,WACrB,IAAI;IACF,SAAS,UAAU,SAAS,KAAK;GACnC,SAAS,OAAO;IACd,KAAK,SAAS,MAAM,WAAW,KAAK;GACtC;EAEJ;CACF;AACF"}

package/dist/dispatch-DK2GBnkt.js

@@ -0,0 +1,51 @@
+//#region src/dispatch.ts
+/**
+* Registering one vendor twice is a hard error rather than a merge: there is
+* nothing a second registration could say that the first cannot, and
+* accepting both would double every event to that vendor — a defect that
+* surfaces weeks later as inflated conversions.
+*/
+function assertUniqueProviders(providers) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const provider of providers) {
+		if (seen.has(provider.name)) throw new Error(`tracklane: provider "${provider.name}" is registered twice. One configuration per vendor.`);
+		seen.add(provider.name);
+	}
+}
+/**
+* Resolves how a vendor spells a canonical event, or `undefined` when
+* nothing should be sent.
+*
+* Not sending is a legitimate outcome rather than a failure: `null` is the
+* host saying "never send this event here", and `ignore` is a vendor whose
+* event identity is minted per account in its own dashboard, so there is no
+* name that could possibly be guessed.
+*/
+function resolveEvent(provider, name) {
+	const events = provider.events;
+	const binding = events && Object.hasOwn(events, name) ? events[name] : void 0;
+	if (binding === null) return void 0;
+	if (binding !== void 0) return binding;
+	if (provider.default === "ignore") return void 0;
+	return name;
+}
+/**
+* Builds the reporting channel. A host that passes no `onError` gets
+* silence, which is what a hand-written vendor call gives it.
+*/
+function makeReporter(onError) {
+	if (!onError) return () => {};
+	return (error) => {
+		try {
+			onError(error);
+		} catch {}
+	};
+}
+/** Normalises whatever a provider threw into a reportable message. */
+function messageOf(cause) {
+	return cause instanceof Error ? cause.message : String(cause);
+}
+//#endregion
+export { resolveEvent as i, makeReporter as n, messageOf as r, assertUniqueProviders as t };
+
+//# sourceMappingURL=dispatch-DK2GBnkt.js.map

package/dist/dispatch-DK2GBnkt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-DK2GBnkt.js","names":[],"sources":["../src/dispatch.ts"],"sourcesContent":["import type { EventBinding, ProviderDefault, TrackingError } from './vocabulary.js';\n\n/** The part of a provider both libraries resolve event names against. */\ninterface Resolvable<Target> {\n  name: string;\n  default: ProviderDefault;\n  events?: Record<string, EventBinding<Target>>;\n}\n\n/**\n * Registering one vendor twice is a hard error rather than a merge: there is\n * nothing a second registration could say that the first cannot, and\n * accepting both would double every event to that vendor — a defect that\n * surfaces weeks later as inflated conversions.\n */\nexport function assertUniqueProviders(providers: readonly { name: string }[]): void {\n  const seen = new Set<string>();\n\n  for (const provider of providers) {\n    if (seen.has(provider.name)) {\n      throw new Error(\n        `tracklane: provider \"${provider.name}\" is registered twice. One configuration per vendor.`,\n      );\n    }\n    seen.add(provider.name);\n  }\n}\n\n/**\n * Resolves how a vendor spells a canonical event, or `undefined` when\n * nothing should be sent.\n *\n * Not sending is a legitimate outcome rather than a failure: `null` is the\n * host saying \"never send this event here\", and `ignore` is a vendor whose\n * event identity is minted per account in its own dashboard, so there is no\n * name that could possibly be guessed.\n */\nexport function resolveEvent<Target>(\n  provider: Resolvable<Target>,\n  name: string,\n): Target | undefined {\n  const events = provider.events;\n  // `hasOwn`, not a plain lookup: every object inherits `constructor` and\n  // `toString`, so an event named either would otherwise resolve to a\n  // function off the prototype chain.\n  const binding = events && Object.hasOwn(events, name) ? events[name] : undefined;\n\n  if (binding === null) return undefined;\n  if (binding !== undefined) return binding;\n  if (provider.default === 'ignore') return undefined;\n\n  return name as Target;\n}\n\n/**\n * Builds the reporting channel. A host that passes no `onError` gets\n * silence, which is what a hand-written vendor call gives it.\n */\nexport function makeReporter(\n  onError: ((error: TrackingError) => void) | undefined,\n): (error: TrackingError) => void {\n  if (!onError) return () => {};\n\n  return (error) => {\n    // A throwing reporter must not take the dispatch down with it, or a\n    // host's broken logger becomes a broken checkout.\n    try {\n      onError(error);\n    } catch {\n      /* the reporter is the last line; there is nowhere left to report to */\n    }\n  };\n}\n\n/** Normalises whatever a provider threw into a reportable message. */\nexport function messageOf(cause: unknown): string {\n  return cause instanceof Error ? cause.message : String(cause);\n}\n"],"mappings":";;;;;;;AAeA,SAAgB,sBAAsB,WAA8C;CAClF,MAAM,uBAAO,IAAI,IAAY;CAE7B,KAAK,MAAM,YAAY,WAAW;EAChC,IAAI,KAAK,IAAI,SAAS,IAAI,GACxB,MAAM,IAAI,MACR,wBAAwB,SAAS,KAAK,qDACxC;EAEF,KAAK,IAAI,SAAS,IAAI;CACxB;AACF;;;;;;;;;;AAWA,SAAgB,aACd,UACA,MACoB;CACpB,MAAM,SAAS,SAAS;CAIxB,MAAM,UAAU,UAAU,OAAO,OAAO,QAAQ,IAAI,IAAI,OAAO,QAAQ,KAAA;CAEvE,IAAI,YAAY,MAAM,OAAO,KAAA;CAC7B,IAAI,YAAY,KAAA,GAAW,OAAO;CAClC,IAAI,SAAS,YAAY,UAAU,OAAO,KAAA;CAE1C,OAAO;AACT;;;;;AAMA,SAAgB,aACd,SACgC;CAChC,IAAI,CAAC,SAAS,aAAa,CAAC;CAE5B,QAAQ,UAAU;EAGhB,IAAI;GACF,QAAQ,KAAK;EACf,QAAQ,CAER;CACF;AACF;;AAGA,SAAgB,UAAU,OAAwB;CAChD,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { a as EventItem, c as UserData, i as EventData, n as ConsentState, o as ProviderDefault, r as EventBinding, s as TrackingError, t as ActionSource } from "./vocabulary-ByyXHVWd.js";
+import { i as TrackOptions, n as BrowserTracking, r as BrowserTrackingOptions, t as BrowserProvider } from "./browser-BQNJ4qUq.js";
+import { a as ServerTrackingOptions, i as ServerTracking, n as ResolvedContext, r as ServerProvider, t as EventContext } from "./server-cNxLsKhl.js";
+export type { ActionSource, BrowserProvider, BrowserTracking, BrowserTrackingOptions, ConsentState, EventBinding, EventContext, EventData, EventItem, ProviderDefault, ResolvedContext, ServerProvider, ServerTracking, ServerTrackingOptions, TrackOptions, TrackingError, UserData };

package/dist/server-cNxLsKhl.d.ts

@@ -0,0 +1,152 @@
+import { c as UserData, i as EventData, n as ConsentState, o as ProviderDefault, r as EventBinding, s as TrackingError, t as ActionSource } from "./vocabulary-ByyXHVWd.js";
+//#region src/providers/ga4.server.d.ts
+/** Credentials for the GA4 Measurement Protocol. */
+interface Ga4ServerCredentials {
+  /** The `G-` id of the data stream. */
+  measurementId: string;
+  /** Created under Admin → Data Streams → Measurement Protocol. */
+  apiSecret: string;
+}
+/** Optional configuration for the GA4 server provider. */
+interface Ga4ServerConfig {
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * Google Analytics 4 on the server, through the Measurement Protocol.
+ *
+ * @param credentials - The measurement id and API secret.
+ * @param config - Rarely needed event name overrides.
+ * @returns A provider for `createTracking` from `tracklane/server`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/server';
+ *
+ * const { track } = createTracking({
+ *   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret: process.env.GA4_SECRET! })],
+ * });
+ *
+ * await track('purchase', order, { cookies: request.headers.get('cookie') });
+ * ```
+ */
+declare function ga4(credentials: Ga4ServerCredentials, config?: Ga4ServerConfig): ServerProvider;
+//#endregion
+//#region src/server.d.ts
+/**
+ * Everything a conversion API needs beyond the event itself: who the person
+ * is, when it happened, and where it was observed.
+ *
+ * None of this is "what happened", which is why it does not travel in the
+ * event data — putting it there would leak identity into the pass-through
+ * event params of the vendors that forward the payload as-is.
+ */
+interface EventContext {
+  user?: UserData;
+  /**
+   * The request's raw `Cookie` header, or an already-parsed map.
+   *
+   * These are cookies the vendors' own browser tags set — this library never
+   * writes one. On the server each adapter reads the cookies belonging to
+   * its own vendor: Meta forwards its value as-is, Google's holds several
+   * things at once and has to be opened. That knowledge lives in the
+   * adapters; the core only splits `name=value; name=value` into pairs.
+   *
+   * **It splits, it does not interpret.** Values are handed over exactly as
+   * they appear, with no percent-decoding. The cookies these vendors set do
+   * not need it; a host reading some other cookie should decode it itself.
+   */
+  cookies?: string | Record<string, string> | null;
+  /** Ties this send to a browser hit. Never invented by the library. */
+  dedupId?: string;
+  /**
+   * When the conversion actually happened. Defaults to now.
+   *
+   * A webhook arrives after the fact and LinkedIn rejects conversions older
+   * than 90 days, so reporting "now" for everything would quietly distort
+   * attribution.
+   */
+  timestamp?: number | Date;
+  /** Overrides the factory default. Meta requires it on every event. */
+  source?: ActionSource;
+  url?: string;
+  ip?: string;
+  userAgent?: string;
+  /** What is known *about* the person: GA4 user properties, PostHog `$set`. */
+  traits?: Record<string, unknown>;
+  /**
+   * Travels inside the event, for the vendors that document such a field.
+   * Today that is GA4's Measurement Protocol, and it reads two of the
+   * signals; the others have no slot and ignore it.
+   */
+  consent?: ConsentState;
+}
+/** The context an adapter receives, with the ambiguity resolved. */
+interface ResolvedContext extends Omit<EventContext, "cookies" | "timestamp"> {
+  cookies: Record<string, string>;
+  /** Epoch milliseconds. Adapters convert to their vendor's spelling. */
+  timestamp: number;
+}
+/**
+ * A destination for server events.
+ *
+ * `track` may throw — on a non-2xx, or where a vendor documents a
+ * precondition the event cannot meet. The dispatcher isolates and reports
+ * it, so adapters stay honest and loud.
+ *
+ * `report` is for a caveat about a request that already succeeded. It is
+ * never a throw: by then the send happened, and throwing would tell a host's
+ * retry logic to resend a delivered conversion.
+ */
+interface ServerProvider<Target = string> {
+  name: string;
+  default: ProviderDefault;
+  events?: Record<string, EventBinding<Target>>;
+  track(name: Target, data: EventData, context: ResolvedContext, report: (message: string) => void): Promise<void>;
+}
+/** Options accepted by {@link createTracking}. */
+interface ServerTrackingOptions {
+  providers: readonly ServerProvider[];
+  onError?: (error: TrackingError) => void;
+}
+/** What {@link createTracking} returns. */
+interface ServerTracking {
+  /**
+   * Sends one event to every configured conversion API.
+   *
+   * Resolves once every provider has settled and never rejects: one vendor
+   * being down is not the caller's failure to handle. Awaiting is about the
+   * request surviving a serverless runtime, not about delivery being
+   * guaranteed.
+   */
+  track(name: string, data?: EventData, context?: EventContext): Promise<void>;
+}
+/**
+ * Creates the server tracking surface.
+ *
+ * There is no `identify` here and nothing is held between calls: a server
+ * instance is shared by every request, so a retained identity would attach
+ * one visitor to another visitor's conversion. Identity travels with the
+ * call, which is also what every conversion API expects.
+ *
+ * There is no `consent` call either — consent commands are properties of a
+ * vendor's on-page tag, and a server request has no tag. The one vendor that
+ * accepts consent server-side reads it from the context.
+ *
+ * @param options - The providers to send to, and an optional error channel.
+ * @returns The `track` call.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/server';
+ *
+ * const { track } = createTracking({
+ *   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret })],
+ * });
+ *
+ * await track('purchase', order, { cookies: request.headers.get('cookie') });
+ * ```
+ */
+declare function createTracking(options: ServerTrackingOptions): ServerTracking;
+//#endregion
+export { ServerTrackingOptions as a, Ga4ServerCredentials as c, ServerTracking as i, ga4 as l, ResolvedContext as n, createTracking as o, ServerProvider as r, Ga4ServerConfig as s, EventContext as t };
+//# sourceMappingURL=server-cNxLsKhl.d.ts.map

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { a as ServerTrackingOptions, c as Ga4ServerCredentials, i as ServerTracking, l as ga4, n as ResolvedContext, o as createTracking, r as ServerProvider, s as Ga4ServerConfig, t as EventContext } from "./server-cNxLsKhl.js";
+export { EventContext, type Ga4ServerConfig, type Ga4ServerCredentials, ResolvedContext, ServerProvider, ServerTracking, ServerTrackingOptions, createTracking, ga4 };

package/dist/server.js

@@ -0,0 +1,190 @@
+import { i as resolveEvent, n as makeReporter, r as messageOf, t as assertUniqueProviders } from "./dispatch-DK2GBnkt.js";
+//#region src/providers/ga4.server.ts
+const ENDPOINT = "https://www.google-analytics.com/mp/collect";
+/**
+* The visitor cookie holds `GA1.<depth>.<client_id>`, and the client id
+* itself contains a dot — so the identifier is the last two segments, which
+* is what survives Google's varying prefix depth.
+*
+* The value must be the cookie as the browser wrote it. A host passing a
+* parsed map passes cookie values, not values it took apart itself.
+*/
+function visitorId(cookies) {
+	const raw = cookies._ga;
+	if (!raw) return void 0;
+	const parts = raw.split(".");
+	if (parts.length < 4) return void 0;
+	return parts.slice(-2).join(".");
+}
+/**
+* The per-container cookie carries the session, in one of two layouts.
+*
+* Verified against Google's live tag on 2026-07-31 rather than assumed:
+*
+* - `GS2.1.s1785511401$o1$g0$t1785511401$j60$l0$h0` — the current one. The
+*   third dot-segment packs several fields joined by `$`, and the session is
+*   the first of them, prefixed with `s`.
+* - `GS1.1.1785511401.1.1.…` — the older one, where the third dot-segment is
+*   the session on its own.
+*
+* Reading the third segment blindly works for the old layout and returns the
+* whole `s…$o1$g0$…` blob for the new one — which the vendor would accept and
+* silently fail to match. Hence the two shapes, and hence `undefined` rather
+* than a guess when neither fits.
+*/
+function sessionId(cookies, measurementId) {
+	const segment = cookies[`_ga_${measurementId.replace(/^G-/, "")}`]?.split(".")[2];
+	if (!segment) return void 0;
+	const packed = /^s(\d+)/.exec(segment);
+	if (packed) return packed[1];
+	return /^\d+$/.test(segment) ? segment : void 0;
+}
+/**
+* The Measurement Protocol documents exactly two consent fields, and spells
+* their values in upper case where the browser spells them in lower — one of
+* the small asymmetries an adapter absorbs so nobody else has to.
+*/
+function consentBody(state) {
+	if (!state) return void 0;
+	const body = {};
+	if (state.ad_user_data) body.ad_user_data = state.ad_user_data.toUpperCase();
+	if (state.ad_personalization) body.ad_personalization = state.ad_personalization.toUpperCase();
+	return Object.keys(body).length > 0 ? body : void 0;
+}
+/**
+* Google Analytics 4 on the server, through the Measurement Protocol.
+*
+* @param credentials - The measurement id and API secret.
+* @param config - Rarely needed event name overrides.
+* @returns A provider for `createTracking` from `tracklane/server`.
+*
+* @example
+* ```ts
+* import { createTracking, ga4 } from 'tracklane/server';
+*
+* const { track } = createTracking({
+*   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret: process.env.GA4_SECRET! })],
+* });
+*
+* await track('purchase', order, { cookies: request.headers.get('cookie') });
+* ```
+*/
+function ga4(credentials, config = {}) {
+	const { measurementId, apiSecret } = credentials;
+	return {
+		name: "ga4",
+		default: "passthrough",
+		...config.events ? { events: config.events } : {},
+		async track(name, data, context, report) {
+			const clientId = visitorId(context.cookies);
+			if (!clientId) throw new Error("ga4: cannot build client_id — no _ga cookie among the cookies passed in context");
+			const session = sessionId(context.cookies, measurementId);
+			if (!session) report("no session cookie (_ga_<container>): Google will accept this event and it will not appear in any report");
+			const params = { ...data };
+			if (session) {
+				params.session_id = session;
+				params.engagement_time_msec = 1;
+			}
+			const body = {
+				client_id: clientId,
+				timestamp_micros: context.timestamp * 1e3,
+				events: [{
+					name,
+					params
+				}]
+			};
+			if (context.user?.userId !== void 0) body.user_id = context.user.userId;
+			if (context.traits) body.user_properties = Object.fromEntries(Object.entries(context.traits).map(([name, value]) => [name, { value }]));
+			const consent = consentBody(context.consent);
+			if (consent) body.consent = consent;
+			const url = `${ENDPOINT}?measurement_id=${encodeURIComponent(measurementId)}&api_secret=${encodeURIComponent(apiSecret)}`;
+			const response = await fetch(url, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body)
+			});
+			if (!response.ok) throw new Error(`ga4: the Measurement Protocol answered ${response.status}`);
+		}
+	};
+}
+//#endregion
+//#region src/server.ts
+/** `name=value; name=value` — the shape of a `Cookie` header. */
+function parseCookies(cookies) {
+	if (!cookies) return {};
+	if (typeof cookies !== "string") return cookies;
+	const parsed = {};
+	for (const pair of cookies.split(";")) {
+		const separator = pair.indexOf("=");
+		if (separator < 1) continue;
+		const name = pair.slice(0, separator).trim();
+		if (name) parsed[name] = pair.slice(separator + 1).trim();
+	}
+	return parsed;
+}
+/**
+* Creates the server tracking surface.
+*
+* There is no `identify` here and nothing is held between calls: a server
+* instance is shared by every request, so a retained identity would attach
+* one visitor to another visitor's conversion. Identity travels with the
+* call, which is also what every conversion API expects.
+*
+* There is no `consent` call either — consent commands are properties of a
+* vendor's on-page tag, and a server request has no tag. The one vendor that
+* accepts consent server-side reads it from the context.
+*
+* @param options - The providers to send to, and an optional error channel.
+* @returns The `track` call.
+*
+* @example
+* ```ts
+* import { createTracking, ga4 } from 'tracklane/server';
+*
+* const { track } = createTracking({
+*   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret })],
+* });
+*
+* await track('purchase', order, { cookies: request.headers.get('cookie') });
+* ```
+*/
+function createTracking(options) {
+	const { providers } = options;
+	assertUniqueProviders(providers);
+	const report = makeReporter(options.onError);
+	return { async track(name, data = {}, context = {}) {
+		const { cookies, timestamp, ...rest } = context;
+		const resolved = {
+			...rest,
+			cookies: parseCookies(cookies),
+			timestamp: timestamp instanceof Date ? timestamp.getTime() : timestamp ?? Date.now()
+		};
+		const sends = providers.map(async (provider) => {
+			const target = resolveEvent(provider, name);
+			if (target === void 0) return;
+			try {
+				await provider.track(target, data, resolved, (message) => {
+					report({
+						provider: provider.name,
+						event: name,
+						severity: "warning",
+						message
+					});
+				});
+			} catch (cause) {
+				report({
+					provider: provider.name,
+					event: name,
+					severity: "error",
+					message: messageOf(cause),
+					cause
+				});
+			}
+		});
+		await Promise.all(sends);
+	} };
+}
+//#endregion
+export { createTracking, ga4 };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/providers/ga4.server.ts","../src/server.ts"],"sourcesContent":["import type { ResolvedContext, ServerProvider } from '../server.js';\nimport type { ConsentState, EventBinding, EventData } from '../vocabulary.js';\n\nconst ENDPOINT = 'https://www.google-analytics.com/mp/collect';\n\n/** Credentials for the GA4 Measurement Protocol. */\nexport interface Ga4ServerCredentials {\n  /** The `G-` id of the data stream. */\n  measurementId: string;\n  /** Created under Admin → Data Streams → Measurement Protocol. */\n  apiSecret: string;\n}\n\n/** Optional configuration for the GA4 server provider. */\nexport interface Ga4ServerConfig {\n  events?: Record<string, EventBinding<string>>;\n}\n\n/**\n * The visitor cookie holds `GA1.<depth>.<client_id>`, and the client id\n * itself contains a dot — so the identifier is the last two segments, which\n * is what survives Google's varying prefix depth.\n *\n * The value must be the cookie as the browser wrote it. A host passing a\n * parsed map passes cookie values, not values it took apart itself.\n */\nfunction visitorId(cookies: Record<string, string>): string | undefined {\n  const raw = cookies._ga;\n  if (!raw) return undefined;\n\n  const parts = raw.split('.');\n  if (parts.length < 4) return undefined;\n\n  return parts.slice(-2).join('.');\n}\n\n/**\n * The per-container cookie carries the session, in one of two layouts.\n *\n * Verified against Google's live tag on 2026-07-31 rather than assumed:\n *\n * - `GS2.1.s1785511401$o1$g0$t1785511401$j60$l0$h0` — the current one. The\n *   third dot-segment packs several fields joined by `$`, and the session is\n *   the first of them, prefixed with `s`.\n * - `GS1.1.1785511401.1.1.…` — the older one, where the third dot-segment is\n *   the session on its own.\n *\n * Reading the third segment blindly works for the old layout and returns the\n * whole `s…$o1$g0$…` blob for the new one — which the vendor would accept and\n * silently fail to match. Hence the two shapes, and hence `undefined` rather\n * than a guess when neither fits.\n */\nfunction sessionId(cookies: Record<string, string>, measurementId: string): string | undefined {\n  // Scoped to *this* property's cookie. A page with two GA4 properties has two\n  // `_ga_*` cookies, and taking whichever came first would attach another\n  // property's session to our event — which Google accepts and never matches.\n  const value = cookies[`_ga_${measurementId.replace(/^G-/, '')}`];\n  const segment = value?.split('.')[2];\n  if (!segment) return undefined;\n\n  const packed = /^s(\\d+)/.exec(segment);\n  if (packed) return packed[1];\n\n  // The older layout: a bare session id, nothing packed around it.\n  return /^\\d+$/.test(segment) ? segment : undefined;\n}\n\n/**\n * The Measurement Protocol documents exactly two consent fields, and spells\n * their values in upper case where the browser spells them in lower — one of\n * the small asymmetries an adapter absorbs so nobody else has to.\n */\nfunction consentBody(state: ConsentState | undefined): Record<string, string> | undefined {\n  if (!state) return undefined;\n\n  const body: Record<string, string> = {};\n  if (state.ad_user_data) body.ad_user_data = state.ad_user_data.toUpperCase();\n  if (state.ad_personalization) body.ad_personalization = state.ad_personalization.toUpperCase();\n\n  return Object.keys(body).length > 0 ? body : undefined;\n}\n\n/**\n * Google Analytics 4 on the server, through the Measurement Protocol.\n *\n * @param credentials - The measurement id and API secret.\n * @param config - Rarely needed event name overrides.\n * @returns A provider for `createTracking` from `tracklane/server`.\n *\n * @example\n * ```ts\n * import { createTracking, ga4 } from 'tracklane/server';\n *\n * const { track } = createTracking({\n *   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret: process.env.GA4_SECRET! })],\n * });\n *\n * await track('purchase', order, { cookies: request.headers.get('cookie') });\n * ```\n */\nexport function ga4(\n  credentials: Ga4ServerCredentials,\n  config: Ga4ServerConfig = {},\n): ServerProvider {\n  const { measurementId, apiSecret } = credentials;\n\n  return {\n    name: 'ga4',\n    default: 'passthrough',\n    ...(config.events ? { events: config.events } : {}),\n\n    async track(\n      name: string,\n      data: EventData,\n      context: ResolvedContext,\n      report: (message: string) => void,\n    ): Promise<void> {\n      const clientId = visitorId(context.cookies);\n      if (!clientId) {\n        // Not withholding on policy grounds: the protocol requires this and\n        // it cannot be invented. The endpoint answers success even to\n        // invalid payloads, so sending anyway would look like it worked.\n        // Naming the vendor's own field, so that searching Google's docs\n        // for the error leads somewhere.\n        throw new Error(\n          'ga4: cannot build client_id — no _ga cookie among the cookies passed in context',\n        );\n      }\n\n      const session = sessionId(context.cookies, measurementId);\n      if (!session) {\n        report(\n          'no session cookie (_ga_<container>): Google will accept this event and it will not appear in any report',\n        );\n      }\n\n      const params: Record<string, unknown> = { ...data };\n      if (session) {\n        params.session_id = session;\n        // Google drops sessions with no engagement from its reports, so the\n        // event would arrive and still be invisible without this.\n        params.engagement_time_msec = 1;\n      }\n\n      // The dedup id maps nowhere: GA4 documents no browser-to-server\n      // deduplication. `transaction_id` — business data — travels in params\n      // and is the duplicate control this vendor does have.\n      const body: Record<string, unknown> = {\n        client_id: clientId,\n        timestamp_micros: context.timestamp * 1000,\n        events: [{ name, params }],\n      };\n\n      if (context.user?.userId !== undefined) body.user_id = context.user.userId;\n\n      if (context.traits) {\n        // Each property is an object with a `value` key here, where the\n        // browser takes the bare value. Sending the bare value is rejected\n        // by Google's validation endpoint and **accepted with 204 by the\n        // collection endpoint**, which then drops it — verified on\n        // 2026-07-31. One of several places where this vendor fails by\n        // accepting.\n        body.user_properties = Object.fromEntries(\n          Object.entries(context.traits).map(([name, value]) => [name, { value }]),\n        );\n      }\n\n      const consent = consentBody(context.consent);\n      if (consent) body.consent = consent;\n\n      // Credentials go in the query because the protocol offers no\n      // alternative. Query strings land in proxy and APM logs; that\n      // exposure is Google's design, not a choice made here.\n      const url = `${ENDPOINT}?measurement_id=${encodeURIComponent(measurementId)}&api_secret=${encodeURIComponent(apiSecret)}`;\n\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json' },\n        body: JSON.stringify(body),\n      });\n\n      if (!response.ok) {\n        // The status only. The event carries raw personal data, and no\n        // library-owned surface re-emits it into a host's logs.\n        throw new Error(`ga4: the Measurement Protocol answered ${response.status}`);\n      }\n    },\n  };\n}\n","import { assertUniqueProviders, makeReporter, messageOf, resolveEvent } from './dispatch.js';\n\nexport {\n  type Ga4ServerConfig,\n  type Ga4ServerCredentials,\n  ga4,\n} from './providers/ga4.server.js';\n\nimport type {\n  ActionSource,\n  ConsentState,\n  EventBinding,\n  EventData,\n  ProviderDefault,\n  TrackingError,\n  UserData,\n} from './vocabulary.js';\n\n/**\n * Everything a conversion API needs beyond the event itself: who the person\n * is, when it happened, and where it was observed.\n *\n * None of this is \"what happened\", which is why it does not travel in the\n * event data — putting it there would leak identity into the pass-through\n * event params of the vendors that forward the payload as-is.\n */\nexport interface EventContext {\n  user?: UserData;\n  /**\n   * The request's raw `Cookie` header, or an already-parsed map.\n   *\n   * These are cookies the vendors' own browser tags set — this library never\n   * writes one. On the server each adapter reads the cookies belonging to\n   * its own vendor: Meta forwards its value as-is, Google's holds several\n   * things at once and has to be opened. That knowledge lives in the\n   * adapters; the core only splits `name=value; name=value` into pairs.\n   *\n   * **It splits, it does not interpret.** Values are handed over exactly as\n   * they appear, with no percent-decoding. The cookies these vendors set do\n   * not need it; a host reading some other cookie should decode it itself.\n   */\n  cookies?: string | Record<string, string> | null;\n  /** Ties this send to a browser hit. Never invented by the library. */\n  dedupId?: string;\n  /**\n   * When the conversion actually happened. Defaults to now.\n   *\n   * A webhook arrives after the fact and LinkedIn rejects conversions older\n   * than 90 days, so reporting \"now\" for everything would quietly distort\n   * attribution.\n   */\n  timestamp?: number | Date;\n  /** Overrides the factory default. Meta requires it on every event. */\n  source?: ActionSource;\n  url?: string;\n  ip?: string;\n  userAgent?: string;\n  /** What is known *about* the person: GA4 user properties, PostHog `$set`. */\n  traits?: Record<string, unknown>;\n  /**\n   * Travels inside the event, for the vendors that document such a field.\n   * Today that is GA4's Measurement Protocol, and it reads two of the\n   * signals; the others have no slot and ignore it.\n   */\n  consent?: ConsentState;\n}\n\n/** The context an adapter receives, with the ambiguity resolved. */\nexport interface ResolvedContext extends Omit<EventContext, 'cookies' | 'timestamp'> {\n  cookies: Record<string, string>;\n  /** Epoch milliseconds. Adapters convert to their vendor's spelling. */\n  timestamp: number;\n}\n\n/**\n * A destination for server events.\n *\n * `track` may throw — on a non-2xx, or where a vendor documents a\n * precondition the event cannot meet. The dispatcher isolates and reports\n * it, so adapters stay honest and loud.\n *\n * `report` is for a caveat about a request that already succeeded. It is\n * never a throw: by then the send happened, and throwing would tell a host's\n * retry logic to resend a delivered conversion.\n */\nexport interface ServerProvider<Target = string> {\n  name: string;\n  default: ProviderDefault;\n  events?: Record<string, EventBinding<Target>>;\n  track(\n    name: Target,\n    data: EventData,\n    context: ResolvedContext,\n    report: (message: string) => void,\n  ): Promise<void>;\n}\n\n/** Options accepted by {@link createTracking}. */\nexport interface ServerTrackingOptions {\n  providers: readonly ServerProvider[];\n  onError?: (error: TrackingError) => void;\n}\n\n/** What {@link createTracking} returns. */\nexport interface ServerTracking {\n  /**\n   * Sends one event to every configured conversion API.\n   *\n   * Resolves once every provider has settled and never rejects: one vendor\n   * being down is not the caller's failure to handle. Awaiting is about the\n   * request surviving a serverless runtime, not about delivery being\n   * guaranteed.\n   */\n  track(name: string, data?: EventData, context?: EventContext): Promise<void>;\n}\n\n/** `name=value; name=value` — the shape of a `Cookie` header. */\nfunction parseCookies(\n  cookies: string | Record<string, string> | null | undefined,\n): Record<string, string> {\n  if (!cookies) return {};\n  if (typeof cookies !== 'string') return cookies;\n\n  const parsed: Record<string, string> = {};\n\n  for (const pair of cookies.split(';')) {\n    const separator = pair.indexOf('=');\n    if (separator < 1) continue;\n\n    const name = pair.slice(0, separator).trim();\n    // Cookie values may contain `=`, so only the first one separates.\n    if (name) parsed[name] = pair.slice(separator + 1).trim();\n  }\n\n  return parsed;\n}\n\n/**\n * Creates the server tracking surface.\n *\n * There is no `identify` here and nothing is held between calls: a server\n * instance is shared by every request, so a retained identity would attach\n * one visitor to another visitor's conversion. Identity travels with the\n * call, which is also what every conversion API expects.\n *\n * There is no `consent` call either — consent commands are properties of a\n * vendor's on-page tag, and a server request has no tag. The one vendor that\n * accepts consent server-side reads it from the context.\n *\n * @param options - The providers to send to, and an optional error channel.\n * @returns The `track` call.\n *\n * @example\n * ```ts\n * import { createTracking, ga4 } from 'tracklane/server';\n *\n * const { track } = createTracking({\n *   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret })],\n * });\n *\n * await track('purchase', order, { cookies: request.headers.get('cookie') });\n * ```\n */\nexport function createTracking(options: ServerTrackingOptions): ServerTracking {\n  const { providers } = options;\n  assertUniqueProviders(providers);\n\n  const report = makeReporter(options.onError);\n\n  return {\n    async track(name, data = {}, context = {}) {\n      const { cookies, timestamp, ...rest } = context;\n      const resolved: ResolvedContext = {\n        ...rest,\n        cookies: parseCookies(cookies),\n        timestamp: timestamp instanceof Date ? timestamp.getTime() : (timestamp ?? Date.now()),\n      };\n\n      const sends = providers.map(async (provider) => {\n        const target = resolveEvent(provider, name);\n        if (target === undefined) return;\n\n        try {\n          await provider.track(target, data, resolved, (message) => {\n            report({ provider: provider.name, event: name, severity: 'warning', message });\n          });\n        } catch (cause) {\n          report({\n            provider: provider.name,\n            event: name,\n            severity: 'error',\n            message: messageOf(cause),\n            cause,\n          });\n        }\n      });\n\n      await Promise.all(sends);\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/vocabulary-ByyXHVWd.d.ts

@@ -0,0 +1,107 @@
+//#region src/vocabulary.d.ts
+/**
+ * The vocabulary shared by the browser and server libraries.
+ *
+ * These two libraries never talk to each other — no runtime, no state, no
+ * instance in common. What they share is this: the names of events and the
+ * shape of the data that travels with them, so that `purchase` means the
+ * same thing on both sides. It is the only sharing with a reason to exist.
+ */
+/** One item inside an ecommerce event, spelled the way GA4 spells it. */
+interface EventItem {
+  item_id?: string;
+  item_name?: string;
+  price?: number;
+  quantity?: number;
+  [key: string]: unknown;
+}
+/**
+ * The business payload of an event.
+ *
+ * The named fields are the ones adapters read to build vendor-specific value
+ * and content slots. The index signature is deliberate: a business measures
+ * things this vocabulary does not name, and closing the bag would make the
+ * library the arbiter of what may be measured.
+ */
+interface EventData {
+  transaction_id?: string;
+  value?: number;
+  currency?: string;
+  items?: EventItem[];
+  [key: string]: unknown;
+}
+/**
+ * Who the person is.
+ *
+ * One identifier for the person, which every vendor receives under its own
+ * name. Values are always raw — hashing and normalisation are field formats
+ * each vendor defines, applied inside the adapter that owns the field.
+ *
+ * Everything else that identifies someone arrives through cookies on the
+ * server, read by whichever adapter knows the format.
+ */
+interface UserData {
+  /** One id for the person, translated per vendor. */
+  userId?: string;
+  email?: string;
+  phone?: string;
+  firstName?: string;
+  lastName?: string;
+  /** From the URL rather than a cookie, which is why it is named here. */
+  twclid?: string;
+}
+/**
+ * Consent signals, in Google's own spelling.
+ *
+ * Google's is the most granular surface any of the five vendors exposes, so
+ * every other vendor receives a *collapse* of it. Carrying the finest
+ * resolution and reducing per vendor means a projection never claims more
+ * than the host declared — expanding a coarse answer into fine signals would
+ * invent information, and this library never does that.
+ *
+ * An absent signal produces no key: silence is not a denial, and converting
+ * it into one would put words in the visitor's mouth just as a grant would.
+ */
+interface ConsentState {
+  ad_storage?: "granted" | "denied";
+  analytics_storage?: "granted" | "denied";
+  ad_user_data?: "granted" | "denied";
+  ad_personalization?: "granted" | "denied";
+}
+/**
+ * Where a conversion happened.
+ *
+ * Meta's vocabulary, adopted verbatim — it is the only vendor of the five
+ * that documents the concept, and it requires the field on every server
+ * event. Inventing a taxonomy and translating it would be both incomplete
+ * for Meta and meaningless to everyone else.
+ */
+type ActionSource = "website" | "app" | "email" | "phone_call" | "chat" | "physical_store" | "system_generated" | "business_messaging" | "other";
+/**
+ * How a canonical event name is spelled for one vendor, or `null` to say
+ * "never send this event here".
+ */
+type EventBinding<Target> = Target | null;
+/** What a provider does with a canonical event it has no binding for. */
+type ProviderDefault = "passthrough" | "ignore";
+/**
+ * Reported out of band, never thrown at the call site.
+ *
+ * Fanning out to N vendors means no single call site can catch anything, so
+ * this is the replica of the `try/catch` a host would have written around a
+ * hand-made call. `severity` separates "this did not arrive" from "this
+ * arrived, and here is something you should know".
+ *
+ * It never carries event contents: the payload holds raw personal data by
+ * design, and no library-owned surface re-emits it into a host's logs.
+ */
+interface TrackingError {
+  provider: string;
+  event: string;
+  severity: "error" | "warning";
+  message: string;
+  cause?: unknown;
+}
+//#endregion
+export { EventItem as a, UserData as c, EventData as i, ConsentState as n, ProviderDefault as o, EventBinding as r, TrackingError as s, ActionSource as t };
+//# sourceMappingURL=vocabulary-ByyXHVWd.d.ts.map

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "tracklane",
+  "version": "0.1.0",
+  "description": "One interface between your application and every tool that receives events — GA4, Meta, LinkedIn, PostHog, X, browser and server.",
+  "keywords": [
+    "analytics",
+    "tracking",
+    "conversions-api",
+    "ga4",
+    "meta-pixel",
+    "posthog",
+    "linkedin",
+    "typescript",
+    "esm"
+  ],
+  "license": "MIT",
+  "author": "Bruno Bertolini <dev@brunobertolini.com>",
+  "homepage": "https://github.com/brunobertolini/tracklane#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brunobertolini/tracklane.git",
+    "directory": "packages/tracklane"
+  },
+  "bugs": "https://github.com/brunobertolini/tracklane/issues",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "package:check": "publint --strict && attw --pack . --profile esm-only"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/node": "catalog:",
+    "@vitest/coverage-v8": "4.1.10",
+    "publint": "0.3.22",
+    "tsdown": "0.22.14",
+    "typescript": "catalog:",
+    "vitest": "4.1.10"
+  }
+}