tracklane 0.5.0 → 0.7.0

package/dist/browser.js

@@ -1,397 +1,2 @@
-import { i as resolveEvent, n as makeReporter, r as messageOf, t as assertUniqueProviders } from "./dispatch-BLBoCn-b.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$1(...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$1("event", name, {
-				...data,
-				send_to: measurementId
-			});
-		},
-		identify(user, traits) {
-			if (user.userId !== void 0) push$1("set", { user_id: user.userId });
-			if (traits) push$1("set", "user_properties", traits);
-		},
-		consent(command, state) {
-			push$1("consent", command, state);
-		}
-	};
-}
-//#endregion
-//#region src/providers/meta.browser.ts
-/**
-* The names Meta accepts through `fbq('track')`. Anything else is a custom
-* event and goes through `trackCustom`, which is a different command rather
-* than a different argument.
-*
-* Seventeen standard events plus `PageView`, which Meta documents separately
-* from the seventeen and which the base snippet fires by itself.
-*/
-const STANDARD_EVENTS = [
-	"AddPaymentInfo",
-	"AddToCart",
-	"AddToWishlist",
-	"CompleteRegistration",
-	"Contact",
-	"CustomizeProduct",
-	"Donate",
-	"FindLocation",
-	"InitiateCheckout",
-	"Lead",
-	"PageView",
-	"Purchase",
-	"Schedule",
-	"Search",
-	"StartTrial",
-	"SubmitApplication",
-	"Subscribe",
-	"ViewContent"
-];
-/**
-* How Meta spells the canonical vocabulary, which is GA4's.
-*
-* Only canonical names appear here. Meta has eight more standard events with
-* no GA4 counterpart (`Subscribe`, `StartTrial`, `Schedule`, `Contact`,
-* `Donate`, `FindLocation`, `CustomizeProduct`, `SubmitApplication`), and
-* inventing canonical names for them would make this library the author of a
-* vocabulary it deliberately borrows. A host that fires those maps its own
-* event name to them through `events`.
-*
-* A canonical event with no standard counterpart is **not** dropped: it goes
-* to `trackCustom` under its own name, because by hand that event would have
-* been sent.
-*/
-const CANONICAL_EVENTS = {
-	page_view: "PageView",
-	view_item: "ViewContent",
-	search: "Search",
-	add_to_cart: "AddToCart",
-	add_to_wishlist: "AddToWishlist",
-	begin_checkout: "InitiateCheckout",
-	add_payment_info: "AddPaymentInfo",
-	purchase: "Purchase",
-	sign_up: "CompleteRegistration",
-	generate_lead: "Lead"
-};
-function fbqWindow() {
-	return typeof window === "undefined" ? void 0 : window;
-}
-/**
-* Sends a command, or fails the way a hand-written call would.
-*
-* Writing `fbq(…)` on a page without Meta'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 fbq = fbqWindow()?.fbq;
-	if (!fbq) throw new Error("meta: window.fbq is not defined. Add Meta's pixel to the page before creating tracking.");
-	fbq(...args);
-}
-/**
-* GA4's `items` become Meta's `contents`, which is a closed shape: `id`,
-* `quantity`, `item_price` and `delivery_category`, and nothing else.
-*
-* The rest of a GA4 item, `item_name` and `item_brand`, is dropped rather than
-* forwarded, because a key Meta does not read inside `contents` looks mapped
-* and arrives nowhere. That is the failure mode this project keeps finding.
-*/
-function contents(items) {
-	return items.map((item) => {
-		const content = {};
-		if (item.item_id !== void 0) content.id = item.item_id;
-		if (item.quantity !== void 0) content.quantity = item.quantity;
-		if (item.price !== void 0) content.item_price = item.price;
-		return content;
-	});
-}
-/**
-* `value` and `currency` are spelled identically by both vendors, so they
-* pass through untouched. Everything the host named itself passes through
-* too: Meta keeps unknown keys as custom properties, which is exactly what a
-* hand-written call would have produced.
-*
-* `transaction_id` stays under its own name here. Meta's pixel documents no
-* order id among its object properties. `order_id` exists on the Conversions
-* API and not on this surface, so translating it would be inventing a slot.
-*/
-function pixelParams(data) {
-	const { items, ...rest } = data;
-	const params = { ...rest };
-	if (items) params.contents = contents(items);
-	return params;
-}
-/**
-* Meta's pixel has one consent switch where this library carries Google's
-* four signals, so the four are collapsed into it.
-*
-* The collapse is the strictest declared answer: any `denied` produces
-* `revoke`, and `grant` needs every declared signal to be `granted`. There is
-* no field to partition, so this is the only reduction that cannot widen a
-* denial, and widening is the one thing a projection must never do.
-*
-* A host that wants Meta to follow only its advertising category, and not its
-* analytics one, decides that before `createTracking` by leaving this
-* provider out, which is what `@tracklane/consent` exists to do.
-*/
-function collapse(state) {
-	const signals = [
-		state.ad_storage,
-		state.analytics_storage,
-		state.ad_user_data,
-		state.ad_personalization
-	].filter((signal) => signal !== void 0);
-	if (signals.length === 0) return void 0;
-	return signals.every((signal) => signal === "granted") ? "grant" : "revoke";
-}
-/**
-* The Meta pixel in the browser, through `fbq`.
-*
-* **This provider does not load Meta's pixel.** The base code belongs on the
-* page, installed the way
-* [Meta documents it](https://developers.facebook.com/docs/meta-pixel/get-started):
-* a snippet in the HTML, or a tag manager. This library talks to the pixel
-* that is already there; it never injects a third-party script and never
-* issues `fbq('init')`.
-*
-* Three consequences follow from that, and all three are Meta's rules rather
-* than ours:
-*
-* - **There is no `identify` here.** Meta accepts advanced matching only in
-*   the base code ("be sure to place advanced matching parameters in the
-*   pixel base code or the values will not be treated as manual advanced
-*   matching values"), and the base code is yours. Put `em`, `ph`, `fn`, `ln`
-*   in your own `fbq('init')`, where the pixel normalises and hashes them for
-*   you. On the server, where there is no snippet, the same identity travels
-*   in `context.user` and is hashed by the adapter.
-* - **The initial consent declaration is not ours.** Meta wants
-*   `fbq('consent', 'revoke')` before `init`, and by the time you hold what
-*   `createTracking` returns that moment has passed. Ours is every
-*   declaration after it, through `consent()`.
-* - **Limited Data Use is not ours either.** `fbq('dataProcessingOptions', …)`
-*   is documented as running before `init`. It belongs in your snippet. The
-*   server half, which has no snippet, carries it on its factory.
-*
-* **There is no pixel id here**, and that is deliberate rather than an
-* omission. `fbq('track')` reaches every pixel the page initialised, so an id
-* passed in would address nothing and the parameter would promise something
-* this adapter cannot deliver. Which pixels exist is declared by your snippet,
-* in `fbq('init')`.
-*
-* @param config - Event name overrides, merged over the built-in map.
-* @returns A provider for `createTracking` from `tracklane/browser`.
-*
-* @example
-* ```ts
-* import { createTracking, meta } from 'tracklane/browser';
-*
-* // Meta's own base code is already in the page, and it named the pixel.
-* const { track } = createTracking({ providers: [meta()] });
-*
-* // fbq('track', 'Purchase', { value: 49.9, currency: 'BRL' }, { eventID: 'T-1' })
-* track('purchase', { value: 49.9, currency: 'BRL' }, { dedupId: 'T-1' });
-* ```
-*/
-function meta(config = {}) {
-	return {
-		name: "meta",
-		default: "passthrough",
-		events: {
-			...CANONICAL_EVENTS,
-			...config.events
-		},
-		track(name, data, options) {
-			const args = [
-				STANDARD_EVENTS.includes(name) ? "track" : "trackCustom",
-				name,
-				pixelParams(data)
-			];
-			if (options.dedupId !== void 0) args.push({ eventID: options.dedupId });
-			push(...args);
-		},
-		consent(_command, state) {
-			const answer = collapse(state);
-			if (answer) push("consent", answer);
-		}
-	};
-}
-//#endregion
-//#region src/providers/posthog.browser.ts
-function posthogWindow() {
-	return typeof window === "undefined" ? void 0 : window;
-}
-/**
-* Returns the vendor SDK, or fails the way a hand-written call would.
-*
-* Calling `posthog.capture(...)` on a page without PostHog'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 sdk() {
-	const instance = posthogWindow()?.posthog;
-	if (!instance) throw new Error("posthog: window.posthog is not defined. Add PostHog's snippet to the page before creating tracking.");
-	return instance;
-}
-/**
-* PostHog in the browser, through `posthog-js`.
-*
-* **This provider does not load PostHog's snippet.** It belongs on the page,
-* installed the way PostHog documents it: a snippet in the HTML, or a tag
-* manager. This library talks to the instance that is already there; it
-* never injects a third-party script into your page.
-*
-* @param config - Rarely needed event name overrides.
-* @returns A provider for `createTracking` from `tracklane/browser`.
-*
-* @example
-* ```ts
-* import { createTracking, posthog } from 'tracklane/browser';
-*
-* // PostHog's own snippet is already in the page.
-* const { track } = createTracking({ providers: [posthog()] });
-*
-* track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
-* ```
-*/
-function posthog(config = {}) {
-	const { events } = config;
-	return {
-		name: "posthog",
-		default: "passthrough",
-		...events ? { events } : {},
-		track(name, data, _options) {
-			sdk().capture(name, data);
-		},
-		identify(user, traits) {
-			if (user.userId !== void 0) sdk().identify(user.userId);
-			if (traits) sdk().setPersonProperties(traits);
-		},
-		consent(_command, state) {
-			const { analytics_storage } = state;
-			if (analytics_storage === "denied") sdk().opt_out_capturing();
-			else if (analytics_storage === "granted") sdk().opt_in_capturing();
-		}
-	};
-}
-//#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, meta, posthog };
-
-//# sourceMappingURL=browser.js.map
+import { a as ga4, i as linkedin, n as posthog, r as meta, t as createTracking } from "./browser-DhzO5qPS.js";
+export { createTracking, ga4, linkedin, meta, posthog };

