react-marketing-tools 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/chunks/core.js

@@ -118,59 +118,151 @@ var e = [
 			});
 		}
 	};
-}, b = class extends Error {
+}, b = /* @__PURE__ */ new Set([
+	"AddPaymentInfo",
+	"AddToCart",
+	"AddToWishlist",
+	"CompleteRegistration",
+	"Contact",
+	"CustomizeProduct",
+	"Donate",
+	"FindLocation",
+	"InitiateCheckout",
+	"Lead",
+	"PageView",
+	"Purchase",
+	"Schedule",
+	"Search",
+	"StartTrial",
+	"SubmitApplication",
+	"Subscribe",
+	"ViewContent"
+]), x = {
+	purchase: "Purchase",
+	sign_up: "CompleteRegistration",
+	generate_lead: "Lead",
+	add_to_cart: "AddToCart",
+	begin_checkout: "InitiateCheckout",
+	view_item: "ViewContent",
+	search: "Search",
+	add_payment_info: "AddPaymentInfo",
+	add_to_wishlist: "AddToWishlist"
+}, S = (e) => typeof e == "object" && !!e, C = (e) => {
+	let t = e.filter(S).filter((e) => e.item_id !== void 0).map((e) => ({
+		id: String(e.item_id),
+		quantity: typeof e.quantity == "number" ? e.quantity : 1
+	}));
+	return {
+		content_ids: t.map((e) => e.id),
+		contents: t,
+		num_items: t.reduce((e, t) => e + t.quantity, 0),
+		content_type: "product"
+	};
+}, w = ({ items: e, search_term: t, ...n }) => ({
+	...n,
+	...typeof t == "string" ? { search_string: t } : {},
+	...Array.isArray(e) ? C(e) : {}
+}), T = ({ name: e, params: t, options: n }) => {
+	let r = n?.meta, i = r?.event ?? x[e] ?? e;
+	return {
+		command: b.has(i) ? "track" : "trackCustom",
+		name: i,
+		params: {
+			...w(t),
+			...r?.params
+		}
+	};
+}, E = /^\d+$/, D = "https://connect.facebook.net/en_US/fbevents.js", O = () => {
+	let e = window;
+	if (!e.fbq) {
+		let t = function() {
+			let e = arguments;
+			t.callMethod ? t.callMethod.call(t, ...e) : t.queue.push(e);
+		};
+		t.push = t, t.loaded = !0, t.version = "2.0", t.queue = [], e.fbq = t, e._fbq ??= t;
+	}
+	return e.fbq;
+}, k = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/fbevents.js")), A = ({ userId: e, traits: t }) => Object.fromEntries(Object.entries({
+	external_id: e,
+	em: t.email,
+	ph: t.phone,
+	fn: t.firstName,
+	ln: t.lastName
+}).filter(([, e]) => e !== void 0)), j = (e) => e.adUserData === "granted" ? "grant" : "revoke", M = ({ pixelId: e, pageViews: t = "auto", loadScript: n = !0, nonce: r }) => {
+	if (!E.test(e)) throw Error(`[react-marketing-tools] metaPixel.pixelId must be the numeric pixel ID (received ${JSON.stringify(e)}).`);
+	return {
+		name: "metaPixel",
+		start({ consent: i, identity: a }) {
+			let o = O();
+			t === "manual" && (o.disablePushState = !0), j(i) === "revoke" && o("consent", "revoke"), a ? o("init", e, A(a)) : o("init", e), t === "auto" && o("track", "PageView"), n && !k() && m({
+				src: D,
+				nonce: r
+			});
+		},
+		track(e) {
+			let { command: t, name: n, params: r } = T(e);
+			O()(t, n, r, { eventID: e.eventId });
+		},
+		page({ eventId: e }) {
+			t === "manual" && O()("track", "PageView", {}, { eventID: e });
+		},
+		consent(e) {
+			O()("consent", j(e));
+		}
+	};
+}, N = class extends Error {
 	code;
 	constructor(e, t, n) {
 		super(`[react-marketing-tools] ${t}`, n), this.name = "AnalyticsError", this.code = e;
 	}
-}, x = /^[A-Za-z][A-Za-z0-9_]{0,39}$/, S = [
+}, P = /^[A-Za-z][A-Za-z0-9_]{0,39}$/, F = [
 	"google_",
 	"ga_",
 	"firebase_"
-], C = 25, w = 100, T = {
+], I = 25, L = 100, R = {
 	page_location: 1e3,
 	page_referrer: 420,
 	page_title: 300
-}, E = [
+}, z = [
 	"email",
 	"phone",
 	"first_name",
 	"last_name",
 	"address",
 	"password"
-], D = String.raw`[\w.+-]+(?:@|%40)[\w-]+(?:\.[\w-]+)+`, O = "[redacted]", k = (e) => {
-	if (!x.test(e)) return "must start with a letter, contain only letters, digits and underscores, and be at most 40 characters";
-	let t = S.find((t) => e.toLowerCase().startsWith(t));
+], B = String.raw`[\w.+-]+(?:@|%40)[\w-]+(?:\.[\w-]+)+`, V = "[redacted]", H = (e) => {
+	if (!P.test(e)) return "must start with a letter, contain only letters, digits and underscores, and be at most 40 characters";
+	let t = F.find((t) => e.toLowerCase().startsWith(t));
 	return t && `must not start with the reserved prefix "${t}"`;
-}, A = (e) => {
-	let t = k(e);
+}, U = (e) => {
+	let t = H(e);
 	return t && `event name "${e}" ${t}`;
-}, j = (e) => {
+}, W = (e) => {
 	let t = Object.keys(e), n = t.flatMap((t) => {
-		let n = k(t);
+		let n = H(t);
 		if (n) return [`param "${t}" ${n}`];
-		let r = e[t], i = T[t] ?? w;
+		let r = e[t], i = R[t] ?? L;
 		return typeof r == "string" && r.length > i ? [`param "${t}" is longer than ${i} characters`] : [];
 	});
-	return t.length > C ? [`has ${t.length} params; the limit is ${C}`, ...n] : n;
-}, M = (e) => new RegExp(D, "i").test(e), N = (e, t) => (typeof t == "string" || typeof t == "number") && E.some((t) => e.toLowerCase().includes(t)) ? O : typeof t == "string" ? t.replace(new RegExp(D, "gi"), O) : t, P = (e) => {
+	return t.length > I ? [`has ${t.length} params; the limit is ${I}`, ...n] : n;
+}, G = (e) => new RegExp(B, "i").test(e), K = (e, t) => (typeof t == "string" || typeof t == "number") && z.some((t) => e.toLowerCase().includes(t)) ? V : typeof t == "string" ? t.replace(new RegExp(B, "gi"), V) : t, q = (e) => {
 	let t = Object.entries(e).map(([e, t]) => [
 		e,
 		t,
-		N(e, t)
+		K(e, t)
 	]);
 	return {
 		params: Object.fromEntries(t.map(([e, , t]) => [e, t])),
 		redactedKeys: t.filter(([, e, t]) => t !== e).map(([e]) => e)
 	};
-}, F = () => typeof window < "u", I = () => typeof crypto.randomUUID == "function" ? crypto.randomUUID() : "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (e) => (Number(e) ^ crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(1))[0] & 15 >> Number(e) / 4).toString(16)), L = (e) => {
+}, J = () => typeof window < "u", Y = () => typeof crypto.randomUUID == "function" ? crypto.randomUUID() : "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (e) => (Number(e) ^ crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(1))[0] & 15 >> Number(e) / 4).toString(16)), X = (e) => {
 	if (e.consent !== "granted" && e.consent !== "denied") throw Error(`[react-marketing-tools] createAnalytics: "consent" must be 'granted' or 'denied' (received ${JSON.stringify(e.consent)}).`);
