tracklane 0.1.1 → 0.2.0

package/dist/browser.js

@@ -10,7 +10,7 @@ function gtagWindow() {
 * 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) {
+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);
@@ -51,17 +51,215 @@ function ga4(measurementId, config = {}) {
 		default: "passthrough",
 		...events ? { events } : {},
 		track(name, data, _options) {
-			push("event", name, {
+			push$1("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);
+			if (user.userId !== void 0) push$1("set", { user_id: user.userId });
+			if (traits) push$1("set", "user_properties", traits);
 		},
 		consent(command, state) {
-			push("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);
 		}
 	};
 }
@@ -136,6 +334,6 @@ function createTracking(options) {
 	};
 }
 //#endregion
-export { createTracking, ga4 };
+export { createTracking, ga4, meta };
 
 //# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -1 +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. A provider written outside this package\n * implements it exactly as the providers shipped here do.\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  /** Sends one event to this vendor. Throwing here reaches `onError`, not the caller. */\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  /** The vendors to send every event to. Registering the same `name` twice throws. */\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;;;;;;;;;;;;;;;;;;;;;;ACTA,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"}
+{"version":3,"file":"browser.js","names":["push"],"sources":["../src/providers/ga4.browser.ts","../src/providers/meta.browser.ts","../src/browser.ts"],"sourcesContent":["// Through the public entry point, exactly as a provider written elsewhere\n// would import it. A provider that needs something not exported here is\n// telling us the contract is incomplete, which is a conversation rather than\n// a reason to reach inside.\nimport type {\n  BrowserProvider,\n  ConsentState,\n  EventBinding,\n  EventData,\n  TrackOptions,\n  UserData,\n} from '../index.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","// Through the public entry point, exactly as a provider written elsewhere\n// would import it. A provider that needs something not exported here is\n// telling us the contract is incomplete, which is a conversation rather than\n// a reason to reach inside.\nimport type {\n  BrowserProvider,\n  ConsentState,\n  EventBinding,\n  EventData,\n  EventItem,\n  TrackOptions,\n} from '../index.js';\n\ninterface FbqWindow {\n  fbq?: (...args: unknown[]) => void;\n}\n\n/**\n * The names Meta accepts through `fbq('track')`. Anything else is a custom\n * event and goes through `trackCustom`, which is a different command rather\n * than a different argument.\n *\n * Seventeen standard events plus `PageView`, which Meta documents separately\n * from the seventeen and which the base snippet fires by itself.\n */\nconst STANDARD_EVENTS: readonly string[] = [\n  'AddPaymentInfo',\n  'AddToCart',\n  'AddToWishlist',\n  'CompleteRegistration',\n  'Contact',\n  'CustomizeProduct',\n  'Donate',\n  'FindLocation',\n  'InitiateCheckout',\n  'Lead',\n  'PageView',\n  'Purchase',\n  'Schedule',\n  'Search',\n  'StartTrial',\n  'SubmitApplication',\n  'Subscribe',\n  'ViewContent',\n];\n\n/**\n * How Meta spells the canonical vocabulary, which is GA4's.\n *\n * Only canonical names appear here. Meta has eight more standard events with\n * no GA4 counterpart (`Subscribe`, `StartTrial`, `Schedule`, `Contact`,\n * `Donate`, `FindLocation`, `CustomizeProduct`, `SubmitApplication`), and\n * inventing canonical names for them would make this library the author of a\n * vocabulary it deliberately borrows. A host that fires those maps its own\n * event name to them through `events`.\n *\n * A canonical event with no standard counterpart is **not** dropped: it goes\n * to `trackCustom` under its own name, because by hand that event would have\n * been sent.\n */\nconst CANONICAL_EVENTS: Record<string, EventBinding<string>> = {\n  page_view: 'PageView',\n  view_item: 'ViewContent',\n  search: 'Search',\n  add_to_cart: 'AddToCart',\n  add_to_wishlist: 'AddToWishlist',\n  begin_checkout: 'InitiateCheckout',\n  add_payment_info: 'AddPaymentInfo',\n  purchase: 'Purchase',\n  sign_up: 'CompleteRegistration',\n  generate_lead: 'Lead',\n};\n\n/** Optional configuration for the Meta browser provider. */\nexport interface MetaBrowserConfig {\n  /**\n   * How this pixel spells each canonical event, merged over the built-in map.\n   *\n   * This is how the eight standard events with no GA4 counterpart are\n   * reached, and how an event is kept out of Meta entirely with `null`.\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 fbqWindow(): FbqWindow | undefined {\n  return typeof window === 'undefined' ? undefined : (window as unknown as FbqWindow);\n}\n\n/**\n * Sends a command, or fails the way a hand-written call would.\n *\n * Writing `fbq(…)` on a page without Meta's snippet throws, and this library\n * replicates that rather than swallowing it: a silent no-op is how a host\n * ends up believing it is measuring something.\n */\nfunction push(...args: unknown[]): void {\n  const fbq = fbqWindow()?.fbq;\n\n  if (!fbq) {\n    throw new Error(\n      \"meta: window.fbq is not defined. Add Meta's pixel to the page before creating tracking.\",\n    );\n  }\n\n  fbq(...args);\n}\n\n/**\n * GA4's `items` become Meta's `contents`, which is a closed shape: `id`,\n * `quantity`, `item_price` and `delivery_category`, and nothing else.\n *\n * The rest of a GA4 item, `item_name` and `item_brand`, is dropped rather than\n * forwarded, because a key Meta does not read inside `contents` looks mapped\n * and arrives nowhere. That is the failure mode this project keeps finding.\n */\nfunction contents(items: readonly EventItem[]): Record<string, unknown>[] {\n  return items.map((item) => {\n    const content: Record<string, unknown> = {};\n\n    if (item.item_id !== undefined) content.id = item.item_id;\n    if (item.quantity !== undefined) content.quantity = item.quantity;\n    if (item.price !== undefined) content.item_price = item.price;\n\n    return content;\n  });\n}\n\n/**\n * `value` and `currency` are spelled identically by both vendors, so they\n * pass through untouched. Everything the host named itself passes through\n * too: Meta keeps unknown keys as custom properties, which is exactly what a\n * hand-written call would have produced.\n *\n * `transaction_id` stays under its own name here. Meta's pixel documents no\n * order id among its object properties. `order_id` exists on the Conversions\n * API and not on this surface, so translating it would be inventing a slot.\n */\nfunction pixelParams(data: EventData): Record<string, unknown> {\n  const { items, ...rest } = data;\n  const params: Record<string, unknown> = { ...rest };\n\n  if (items) params.contents = contents(items);\n\n  return params;\n}\n\n/**\n * Meta's pixel has one consent switch where this library carries Google's\n * four signals, so the four are collapsed into it.\n *\n * The collapse is the strictest declared answer: any `denied` produces\n * `revoke`, and `grant` needs every declared signal to be `granted`. There is\n * no field to partition, so this is the only reduction that cannot widen a\n * denial, and widening is the one thing a projection must never do.\n *\n * A host that wants Meta to follow only its advertising category, and not its\n * analytics one, decides that before `createTracking` by leaving this\n * provider out, which is what `@tracklane/consent` exists to do.\n */\nfunction collapse(state: ConsentState): 'grant' | 'revoke' | undefined {\n  const signals = [\n    state.ad_storage,\n    state.analytics_storage,\n    state.ad_user_data,\n    state.ad_personalization,\n  ].filter((signal) => signal !== undefined);\n\n  // Nothing declared produces no command. Reading silence as either answer\n  // puts words in the visitor's mouth.\n  if (signals.length === 0) return undefined;\n\n  return signals.every((signal) => signal === 'granted') ? 'grant' : 'revoke';\n}\n\n/**\n * The Meta pixel in the browser, through `fbq`.\n *\n * **This provider does not load Meta's pixel.** The base code belongs on the\n * page, installed the way\n * [Meta documents it](https://developers.facebook.com/docs/meta-pixel/get-started):\n * a snippet in the HTML, or a tag manager. This library talks to the pixel\n * that is already there; it never injects a third-party script and never\n * issues `fbq('init')`.\n *\n * Three consequences follow from that, and all three are Meta's rules rather\n * than ours:\n *\n * - **There is no `identify` here.** Meta accepts advanced matching only in\n *   the base code (\"be sure to place advanced matching parameters in the\n *   pixel base code or the values will not be treated as manual advanced\n *   matching values\"), and the base code is yours. Put `em`, `ph`, `fn`, `ln`\n *   in your own `fbq('init')`, where the pixel normalises and hashes them for\n *   you. On the server, where there is no snippet, the same identity travels\n *   in `context.user` and is hashed by the adapter.\n * - **The initial consent declaration is not ours.** Meta wants\n *   `fbq('consent', 'revoke')` before `init`, and by the time you hold what\n *   `createTracking` returns that moment has passed. Ours is every\n *   declaration after it, through `consent()`.\n * - **Limited Data Use is not ours either.** `fbq('dataProcessingOptions', …)`\n *   is documented as running before `init`. It belongs in your snippet. The\n *   server half, which has no snippet, carries it on its factory.\n *\n * **There is no pixel id here**, and that is deliberate rather than an\n * omission. `fbq('track')` reaches every pixel the page initialised, so an id\n * passed in would address nothing and the parameter would promise something\n * this adapter cannot deliver. Which pixels exist is declared by your snippet,\n * in `fbq('init')`.\n *\n * @param config - Event name overrides, merged over the built-in map.\n * @returns A provider for `createTracking` from `tracklane/browser`.\n *\n * @example\n * ```ts\n * import { createTracking, meta } from 'tracklane/browser';\n *\n * // Meta's own base code is already in the page, and it named the pixel.\n * const { track } = createTracking({ providers: [meta()] });\n *\n * // fbq('track', 'Purchase', { value: 49.9, currency: 'BRL' }, { eventID: 'T-1' })\n * track('purchase', { value: 49.9, currency: 'BRL' }, { dedupId: 'T-1' });\n * ```\n */\nexport function meta(config: MetaBrowserConfig = {}): BrowserProvider {\n  return {\n    name: 'meta',\n    // An event Meta has no standard name for is still an event Meta accepts,\n    // through `trackCustom`. Nothing is silently dropped.\n    default: 'passthrough',\n    events: { ...CANONICAL_EVENTS, ...config.events },\n\n    track(name: string, data: EventData, options: TrackOptions): void {\n      // `track`, which is what a hand-written call is, and the only form Meta\n      // documents the deduplication object for.\n      //\n      // `trackSingle` exists and would address one pixel, the way GA4's\n      // `send_to` does. It was used here and then abandoned: Meta publishes no\n      // signature for `trackSingle` carrying `{ eventID }`, so the placement\n      // that deduplication depends on had no contract behind it. It worked when\n      // verified against a real pixel, and an undocumented shape that works\n      // today can stop working with no error and no visible symptom — the\n      // browser and server hits would simply both count.\n      //\n      // The cost is Meta's own: on a page with two pixels initialised, `track`\n      // reaches both. That is what `fbq('track')` does by hand, so this\n      // replicates it rather than deciding otherwise on the host's behalf.\n      const command = STANDARD_EVENTS.includes(name) ? 'track' : 'trackCustom';\n      const args: unknown[] = [command, name, pixelParams(data)];\n\n      // Meta's key is `eventID` here and `event_id` on the Conversions API,\n      // matched together with the event name. The library never invents the\n      // value: only one the host already owns can match on both sides.\n      if (options.dedupId !== undefined) args.push({ eventID: options.dedupId });\n\n      push(...args);\n    },\n\n    consent(_command: 'default' | 'update', state: ConsentState): void {\n      // Meta has one consent command and no equivalent of Google's\n      // default/update split, so the command maps to nothing. What is\n      // declared is the state, and that is what is forwarded.\n      const answer = collapse(state);\n      if (answer) push('consent', answer);\n    },\n  };\n}\n","import { assertUniqueProviders, makeReporter, messageOf, resolveEvent } from './dispatch.js';\n\nexport { type Ga4BrowserConfig, ga4 } from './providers/ga4.browser.js';\nexport { type MetaBrowserConfig, meta } from './providers/meta.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. A provider written outside this package\n * implements it exactly as the providers shipped here do.\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  /**\n   * Loads the vendor tag, at creation.\n   *\n   * **Make it idempotent.** A host that rebuilds its tracking, as\n   * `@tracklane/consent` does on every consent answer, creates again and\n   * installs again, including providers that were already there.\n   */\n  install?(): void | Promise<void>;\n  /** Sends one event to this vendor. Throwing here reaches `onError`, not the caller. */\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  /** The vendors to send every event to. Registering the same `name` twice throws. */\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":"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"}

package/dist/index.d.ts

@@ -1,4 +1,2 @@
-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-fzM9ZuE1.js";
-import { i as TrackOptions, n as BrowserTracking, r as BrowserTrackingOptions, t as BrowserProvider } from "./browser-usMUxJhU.js";
-import { a as ServerTrackingOptions, i as ServerTracking, n as ResolvedContext, r as ServerProvider, t as EventContext } from "./server-DRda44Tb.js";
+import { C as UserData, S as TrackingError, _ as ConsentState, b as EventItem, d as ResolvedContext, f as ServerProvider, g as ActionSource, i as TrackOptions, m as ServerTrackingOptions, n as BrowserTracking, p as ServerTracking, r as BrowserTrackingOptions, t as BrowserProvider, u as EventContext, v as EventBinding, x as ProviderDefault, y as EventData } from "./browser-DmJeRMFB.js";
 export type { ActionSource, BrowserProvider, BrowserTracking, BrowserTrackingOptions, ConsentState, EventBinding, EventContext, EventData, EventItem, ProviderDefault, ResolvedContext, ServerProvider, ServerTracking, ServerTrackingOptions, TrackOptions, TrackingError, UserData };

package/dist/server.d.ts

@@ -1,2 +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-DRda44Tb.js";
-export { EventContext, type Ga4ServerConfig, type Ga4ServerCredentials, ResolvedContext, ServerProvider, ServerTracking, ServerTrackingOptions, createTracking, ga4 };
+import { D as Ga4ServerConfig, E as meta, O as Ga4ServerCredentials, T as MetaServerCredentials, d as ResolvedContext, f as ServerProvider, h as createTracking, k as ga4, m as ServerTrackingOptions, p as ServerTracking, u as EventContext, w as MetaServerConfig } from "./browser-DmJeRMFB.js";
+export { EventContext, type Ga4ServerConfig, type Ga4ServerCredentials, type MetaServerConfig, type MetaServerCredentials, ResolvedContext, ServerProvider, ServerTracking, ServerTrackingOptions, createTracking, ga4, meta };

package/dist/server.js

@@ -108,6 +108,217 @@ function ga4(credentials, config = {}) {
 	};
 }
 //#endregion
+//#region src/providers/meta.server.ts
+const GRAPH = "https://graph.facebook.com";
+/**
+* Pinned on purpose. A Graph URL with no version resolves to the *oldest*
+* version still available, which silently changes what the endpoint accepts
+* the day Meta drops it.
+*/
+const DEFAULT_API_VERSION = "v25.0";
+/**
+* How Meta spells the canonical vocabulary, which is GA4's. Kept in step with
+* `meta.browser.ts` by hand: the two halves are two libraries, and neither
+* imports the other.
+*/
+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"
+};
+/**
+* Web Crypto rather than `node:crypto`, so the built server bundle stays
+* platform-neutral: this adapter is called from Cloudflare Workers, Deno and
+* Vercel's edge runtime as often as from a Node process, and a `node:` import
+* would rule those out for no gain.
+*/
+async function sha256(value) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+* **Why the adapter hashes and does not ask the host to.**
+*
+* This looks like the library transforming data, and the cutting rule forbids
+* that. It is not. Meta does not define a field called "email" that happens
+* to want a hash: it defines `em` *as* the SHA-256 of the trimmed, lowercased
+* address, the same way it defines `event_time` as seconds rather than
+* milliseconds. Writing this line by hand you write
+* `sha256(email.trim().toLowerCase())`, and the adapter replicates exactly
+* that. Normalisation lives with the field it belongs to.
+*
+* The alternative is worse and is where integrations demonstrably go wrong:
+* three vendors want SHA-256 under three different normalisation rules, so a
+* host hashing on its own side has to hash the same address three ways and
+* discovers a mistake only as a quietly poor match rate.
+*/
+const normaliseEmail = (value) => value.trim().toLowerCase();
+/**
+* "Remove symbols, letters, and any leading zeros." The country code is not
+* added here: Meta wants one and the library does not know it, and guessing a
+* country onto a phone number invents an identifier for a different person.
+*/
+const normalisePhone = (value) => value.replace(/\D/g, "").replace(/^0+/, "");
+/** "Lowercase only with no punctuation." Spaces and accents survive; Meta reads UTF-8. */
+const normaliseName = (value) => value.trim().toLowerCase().replace(/[\p{P}\p{S}]/gu, "");
+/**
+* GA4's `items` become Meta's `contents`, a closed shape: `id`, `quantity`,
+* `item_price`, `delivery_category`. The rest of a GA4 item is dropped rather
+* than forwarded, because a key Meta does not read inside `contents` looks
+* mapped and arrives nowhere.
+*/
+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. Everything
+* the host named itself passes through, because a business measures things
+* this vocabulary does not name.
+*
+* `transaction_id` becomes `order_id`, which this surface documents and the
+* pixel does not. It is one of the asymmetries between Meta's two halves an
+* adapter absorbs so nobody else has to.
+*/
+function customData(data) {
+	const { items, transaction_id: transactionId, ...rest } = data;
+	const custom = { ...rest };
+	if (transactionId !== void 0) custom.order_id = transactionId;
+	if (items) custom.contents = contents(items);
+	return custom;
+}
+/**
+* The heaviest surface of the five vendors: four hashed identifiers, four raw
+* ones, and two cookies forwarded exactly as the pixel wrote them.
+*
+* Built in a fixed order, and hashed one after another rather than in
+* parallel, so that the same input produces the same JSON on every run. Two
+* identical events differing only in key order would be the library inventing
+* something, which is precisely what the conformance suite looks for.
+*/
+async function userData(context) {
+	const user = context.user ?? {};
+	const built = {};
+	const hashed = [
+		[
+			"em",
+			user.email,
+			normaliseEmail
+		],
+		[
+			"ph",
+			user.phone,
+			normalisePhone
+		],
+		[
+			"fn",
+			user.firstName,
+			normaliseName
+		],
+		[
+			"ln",
+			user.lastName,
+			normaliseName
+		]
+	];
+	for (const [field, raw, normalise] of hashed) {
+		if (raw === void 0) continue;
+		const normalised = normalise(raw);
+		if (!normalised) continue;
+		built[field] = await sha256(normalised);
+	}
+	if (user.userId !== void 0) built.external_id = user.userId;
+	if (context.ip !== void 0) built.client_ip_address = context.ip;
+	if (context.userAgent !== void 0) built.client_user_agent = context.userAgent;
+	const fbp = context.cookies._fbp;
+	if (fbp) built.fbp = fbp;
+	const fbc = context.cookies._fbc;
+	if (fbc) built.fbc = fbc;
+	return built;
+}
+/**
+* Meta's Conversions API.
+*
+* @param credentials - The pixel id and an access token.
+* @param config - Event overrides, the default action source, and Meta's own
+* levers: the API version, a test event code, and Limited Data Use.
+* @returns A provider for `createTracking` from `tracklane/server`.
+*
+* @example
+* ```ts
+* import { createTracking, meta } from 'tracklane/server';
+*
+* const { track } = createTracking({
+*   providers: [meta({ pixelId: '1234567890', accessToken: process.env.META_TOKEN! })],
+* });
+*
+* await track('purchase', order, {
+*   user: { email: order.email },
+*   cookies: request.headers.get('cookie'),
+*   dedupId: order.id,
+*   ip,
+*   userAgent,
+* });
+* ```
+*/
+function meta(credentials, config = {}) {
+	const { pixelId, accessToken } = credentials;
+	const { actionSource = "website", apiVersion = DEFAULT_API_VERSION, testEventCode } = config;
+	return {
+		name: "meta",
+		default: "passthrough",
+		events: {
+			...CANONICAL_EVENTS,
+			...config.events
+		},
+		async track(name, data, context, report) {
+			const user = await userData(context);
+			if (Object.keys(user).length === 0) throw new Error("meta: cannot build user_data, the Conversions API requires at least one identifier. Pass context.user, context.ip with context.userAgent, or the _fbp/_fbc cookies.");
+			const event = {
+				event_name: name,
+				event_time: Math.floor(context.timestamp / 1e3),
+				action_source: context.source ?? actionSource,
+				user_data: user
+			};
+			if (context.dedupId !== void 0) event.event_id = context.dedupId;
+			if (context.url !== void 0) event.event_source_url = context.url;
+			const custom = customData(data);
+			if (Object.keys(custom).length > 0) event.custom_data = custom;
+			if (config.dataProcessingOptions) {
+				event.data_processing_options = config.dataProcessingOptions;
+				if (config.dataProcessingOptionsCountry !== void 0) event.data_processing_options_country = config.dataProcessingOptionsCountry;
+				if (config.dataProcessingOptionsState !== void 0) event.data_processing_options_state = config.dataProcessingOptionsState;
+			}
+			const body = new URLSearchParams({
+				data: JSON.stringify([event]),
+				access_token: accessToken
+			});
+			if (testEventCode) body.set("test_event_code", testEventCode);
+			const response = await fetch(`${GRAPH}/${apiVersion}/${encodeURIComponent(pixelId)}/events`, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body
+			});
+			if (!response.ok) throw new Error(`meta: the Conversions API answered ${response.status}`);
+			const result = await response.json().catch(() => null);
+			const messages = result?.messages;
+			if (Array.isArray(messages) && messages.length > 0) report(`accepted with ${messages.length} warning(s) from the Conversions API; read them under fbtrace_id ${result?.fbtrace_id ?? "unknown"} in Events Manager`);
+		}
+	};
+}
+//#endregion
 //#region src/server.ts
 /** `name=value; name=value`, the shape of a `Cookie` header. */
 function parseCookies(cookies) {
@@ -185,6 +396,6 @@ function createTracking(options) {
 	} };
 }
 //#endregion
-export { createTracking, ga4 };
+export { createTracking, ga4, meta };
 
 //# sourceMappingURL=server.js.map