package/dist/conformance.d.ts

@@ -1,4 +1,4 @@
-import { m as ServerProvider, p as ResolvedContext, t as BrowserProvider } from "./browser-CddkJdvX.js";
+import { g as ServerProvider, h as ResolvedContext, t as BrowserProvider } from "./browser-34-CHcxK.js";
 //#region src/conformance.d.ts
 /**
  * Runs the shared conformance suite against a browser provider.
@@ -8,6 +8,7 @@ import { m as ServerProvider, p as ResolvedContext, t as BrowserProvider } from
  * @param captured - Everything the provider handed the vendor since the last
  * reset, in order.
  * @param reset - Clears what `captured` returns.
+ * @param target - An already-resolved vendor target. Defaults to `purchase`.
  *
  * @example
  * ```ts
@@ -24,6 +25,8 @@ declare function conformsAsBrowserProvider(options: {
   create: () => BrowserProvider;
   captured: () => unknown[];
   reset: () => void;
+  /** Already-resolved vendor target; conversion-ID providers use their configured ID. */
+  target?: string;
 }): void;
 /**
  * Runs the shared conformance suite against a server provider.
@@ -35,6 +38,7 @@ declare function conformsAsBrowserProvider(options: {
  * @param fail - Makes the next send fail at the transport, so the suite can
  * check that the provider is loud about it.
  * @param context - A resolved context with a fixed timestamp.
+ * @param target - An already-resolved vendor target. Defaults to `purchase`.
  *
  * @example
  * ```ts
@@ -55,6 +59,8 @@ declare function conformsAsServerProvider(options: {
   reset: () => void;
   fail: () => void;
   context: () => ResolvedContext;
+  /** Already-resolved vendor target; conversion-ID providers use their configured ID. */
+  target?: string;
 }): void;
 //#endregion
 export { conformsAsBrowserProvider, conformsAsServerProvider };