-}, R = (i) => {
-	L(i);
+}, Z = (i) => {
+	X(i);
 	let { debug: a = !1, onError: s = console.error, respectGpc: c = !0 } = i, l = n({
 		consent: i.consent,
 		gpc: c && o()
-	}), u = l, d = [
+	}), u = l, d, f = [
 		...i.gtm ? [y({
 			...i.gtm,
 			nonce: i.nonce
@@ -179,80 +271,101 @@ var e = [
 			...i.ga4,
 			nonce: i.nonce
 		})] : [],
+		...i.metaPixel ? [M({
+			...i.metaPixel,
+			nonce: i.nonce
+		})] : [],
 		...i.destinations ?? []
-	], f = [], p = !1, m = (e) => {
+	], p = [], m = !1, h = (e) => {
 		if (a) throw e;
 		s(e);
-	}, h = (e) => {
-		for (let t of d) try {
+	}, _ = (e) => {
+		for (let t of f) try {
 			e(t);
 		} catch (e) {
-			s(new b("destination_failed", `destination "${t.name}" failed`, { cause: e }));
+			s(new N("destination_failed", `destination "${t.name}" failed`, { cause: e }));
 		}
-	}, _ = (e) => {
-		p ? h(e) : f.push(e);
-	}, v = (e, t) => {
-		let n = A(e);
-		if (n) {
-			m(new b("invalid_event", n));
+	}, v = (e) => {
+		m ? _(e) : p.push(e);
+	}, b = ({ name: e, params: t, options: n }) => {
+		let r = U(e);
+		if (r) {
+			h(new N("invalid_event", r));
 			return;
 		}
-		for (let n of j(t)) m(new b("invalid_param", `event "${e}" ${n}`));
-		let { params: r, redactedKeys: i } = P(t);
-		return i.length > 0 && m(new b("pii_redacted", `event "${e}": personal data redacted from ${i.join(", ")}`)), {
+		for (let n of W(t)) h(new N("invalid_param", `event "${e}" ${n}`));
+		let i = q(t), a = n?.meta?.params && q(n.meta.params), o = [...i.redactedKeys, ...a?.redactedKeys.map((e) => `meta.${e}`) ?? []];
+		return o.length > 0 && h(new N("pii_redacted", `event "${e}": personal data redacted from ${o.join(", ")}`)), {
 			name: e,
-			params: r,
-			eventId: I(),
+			params: i.params,
+			...n && { options: a ? {
+				...n,
+				meta: {
+					...n.meta,
+					params: a.params
+				}
+			} : n },
+			eventId: Y(),
 			timestamp: Date.now()
 		};
 	};
 	return {
 		start() {
-			!p && F() && (p = !0, h((e) => e.start({ consent: l })), f.splice(0).forEach(h));
+			!m && J() && (m = !0, _((e) => e.start({
+				consent: l,
+				identity: d
+			})), p.splice(0).forEach(_));
 		},
-		track(e, t = {}) {
-			if (!F()) return;
-			let n = v(e, t);
-			n && _((e) => e.track(n));
+		track(e, t = {}, n) {
+			if (!J()) return;
+			let r = b({
+				name: e,
+				params: t,
+				options: n
+			});
+			r && v((e) => e.track(r));
 		},
 		page(e = {}) {
-			if (!F()) return;
-			let t = v("page_view", {
-				page_location: location.href,
-				page_title: document.title,
-				...e
+			if (!J()) return;
+			let t = b({
+				name: "page_view",
+				params: {
+					page_location: location.href,
+					page_title: document.title,
+					...e
+				}
 			});
-			t && _((e) => e.page ? e.page(t) : e.track(t));
+			t && v((e) => e.page ? e.page(t) : e.track(t));
 		},
 		identify(e, t = {}) {
-			if (F()) {
-				if (!e || M(e)) {
-					m(new b("invalid_user_id", "identify() needs a non-empty user id that is not personal data such as an email address"));
-					return;
-				}
-				_((n) => n.identify?.({
-					userId: e,
-					traits: t
-				}));
+			if (!J()) return;
+			if (!e || G(e)) {
+				h(new N("invalid_user_id", "identify() needs a non-empty user id that is not personal data such as an email address"));
+				return;
 			}
+			let n = {
+				userId: e,
+				traits: t
+			};
+			d = n, v((e) => e.identify?.(n));
 		},
 		reset() {
-			F() && _((e) => e.reset?.());
+			J() && (d = void 0, v((e) => e.reset?.()));
 		},
 		consent: {
 			update(n) {
-				if (!F()) return;
+				if (!J()) return;
 				let i = Object.entries(n).filter(([n, r]) => r !== void 0 && !(e.includes(n) && t(r)));
 				if (i.length > 0) {
-					m(new b("invalid_consent", `consent.update() ignored: ${i.map(([e, t]) => `${e}=${JSON.stringify(t)}`).join(", ")}. Use analytics, ads, adUserData or adPersonalization with 'granted' or 'denied'.`));
+					h(new N("invalid_consent", `consent.update() ignored: ${i.map(([e, t]) => `${e}=${JSON.stringify(t)}`).join(", ")}. Use analytics, ads, adUserData or adPersonalization with 'granted' or 'denied'.`));
 					return;
 				}
 				let a = r(u, n);
-				u = a, _((e) => e.consent?.(a));
+				u = a, v((e) => e.consent?.(a));
 			},
 			get: () => u
 		}
 	};
 };
 //#endregion
-export { b as n, R as t };
+export { N as n, Z as t };

package/dist/core/types.d.ts

@@ -13,9 +13,18 @@ export type ConsentState = {
 export type ConsentUpdate = Partial<ConsentState>;
 /** Event parameters, passed to every destination as-is. */
 export type EventParams = Record<string, unknown>;
+/** Per-call adjustments for one destination, when the automatic mapping isn't what you want. */
+export type TrackOptions = {
+    /** Meta Pixel: send as this event name (standard or custom), with these params merged over the mapped ones. */
+    meta?: {
+        event?: string;
+        params?: EventParams;
+    };
+};
 export type AnalyticsEvent = {
     name: string;
     params: EventParams;
+    options?: TrackOptions;
     /** Unique per `track()` call and shared by every destination, so vendors can deduplicate the same event. */
     eventId: string;
     /** Milliseconds since the Unix epoch at the moment `track()` was called. */
@@ -38,9 +47,13 @@ export type Identity = {
 /** Somewhere events are sent. Built-in destinations are configured by key; custom ones go in `destinations`. */
 export type Destination = {
     name: string;
-    /** Called once, in the browser, by `analytics.start()`, with the consent state the page started with. */
+    /**
+     * Called once, in the browser, by `analytics.start()`, with the consent state the page started with and the user
+     * identified before start, if any. Some vendors (the Meta Pixel) only accept user data when they initialise.
+     */
     start(context: {
         consent: ConsentState;
+        identity?: Identity;
     }): void;
     track(event: AnalyticsEvent): void;
     /** Receives every consent change, in order with events. */
@@ -76,6 +89,17 @@ export type Ga4Config = {
     /** Milliseconds tags wait for a consent update when a Consent Mode signal starts denied. Defaults to 500. */
     waitForUpdate?: number;
 };
+export type MetaPixelConfig = {
+    /** Meta Pixel (dataset) ID, e.g. `1234567890123456`. */
+    pixelId: string;
+    /**
+     * `'auto'` (default): the Pixel sends PageView on load and on client-side navigation itself.
+     * `'manual'`: only `analytics.page()` sends PageView.
+     */
+    pageViews?: 'auto' | 'manual';
+    /** Set to `false` when the page already includes the Meta Pixel base code. Defaults to `true`. */
+    loadScript?: boolean;
+};
 export type AnalyticsConfig = {
     /** Initial consent for every purpose. Required, so every site makes an explicit choice. */
     consent: ConsentStatus;
@@ -86,6 +110,7 @@ export type AnalyticsConfig = {
     respectGpc?: boolean;
     gtm?: GtmConfig;
     ga4?: Ga4Config;
+    metaPixel?: MetaPixelConfig;
     /** Custom destinations, in addition to the built-in ones. */
     destinations?: Destination[];
     /** Content-Security-Policy nonce added to every script the library injects. */
@@ -99,7 +124,7 @@ export type Analytics = {
     /** Loads vendor scripts and delivers queued events. Safe to call more than once; does nothing outside the browser. */
     start(): void;
     /** Sends an event to every destination, queued until `start()`. Does nothing outside the browser. */
-    track(name: string, params?: EventParams): void;
+    track(name: string, params?: EventParams, options?: TrackOptions): void;
     /** Sends a `page_view` with the current `page_location` and `page_title`, plus any params given. */
     page(params?: EventParams): void;
     /** Associates later events with a user. `userId` must not be personal data such as an email address. */

package/dist/core.d.ts

@@ -1,4 +1,4 @@
 export { createAnalytics } from './core/createAnalytics.js';
 export { AnalyticsError } from './core/errors.js';
 export type { AnalyticsErrorCode } from './core/errors.js';
-export type { Analytics, AnalyticsConfig, AnalyticsEvent, ConsentState, ConsentStatus, ConsentUpdate, Destination, EventParams, Ga4Config, GtmConfig, Identity, IdentityTraits, } from './core/types.js';
+export type { Analytics, AnalyticsConfig, AnalyticsEvent, ConsentState, ConsentStatus, ConsentUpdate, Destination, EventParams, Ga4Config, GtmConfig, Identity, IdentityTraits, MetaPixelConfig, TrackOptions, } from './core/types.js';

package/dist/destinations/metaEventMap.d.ts

@@ -0,0 +1,12 @@
+import type { AnalyticsEvent, EventParams } from '../core/types.js';
+/** GA4 recommended event → the Meta standard event with the same meaning. */
+export declare const GA4_TO_META_EVENT: Readonly<Record<string, string>>;
+/** GA4-style params → Meta standard params; everything else passes through. */
+export declare const toMetaParams: ({ items, search_term: searchTerm, ...rest }: EventParams) => EventParams;
+export type MetaCall = {
+    command: 'track' | 'trackCustom';
+    name: string;
+    params: EventParams;
+};
+/** How an event reaches the Pixel: a standard event through `track`, anything else through `trackCustom`. */
+export declare const toMetaCall: ({ name, params, options, }: AnalyticsEvent) => MetaCall;

package/dist/destinations/metaPixel.d.ts

@@ -0,0 +1,6 @@
+import type { Destination, MetaPixelConfig } from '../core/types.js';
+type MetaPixelDestinationOptions = MetaPixelConfig & {
+    nonce?: string;
+};
+export declare const createMetaPixelDestination: ({ pixelId, pageViews, loadScript, nonce, }: MetaPixelDestinationOptions) => Destination;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-marketing-tools",
   "type": "module",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "React Marketing Tools are a set of tools to make it easier for you to implement analytics and track user journeys, interactions throughout your App. using dataLayer/Google Tag Manager, GA4 fetch directly or coming soon facebook pixel.",
   "license": "MIT",
   "author": "bronz3beard <exempli.gratia.webdesign@gmail.com> (https://www.heyrory.com/)",