tracklane 0.4.0 → 0.5.0

package/dist/conformance.d.ts

@@ -0,0 +1,61 @@
+import { m as ServerProvider, p as ResolvedContext, t as BrowserProvider } from "./browser-CddkJdvX.js";
+//#region src/conformance.d.ts
+/**
+ * Runs the shared conformance suite against a browser provider.
+ *
+ * @param create - Builds the provider under test. Called per assertion, so a
+ * provider that accumulates state between runs fails rather than hides.
+ * @param captured - Everything the provider handed the vendor since the last
+ * reset, in order.
+ * @param reset - Clears what `captured` returns.
+ *
+ * @example
+ * ```ts
+ * describe('ga4 browser conformance', () => {
+ *   conformsAsBrowserProvider({
+ *     create: () => ga4('G-ABC'),
+ *     captured: () => calls,
+ *     reset: () => { calls = []; },
+ *   });
+ * });
+ * ```
+ */
+declare function conformsAsBrowserProvider(options: {
+  create: () => BrowserProvider;
+  captured: () => unknown[];
+  reset: () => void;
+}): void;
+/**
+ * Runs the shared conformance suite against a server provider.
+ *
+ * @param create - Builds the provider under test, per assertion.
+ * @param captured - Everything the provider sent since the last reset.
+ * @param reset - Clears what `captured` returns, and restores a successful
+ * transport.
+ * @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.
+ *
+ * @example
+ * ```ts
+ * describe('ga4 server conformance', () => {
+ *   conformsAsServerProvider({
+ *     create: () => ga4(credentials),
+ *     captured: () => fetchMock.mock.calls,
+ *     reset: () => { fetchMock.mockClear(); },
+ *     fail: () => { fetchMock.mockResolvedValueOnce(new Response(null, { status: 500 })); },
+ *     context,
+ *   });
+ * });
+ * ```
+ */
+declare function conformsAsServerProvider(options: {
+  create: () => ServerProvider;
+  captured: () => unknown[];
+  reset: () => void;
+  fail: () => void;
+  context: () => ResolvedContext;
+}): void;
+//#endregion
+export { conformsAsBrowserProvider, conformsAsServerProvider };
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.js

@@ -0,0 +1,153 @@
+import { expect, it } from "vitest";
+//#region src/conformance.ts
+/**
+* The behaviour every provider owes, which the types cannot express.
+*
+* ADR-0004 requires this suite because a provider can satisfy
+* {@link BrowserProvider} or {@link ServerProvider} perfectly and still break
+* a rule the whole library rests on. The interface cannot say "never invent an
+* identifier" or "never expand a consent signal"; a test can.
+*
+* These are invariants, not vendor behaviour. What GA4 sends and how it spells
+* it belongs in the GA4 tests. What follows must hold for a provider written
+* by anyone, for a vendor nobody here has heard of.
+*
+* **Published as `tracklane/conformance`**, because the claim that a provider
+* written elsewhere uses the same contract as the ones shipped here is only
+* true if it can run the same checks. `vitest` is an optional peer: import this
+* from a test file and call one of the two functions below inside a `describe`.
+*
+* **A wrapper owes the same invariants as a provider.** Wrapping a shipped
+* provider and delegating (see the provider documentation) produces an object
+* that the dispatcher cannot tell apart from any other, so run it through here
+* too. On the server half that catches the expensive mistake: a wrapper whose
+* `track` does not `await` the provider it delegates to resolves before the
+* request settles, which a serverless runtime turns into a conversion that
+* never left. {@link conformsAsServerProvider} fails on it, because a vendor
+* refusal can no longer reach the caller.
+*/
+const DEFAULTS = ["passthrough", "ignore"];
+/** A payload with nothing in it that could excuse a difference between runs. */
+const STABLE_DATA = {
+	transaction_id: "T-1",
+	value: 49.9,
+	currency: "BRL"
+};
+function assertIdentity(provider) {
+	it("names itself, once and stably", () => {
+		expect(provider.name).toBeTruthy();
+		expect(provider.name.trim()).toBe(provider.name);
+	});
+	it("declares what happens to an event it has no binding for", () => {
+		expect(DEFAULTS).toContain(provider.default);
+	});
+}
+/**
+* Runs the shared conformance suite against a browser provider.
+*
+* @param create - Builds the provider under test. Called per assertion, so a
+* provider that accumulates state between runs fails rather than hides.
+* @param captured - Everything the provider handed the vendor since the last
+* reset, in order.
+* @param reset - Clears what `captured` returns.
+*
+* @example
+* ```ts
+* describe('ga4 browser conformance', () => {
+*   conformsAsBrowserProvider({
+*     create: () => ga4('G-ABC'),
+*     captured: () => calls,
+*     reset: () => { calls = []; },
+*   });
+* });
+* ```
+*/
+function conformsAsBrowserProvider(options) {
+	const { create, captured, reset } = options;
+	assertIdentity(create());
+	it("sends the same thing twice for the same event", () => {
+		reset();
+		create().track("purchase", STABLE_DATA, {});
+		const first = JSON.stringify(captured());
+		reset();
+		create().track("purchase", 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, {});
+		const without = JSON.stringify(captured());
+		reset();
+		create().track("purchase", STABLE_DATA, { dedupId: "DEDUP-XYZ" });
+		const with_ = JSON.stringify(captured());
+		if (with_ !== without) expect(with_).toContain("DEDUP-XYZ");
+		expect(without).not.toContain("DEDUP-XYZ");
+	});
+	it("never expands a consent signal it was not given", () => {
+		const provider = create();
+		if (!provider.consent) return;
+		reset();
+		provider.consent("update", { analytics_storage: "denied" });
+		expect(JSON.stringify(captured())).not.toContain("granted");
+	});
+}
+/**
+* Runs the shared conformance suite against a server provider.
+*
+* @param create - Builds the provider under test, per assertion.
+* @param captured - Everything the provider sent since the last reset.
+* @param reset - Clears what `captured` returns, and restores a successful
+* transport.
+* @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.
+*
+* @example
+* ```ts
+* describe('ga4 server conformance', () => {
+*   conformsAsServerProvider({
+*     create: () => ga4(credentials),
+*     captured: () => fetchMock.mock.calls,
+*     reset: () => { fetchMock.mockClear(); },
+*     fail: () => { fetchMock.mockResolvedValueOnce(new Response(null, { status: 500 })); },
+*     context,
+*   });
+* });
+* ```
+*/
+function conformsAsServerProvider(options) {
+	const { create, captured, reset, fail, context } = options;
+	const noop = () => {};
+	assertIdentity(create());
+	it("sends the same thing twice for the same event", async () => {
+		reset();
+		await create().track("purchase", STABLE_DATA, context(), noop);
+		const first = JSON.stringify(captured());
+		reset();
+		await create().track("purchase", 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);
+		const without = JSON.stringify(captured());
+		reset();
+		await create().track("purchase", STABLE_DATA, {
+			...context(),
+			dedupId: "DEDUP-XYZ"
+		}, noop);
+		const with_ = JSON.stringify(captured());
+		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 () => {
+		reset();
+		fail();
+		await expect(create().track("purchase", STABLE_DATA, context(), noop)).rejects.toThrow();
+	});
+}
+//#endregion
+export { conformsAsBrowserProvider, conformsAsServerProvider };
+
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracklane",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One interface between your application and every tool that receives events, for the browser and server. GA4, Meta and PostHog today; LinkedIn and X next.",
   "keywords": [
     "analytics",
@@ -39,6 +39,10 @@
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
     },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "default": "./dist/conformance.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -60,6 +64,14 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.10"
   },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",