package/dist/conformance.js

@@ -1,3 +1,6 @@
+import { n as isVendorResponseError } from "./src-DLRGPWMj.js";
+import { t as createTracking } from "./browser-DhzO5qPS.js";
+import { t as createTracking$1 } from "./server-DnP7RtEn.js";
 import { expect, it } from "vitest";
 //#region src/conformance.ts
 /**
@@ -50,6 +53,7 @@ function assertIdentity(provider) {
 * @param captured - Everything the provider handed the vendor since the last
 * reset, in order.
 * @param reset - Clears what `captured` returns.
+* @param target - An already-resolved vendor target. Defaults to `purchase`.
 *
 * @example
 * ```ts
@@ -64,22 +68,43 @@ function assertIdentity(provider) {
 */
 function conformsAsBrowserProvider(options) {
 	const { create, captured, reset } = options;
+	const target = options.target ?? "purchase";
 	assertIdentity(create());
+	it("reports absent mappings on ignore providers and keeps explicit exclusions silent", () => {
+		const { install: _install, ...provider } = create();
+		if (provider.default !== "ignore") return;
+		reset();
+		const errors = [];
+		const tracking = createTracking({
+			providers: [{
+				...provider,
+				events: { explicit: null }
+			}],
+			onError: (error) => errors.push(error)
+		});
+		tracking.track("missing");
+		tracking.track("explicit");
+		expect(errors).toMatchObject([{
+			severity: "warning",
+			event: "missing"
+		}]);
+		expect(captured()).toEqual([]);
+	});
 	it("sends the same thing twice for the same event", () => {
 		reset();
-		create().track("purchase", STABLE_DATA, {});
+		create().track(target, STABLE_DATA, {});
 		const first = JSON.stringify(captured());
 		reset();
-		create().track("purchase", STABLE_DATA, {});
+		create().track(target, STABLE_DATA, {});
 		const second = JSON.stringify(captured());
 		expect(second).toBe(first);
 	});
 	it("forwards the deduplication id only when it was given one", () => {
 		reset();
-		create().track("purchase", STABLE_DATA, {});
+		create().track(target, STABLE_DATA, {});
 		const without = JSON.stringify(captured());
 		reset();
-		create().track("purchase", STABLE_DATA, { dedupId: "DEDUP-XYZ" });
+		create().track(target, STABLE_DATA, { dedupId: "DEDUP-XYZ" });
 		const with_ = JSON.stringify(captured());
 		if (with_ !== without) expect(with_).toContain("DEDUP-XYZ");
 		expect(without).not.toContain("DEDUP-XYZ");
@@ -102,6 +127,7 @@ function conformsAsBrowserProvider(options) {
 * @param fail - Makes the next send fail at the transport, so the suite can
 * check that the provider is loud about it.
 * @param context - A resolved context with a fixed timestamp.
+* @param target - An already-resolved vendor target. Defaults to `purchase`.
 *
 * @example
 * ```ts
@@ -118,22 +144,43 @@ function conformsAsBrowserProvider(options) {
 */
 function conformsAsServerProvider(options) {
 	const { create, captured, reset, fail, context } = options;
+	const target = options.target ?? "purchase";
 	const noop = () => {};
 	assertIdentity(create());
+	it("reports absent mappings on ignore providers and keeps explicit exclusions silent", async () => {
+		const provider = create();
+		if (provider.default !== "ignore") return;
+		reset();
+		const errors = [];
+		const tracking = createTracking$1({
+			providers: [{
+				...provider,
+				events: { explicit: null }
+			}],
+			onError: (error) => errors.push(error)
+		});
+		await tracking.track("missing", {}, context());
+		await tracking.track("explicit", {}, context());
+		expect(errors).toMatchObject([{
+			severity: "warning",
+			event: "missing"
+		}]);
+		expect(captured()).toEqual([]);
+	});
 	it("sends the same thing twice for the same event", async () => {
 		reset();
-		await create().track("purchase", STABLE_DATA, context(), noop);
+		await create().track(target, STABLE_DATA, context(), noop);
 		const first = JSON.stringify(captured());
 		reset();
-		await create().track("purchase", STABLE_DATA, context(), noop);
+		await create().track(target, STABLE_DATA, context(), noop);
 		expect(JSON.stringify(captured())).toBe(first);
 	});
 	it("forwards the deduplication id only when it was given one", async () => {
 		reset();
-		await create().track("purchase", STABLE_DATA, context(), noop);
+		await create().track(target, STABLE_DATA, context(), noop);
 		const without = JSON.stringify(captured());
 		reset();
-		await create().track("purchase", STABLE_DATA, {
+		await create().track(target, STABLE_DATA, {
 			...context(),
 			dedupId: "DEDUP-XYZ"
 		}, noop);
@@ -141,10 +188,20 @@ function conformsAsServerProvider(options) {
 		if (with_ !== without) expect(with_).toContain("DEDUP-XYZ");
 		expect(without).not.toContain("DEDUP-XYZ");
 	});
-	it("throws when the vendor did not accept the send", async () => {
+	it("throws a VendorResponseError when the vendor did not accept the send", async () => {
 		reset();
 		fail();
-		await expect(create().track("purchase", STABLE_DATA, context(), noop)).rejects.toThrow();
+		let caught;
+		try {
+			await create().track(target, STABLE_DATA, context(), noop);
+		} catch (error) {
+			caught = error;
+		}
+		expect(isVendorResponseError(caught)).toBe(true);
+		if (isVendorResponseError(caught)) {
+			expect(typeof caught.status).toBe("number");
+			expect(typeof caught.body).toBe("string");
+		}
 	});
 }
 //#endregion

package/dist/conformance.js.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.js","names":[],"sources":["../src/conformance.ts"],"sourcesContent":["import { expect, it } from 'vitest';\nimport type { BrowserProvider } from './browser.js';\nimport type { ResolvedContext, ServerProvider } from './server.js';\nimport type { EventData, ProviderDefault } from './vocabulary.js';\n\n/**\n * The behaviour every provider owes, which the types cannot express.\n *\n * ADR-0004 requires this suite because a provider can satisfy\n * {@link BrowserProvider} or {@link ServerProvider} perfectly and still break\n * a rule the whole library rests on. The interface cannot say \"never invent an\n * identifier\" or \"never expand a consent signal\"; a test can.\n *\n * These are invariants, not vendor behaviour. What GA4 sends and how it spells\n * it belongs in the GA4 tests. What follows must hold for a provider written\n * by anyone, for a vendor nobody here has heard of.\n *\n * **Published as `tracklane/conformance`**, because the claim that a provider\n * written elsewhere uses the same contract as the ones shipped here is only\n * true if it can run the same checks. `vitest` is an optional peer: import this\n * from a test file and call one of the two functions below inside a `describe`.\n *\n * **A wrapper owes the same invariants as a provider.** Wrapping a shipped\n * provider and delegating (see the provider documentation) produces an object\n * that the dispatcher cannot tell apart from any other, so run it through here\n * too. On the server half that catches the expensive mistake: a wrapper whose\n * `track` does not `await` the provider it delegates to resolves before the\n * request settles, which a serverless runtime turns into a conversion that\n * never left. {@link conformsAsServerProvider} fails on it, because a vendor\n * refusal can no longer reach the caller.\n */\n\nconst DEFAULTS: ProviderDefault[] = ['passthrough', 'ignore'];\n\n/** A payload with nothing in it that could excuse a difference between runs. */\nconst STABLE_DATA: EventData = { transaction_id: 'T-1', value: 49.9, currency: 'BRL' };\n\nfunction assertIdentity(provider: { name: string; default: ProviderDefault }): void {\n  it('names itself, once and stably', () => {\n    // The name is what a duplicate registration is detected by, and what an\n    // error report is attributed to.\n    expect(provider.name).toBeTruthy();\n    expect(provider.name.trim()).toBe(provider.name);\n  });\n\n  it('declares what happens to an event it has no binding for', () => {\n    expect(DEFAULTS).toContain(provider.default);\n  });\n}\n\n/**\n * Runs the shared conformance suite against a browser provider.\n *\n * @param create - Builds the provider under test. Called per assertion, so a\n * provider that accumulates state between runs fails rather than hides.\n * @param captured - Everything the provider handed the vendor since the last\n * reset, in order.\n * @param reset - Clears what `captured` returns.\n *\n * @example\n * ```ts\n * describe('ga4 browser conformance', () => {\n *   conformsAsBrowserProvider({\n *     create: () => ga4('G-ABC'),\n *     captured: () => calls,\n *     reset: () => { calls = []; },\n *   });\n * });\n * ```\n */\nexport function conformsAsBrowserProvider(options: {\n  create: () => BrowserProvider;\n  captured: () => unknown[];\n  reset: () => void;\n}): void {\n  const { create, captured, reset } = options;\n\n  assertIdentity(create());\n\n  it('sends the same thing twice for the same event', () => {\n    // The library never invents an identifier, and this is how that rule is\n    // caught rather than trusted: a generated id, a random value or a clock\n    // read makes two identical calls differ.\n    reset();\n    create().track('purchase', STABLE_DATA, {});\n    const first = JSON.stringify(captured());\n\n    reset();\n    create().track('purchase', STABLE_DATA, {});\n    const second = JSON.stringify(captured());\n\n    expect(second).toBe(first);\n  });\n\n  it('forwards the deduplication id only when it was given one', () => {\n    reset();\n    create().track('purchase', STABLE_DATA, {});\n    const without = JSON.stringify(captured());\n\n    reset();\n    create().track('purchase', STABLE_DATA, { dedupId: 'DEDUP-XYZ' });\n    const with_ = JSON.stringify(captured());\n\n    // Either the vendor has the concept, and the value appears where it did\n    // not before, or it has none and nothing changes. Inventing one to fill\n    // the slot is the failure this catches.\n    if (with_ !== without) expect(with_).toContain('DEDUP-XYZ');\n    expect(without).not.toContain('DEDUP-XYZ');\n  });\n\n  it('never expands a consent signal it was not given', () => {\n    const provider = create();\n    if (!provider.consent) return;\n\n    reset();\n    provider.consent('update', { analytics_storage: 'denied' });\n\n    // One denial in must never become a grant out. Collapsing Google's\n    // vocabulary for a coarser vendor is translation; widening it invents a\n    // permission the visitor never gave.\n    expect(JSON.stringify(captured())).not.toContain('granted');\n  });\n}\n\n/**\n * Runs the shared conformance suite against a server provider.\n *\n * @param create - Builds the provider under test, per assertion.\n * @param captured - Everything the provider sent since the last reset.\n * @param reset - Clears what `captured` returns, and restores a successful\n * transport.\n * @param fail - Makes the next send fail at the transport, so the suite can\n * check that the provider is loud about it.\n * @param context - A resolved context with a fixed timestamp.\n *\n * @example\n * ```ts\n * describe('ga4 server conformance', () => {\n *   conformsAsServerProvider({\n *     create: () => ga4(credentials),\n *     captured: () => fetchMock.mock.calls,\n *     reset: () => { fetchMock.mockClear(); },\n *     fail: () => { fetchMock.mockResolvedValueOnce(new Response(null, { status: 500 })); },\n *     context,\n *   });\n * });\n * ```\n */\nexport function conformsAsServerProvider(options: {\n  create: () => ServerProvider;\n  captured: () => unknown[];\n  reset: () => void;\n  fail: () => void;\n  context: () => ResolvedContext;\n}): void {\n  const { create, captured, reset, fail, context } = options;\n  const noop = (): void => {};\n\n  assertIdentity(create());\n\n  it('sends the same thing twice for the same event', async () => {\n    // The context carries a fixed timestamp, so any difference between these\n    // two is something the provider produced on its own.\n    reset();\n    await create().track('purchase', STABLE_DATA, context(), noop);\n    const first = JSON.stringify(captured());\n\n    reset();\n    await create().track('purchase', STABLE_DATA, context(), noop);\n\n    expect(JSON.stringify(captured())).toBe(first);\n  });\n\n  it('forwards the deduplication id only when it was given one', async () => {\n    reset();\n    await create().track('purchase', STABLE_DATA, context(), noop);\n    const without = JSON.stringify(captured());\n\n    reset();\n    await create().track('purchase', STABLE_DATA, { ...context(), dedupId: 'DEDUP-XYZ' }, noop);\n    const with_ = JSON.stringify(captured());\n\n    if (with_ !== without) expect(with_).toContain('DEDUP-XYZ');\n    expect(without).not.toContain('DEDUP-XYZ');\n  });\n\n  it('throws when the vendor did not accept the send', async () => {\n    // Adapters stay honest and loud. Swallowing a non-2xx is how a host ends\n    // up believing it is measuring something, and the dispatcher is already\n    // there to isolate the throw and report it.\n    reset();\n    fail();\n\n    await expect(create().track('purchase', STABLE_DATA, context(), noop)).rejects.toThrow();\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"conformance.js","names":["createBrowserTracking","createServerTracking"],"sources":["../src/conformance.ts"],"sourcesContent":["import { expect, it } from 'vitest';\nimport { type BrowserProvider, createTracking as createBrowserTracking } from './browser.js';\nimport { isVendorResponseError } from './errors.js';\nimport {\n  createTracking as createServerTracking,\n  type ResolvedContext,\n  type ServerProvider,\n} from './server.js';\nimport type { EventData, ProviderDefault } from './vocabulary.js';\n\n/**\n * The behaviour every provider owes, which the types cannot express.\n *\n * ADR-0004 requires this suite because a provider can satisfy\n * {@link BrowserProvider} or {@link ServerProvider} perfectly and still break\n * a rule the whole library rests on. The interface cannot say \"never invent an\n * identifier\" or \"never expand a consent signal\"; a test can.\n *\n * These are invariants, not vendor behaviour. What GA4 sends and how it spells\n * it belongs in the GA4 tests. What follows must hold for a provider written\n * by anyone, for a vendor nobody here has heard of.\n *\n * **Published as `tracklane/conformance`**, because the claim that a provider\n * written elsewhere uses the same contract as the ones shipped here is only\n * true if it can run the same checks. `vitest` is an optional peer: import this\n * from a test file and call one of the two functions below inside a `describe`.\n *\n * **A wrapper owes the same invariants as a provider.** Wrapping a shipped\n * provider and delegating (see the provider documentation) produces an object\n * that the dispatcher cannot tell apart from any other, so run it through here\n * too. On the server half that catches the expensive mistake: a wrapper whose\n * `track` does not `await` the provider it delegates to resolves before the\n * request settles, which a serverless runtime turns into a conversion that\n * never left. {@link conformsAsServerProvider} fails on it, because a vendor\n * refusal can no longer reach the caller.\n */\n\nconst DEFAULTS: ProviderDefault[] = ['passthrough', 'ignore'];\n\n/** A payload with nothing in it that could excuse a difference between runs. */\nconst STABLE_DATA: EventData = { transaction_id: 'T-1', value: 49.9, currency: 'BRL' };\n\nfunction assertIdentity(provider: { name: string; default: ProviderDefault }): void {\n  it('names itself, once and stably', () => {\n    // The name is what a duplicate registration is detected by, and what an\n    // error report is attributed to.\n    expect(provider.name).toBeTruthy();\n    expect(provider.name.trim()).toBe(provider.name);\n  });\n\n  it('declares what happens to an event it has no binding for', () => {\n    expect(DEFAULTS).toContain(provider.default);\n  });\n}\n\n/**\n * Runs the shared conformance suite against a browser provider.\n *\n * @param create - Builds the provider under test. Called per assertion, so a\n * provider that accumulates state between runs fails rather than hides.\n * @param captured - Everything the provider handed the vendor since the last\n * reset, in order.\n * @param reset - Clears what `captured` returns.\n * @param target - An already-resolved vendor target. Defaults to `purchase`.\n *\n * @example\n * ```ts\n * describe('ga4 browser conformance', () => {\n *   conformsAsBrowserProvider({\n *     create: () => ga4('G-ABC'),\n *     captured: () => calls,\n *     reset: () => { calls = []; },\n *   });\n * });\n * ```\n */\nexport function conformsAsBrowserProvider(options: {\n  create: () => BrowserProvider;\n  captured: () => unknown[];\n  reset: () => void;\n  /** Already-resolved vendor target; conversion-ID providers use their configured ID. */\n  target?: string;\n}): void {\n  const { create, captured, reset } = options;\n  const target = options.target ?? 'purchase';\n\n  assertIdentity(create());\n\n  it('reports absent mappings on ignore providers and keeps explicit exclusions silent', () => {\n    // Mapping assertions do not exercise the host's installation hook.\n    const { install: _install, ...provider } = create();\n    if (provider.default !== 'ignore') return;\n    reset();\n    const errors: { severity: string; event: string }[] = [];\n    const tracking = createBrowserTracking({\n      providers: [{ ...provider, events: { explicit: null } }],\n      onError: (error) => errors.push(error),\n    });\n    tracking.track('missing');\n    tracking.track('explicit');\n    expect(errors).toMatchObject([{ severity: 'warning', event: 'missing' }]);\n    expect(captured()).toEqual([]);\n  });\n\n  it('sends the same thing twice for the same event', () => {\n    // The library never invents an identifier, and this is how that rule is\n    // caught rather than trusted: a generated id, a random value or a clock\n    // read makes two identical calls differ.\n    reset();\n    create().track(target, STABLE_DATA, {});\n    const first = JSON.stringify(captured());\n\n    reset();\n    create().track(target, STABLE_DATA, {});\n    const second = JSON.stringify(captured());\n\n    expect(second).toBe(first);\n  });\n\n  it('forwards the deduplication id only when it was given one', () => {\n    reset();\n    create().track(target, STABLE_DATA, {});\n    const without = JSON.stringify(captured());\n\n    reset();\n    create().track(target, STABLE_DATA, { dedupId: 'DEDUP-XYZ' });\n    const with_ = JSON.stringify(captured());\n\n    // Either the vendor has the concept, and the value appears where it did\n    // not before, or it has none and nothing changes. Inventing one to fill\n    // the slot is the failure this catches.\n    if (with_ !== without) expect(with_).toContain('DEDUP-XYZ');\n    expect(without).not.toContain('DEDUP-XYZ');\n  });\n\n  it('never expands a consent signal it was not given', () => {\n    const provider = create();\n    if (!provider.consent) return;\n\n    reset();\n    provider.consent('update', { analytics_storage: 'denied' });\n\n    // One denial in must never become a grant out. Collapsing Google's\n    // vocabulary for a coarser vendor is translation; widening it invents a\n    // permission the visitor never gave.\n    expect(JSON.stringify(captured())).not.toContain('granted');\n  });\n}\n\n/**\n * Runs the shared conformance suite against a server provider.\n *\n * @param create - Builds the provider under test, per assertion.\n * @param captured - Everything the provider sent since the last reset.\n * @param reset - Clears what `captured` returns, and restores a successful\n * transport.\n * @param fail - Makes the next send fail at the transport, so the suite can\n * check that the provider is loud about it.\n * @param context - A resolved context with a fixed timestamp.\n * @param target - An already-resolved vendor target. Defaults to `purchase`.\n *\n * @example\n * ```ts\n * describe('ga4 server conformance', () => {\n *   conformsAsServerProvider({\n *     create: () => ga4(credentials),\n *     captured: () => fetchMock.mock.calls,\n *     reset: () => { fetchMock.mockClear(); },\n *     fail: () => { fetchMock.mockResolvedValueOnce(new Response(null, { status: 500 })); },\n *     context,\n *   });\n * });\n * ```\n */\nexport function conformsAsServerProvider(options: {\n  create: () => ServerProvider;\n  captured: () => unknown[];\n  reset: () => void;\n  fail: () => void;\n  context: () => ResolvedContext;\n  /** Already-resolved vendor target; conversion-ID providers use their configured ID. */\n  target?: string;\n}): void {\n  const { create, captured, reset, fail, context } = options;\n  const target = options.target ?? 'purchase';\n  const noop = (): void => {};\n\n  assertIdentity(create());\n\n  it('reports absent mappings on ignore providers and keeps explicit exclusions silent', async () => {\n    const provider = create();\n    if (provider.default !== 'ignore') return;\n    reset();\n    const errors: { severity: string; event: string }[] = [];\n    const tracking = createServerTracking({\n      providers: [{ ...provider, events: { explicit: null } }],\n      onError: (error) => errors.push(error),\n    });\n    await tracking.track('missing', {}, context());\n    await tracking.track('explicit', {}, context());\n    expect(errors).toMatchObject([{ severity: 'warning', event: 'missing' }]);\n    expect(captured()).toEqual([]);\n  });\n\n  it('sends the same thing twice for the same event', async () => {\n    // The context carries a fixed timestamp, so any difference between these\n    // two is something the provider produced on its own.\n    reset();\n    await create().track(target, STABLE_DATA, context(), noop);\n    const first = JSON.stringify(captured());\n\n    reset();\n    await create().track(target, STABLE_DATA, context(), noop);\n\n    expect(JSON.stringify(captured())).toBe(first);\n  });\n\n  it('forwards the deduplication id only when it was given one', async () => {\n    reset();\n    await create().track(target, STABLE_DATA, context(), noop);\n    const without = JSON.stringify(captured());\n\n    reset();\n    await create().track(target, STABLE_DATA, { ...context(), dedupId: 'DEDUP-XYZ' }, noop);\n    const with_ = JSON.stringify(captured());\n\n    if (with_ !== without) expect(with_).toContain('DEDUP-XYZ');\n    expect(without).not.toContain('DEDUP-XYZ');\n  });\n\n  it('throws a VendorResponseError when the vendor did not accept the send', async () => {\n    // Adapters stay honest and loud. Swallowing a non-2xx is how a host ends\n    // up believing it is measuring something, and the dispatcher is already\n    // there to isolate the throw and report it. ADR-0013 adds the shape: what\n    // reaches the host is recognised by `isVendorResponseError`, carrying the\n    // status and the body, not just any throw. The body itself is\n    // the caller's `fail()` hook to produce; a bodiless response is valid\n    // (the documented example does exactly that), so it is not asserted here.\n    reset();\n    fail();\n\n    let caught: unknown;\n    try {\n      await create().track(target, STABLE_DATA, context(), noop);\n    } catch (error) {\n      caught = error;\n    }\n\n    expect(isVendorResponseError(caught)).toBe(true);\n    if (isVendorResponseError(caught)) {\n      expect(typeof caught.status).toBe('number');\n      expect(typeof caught.body).toBe('string');\n    }\n  });\n}\n"],"mappings":"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"}

package/dist/{dispatch-BLBoCn-b.js → dispatch-B32jGhlh.js}

@@ -21,12 +21,15 @@ function assertUniqueProviders(providers) {
 * event identity is minted per account in its own dashboard, so there is no
 * name that could possibly be guessed.
 */
-function resolveEvent(provider, name) {
+function resolveEvent(provider, name, report) {
 	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;
+	if (provider.default === "ignore") {
+		report?.("event omitted: no conversion mapping; add a binding or null for an explicit exclusion");
+		return;
+	}
 	return name;
 }
 /**
@@ -48,4 +51,4 @@ function messageOf(cause) {
 //#endregion
 export { resolveEvent as i, makeReporter as n, messageOf as r, assertUniqueProviders as t };
 
-//# sourceMappingURL=dispatch-BLBoCn-b.js.map
+//# sourceMappingURL=dispatch-B32jGhlh.js.map

package/dist/dispatch-B32jGhlh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-B32jGhlh.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  report?: (message: string) => void,\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') {\n    report?.(\n      'event omitted: no conversion mapping; add a binding or null for an explicit exclusion',\n    );\n    return undefined;\n  }\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,MACA,QACoB;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;EACjC,SACE,uFACF;EACA;CACF;CAEA,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"}