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

package/dist/chunks/core.js

@@ -1,154 +1,371 @@
-//#region lib/destinations/gtm.ts
-var e = /^GTM-[A-Z0-9]+$/, t = () => window.dataLayer ??= [], n = (e) => Array.from(document.scripts).some((t) => t.src === e), r = ({ src: e, nonce: t }) => {
+//#region lib/core/consent.ts
+var e = [
+	"analytics",
+	"ads",
+	"adUserData",
+	"adPersonalization"
+], t = (e) => e === "granted" || e === "denied", n = ({ consent: e, gpc: t }) => {
+	let n = t ? "denied" : e;
+	return {
+		analytics: e,
+		ads: n,
+		adUserData: n,
+		adPersonalization: n
+	};
+}, r = (e, t) => ({
+	analytics: t.analytics ?? e.analytics,
+	ads: t.ads ?? e.ads,
+	adUserData: t.adUserData ?? t.ads ?? e.adUserData,
+	adPersonalization: t.adPersonalization ?? t.ads ?? e.adPersonalization
+}), i = (e) => ({
+	analytics_storage: e.analytics,
+	ad_storage: e.ads,
+	ad_user_data: e.adUserData,
+	ad_personalization: e.adPersonalization
+}), a = (e) => Object.values(e).includes("denied"), o = () => typeof navigator < "u" && navigator.globalPrivacyControl === !0, s = () => window.dataLayer ??= [], c = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/gtag/js")), l = () => window.gtag ??= function() {
+	s().push(arguments);
+}, u = ({ consent: e, waitForUpdate: t }) => {
+	l()("consent", "default", {
+		...i(e),
+		...a(e) ? { wait_for_update: t } : {}
+	});
+}, d = (e) => {
+	l()("consent", "update", i(e));
+}, f = (e, t) => {
+	let n = URL.canParse(e) ? new URL(e) : void 0;
+	if (n?.protocol !== "https:") throw Error(`[react-marketing-tools] ${t} must be an https:// URL (received ${JSON.stringify(e)}).`);
+	return n;
+}, p = (e) => Array.from(document.scripts).some((t) => t.src === e), m = ({ src: e, nonce: t }) => {
 	let n = document.createElement("script");
 	n.async = !0, n.src = e, t && n.setAttribute("nonce", t), document.head.append(n);
-}, i = ({ containerId: i, loadScript: a = !0, nonce: o }) => {
-	if (!e.test(i)) throw Error(`[react-marketing-tools] gtm.containerId must look like "GTM-XXXXXXX" (received ${JSON.stringify(i)}).`);
-	let s = `https://www.googletagmanager.com/gtm.js?id=${i}`;
+}, h = /^G-[A-Z0-9]+$/, g = ({ measurementId: e, pageViews: t = "auto", loadScript: n = !0, serverContainerUrl: r, waitForUpdate: i = 500, nonce: a }) => {
+	if (!h.test(e)) throw Error(`[react-marketing-tools] ga4.measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)}).`);
+	r !== void 0 && f(r, "ga4.serverContainerUrl");
+	let o = `https://www.googletagmanager.com/gtag/js?id=${e}`, s = (e, t) => r ? {
+		...e,
+		event_id: t
+	} : e;
+	return {
+		name: "ga4",
+		start({ consent: s }) {
+			u({
+				consent: s,
+				waitForUpdate: i
+			}), c() || (l()("js", /* @__PURE__ */ new Date()), n && m({
+				src: o,
+				nonce: a
+			})), l()("config", e, {
+				...t === "manual" ? { send_page_view: !1 } : {},
+				...r ? { server_container_url: r } : {}
+			});
+		},
+		track({ name: e, params: t, eventId: n }) {
+			l()("event", e, s(t, n));
+		},
+		consent(e) {
+			d(e);
+		},
+		page({ params: e, eventId: n }) {
+			t === "manual" && l()("event", "page_view", s(e, n));
+		},
+		identify({ userId: e }) {
+			l()("set", { user_id: e });
+		},
+		reset() {
+			l()("set", { user_id: null });
+		}
+	};
+}, _ = /^GTM-[A-Z0-9]+$/, v = (e, t) => {
+	let n = f(t ?? "https://www.googletagmanager.com/gtm.js", "gtm.scriptUrl");
+	return n.searchParams.set("id", e), n.href;
+}, y = ({ containerId: e, loadScript: t = !0, scriptUrl: n, waitForUpdate: r = 500, nonce: i }) => {
+	if (!_.test(e)) throw Error(`[react-marketing-tools] gtm.containerId must look like "GTM-XXXXXXX" (received ${JSON.stringify(e)}).`);
+	let a = v(e, n);
 	return {
 		name: "gtm",
-		start() {
-			let e = t();
-			a && !n(s) && (e.push({
+		start({ consent: e }) {
+			u({
+				consent: e,
+				waitForUpdate: r
+			}), t && !p(a) && (s().push({
 				"gtm.start": Date.now(),
 				event: "gtm.js"
-			}), r({
-				src: s,
-				nonce: o
+			}), m({
+				src: a,
+				nonce: i
 			}));
 		},
-		track({ name: e, params: n, eventId: r }) {
-			t().push({
-				...n,
+		track({ name: e, params: t, eventId: n }) {
+			s().push({
+				...t,
 				event: e,
-				event_id: r
+				event_id: n
 			});
 		},
+		consent(e) {
+			d(e);
+		},
 		identify({ userId: e }) {
-			t().push({
+			s().push({
 				event: "identify",
 				user_id: e
 			});
 		},
 		reset() {
-			t().push({
+			s().push({
 				event: "reset",
 				user_id: void 0
 			});
 		}
 	};
-}, a = 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;
 	}
-}, o = /^[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, l = 100, u = {
+], I = 25, L = 100, R = {
 	page_location: 1e3,
 	page_referrer: 420,
 	page_title: 300
-}, d = [
+}, z = [
 	"email",
 	"phone",
 	"first_name",
 	"last_name",
 	"address",
 	"password"
-], f = String.raw`[\w.+-]+(?:@|%40)[\w-]+(?:\.[\w-]+)+`, p = "[redacted]", m = (e) => {
-	if (!o.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}"`;
-}, h = (e) => {
-	let t = m(e);
+}, U = (e) => {
+	let t = H(e);
 	return t && `event name "${e}" ${t}`;
-}, g = (e) => {
+}, W = (e) => {
 	let t = Object.keys(e), n = t.flatMap((t) => {
-		let n = m(t);
+		let n = H(t);
 		if (n) return [`param "${t}" ${n}`];
-		let r = e[t], i = u[t] ?? l;
+		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;
-}, _ = (e) => new RegExp(f, "i").test(e), v = (e, t) => (typeof t == "string" || typeof t == "number") && d.some((t) => e.toLowerCase().includes(t)) ? p : typeof t == "string" ? t.replace(new RegExp(f, "gi"), p) : t, y = (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,
-		v(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)
 	};
-}, b = () => typeof window < "u", x = () => 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)), S = (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)}).`);
-}, C = (e) => {
-	S(e);
-	let { debug: t = !1, onError: n = console.error } = e, r = [...e.gtm ? [i({
-		...e.gtm,
-		nonce: e.nonce
-	})] : [], ...e.destinations ?? []], o = [], s = !1, c = (e) => {
-		if (t) throw e;
-		n(e);
-	}, l = (e) => {
-		for (let t of r) try {
+}, 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, f = [
+		...i.gtm ? [y({
+			...i.gtm,
+			nonce: i.nonce
+		})] : [],
+		...i.ga4 ? [g({
+			...i.ga4,
+			nonce: i.nonce
+		})] : [],
+		...i.metaPixel ? [M({
+			...i.metaPixel,
+			nonce: i.nonce
+		})] : [],
+		...i.destinations ?? []
+	], p = [], m = !1, h = (e) => {
+		if (a) throw e;
+		s(e);
+	}, _ = (e) => {
+		for (let t of f) try {
 			e(t);
 		} catch (e) {
-			n(new a("destination_failed", `destination "${t.name}" failed`, { cause: e }));
+			s(new N("destination_failed", `destination "${t.name}" failed`, { cause: e }));
 		}
-	}, u = (e) => {
-		s ? l(e) : o.push(e);
-	}, d = (e, t) => {
-		let n = h(e);
-		if (n) {
-			c(new a("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 g(t)) c(new a("invalid_param", `event "${e}" ${n}`));
-		let { params: r, redactedKeys: i } = y(t);
-		return i.length > 0 && c(new a("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: x(),
+			params: i.params,
+			...n && { options: a ? {
+				...n,
+				meta: {
+					...n.meta,
+					params: a.params
+				}
+			} : n },
+			eventId: Y(),
 			timestamp: Date.now()
 		};
 	};
 	return {
 		start() {
-			!s && b() && (s = !0, l((e) => e.start()), o.splice(0).forEach(l));
+			!m && J() && (m = !0, _((e) => e.start({
+				consent: l,
+				identity: d
+			})), p.splice(0).forEach(_));
 		},
-		track(e, t = {}) {
-			if (!b()) return;
-			let n = d(e, t);
-			n && u((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 (!b()) return;
-			let t = d("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 && u((e) => e.page ? e.page(t) : e.track(t));
+			t && v((e) => e.page ? e.page(t) : e.track(t));
 		},
 		identify(e, t = {}) {
-			if (b()) {
-				if (!e || _(e)) {
-					c(new a("invalid_user_id", "identify() needs a non-empty user id that is not personal data such as an email address"));
-					return;
-				}
-				u((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() {
-			b() && u((e) => e.reset?.());
+			J() && (d = void 0, v((e) => e.reset?.()));
+		},
+		consent: {
+			update(n) {
+				if (!J()) return;
+				let i = Object.entries(n).filter(([n, r]) => r !== void 0 && !(e.includes(n) && t(r)));
+				if (i.length > 0) {
+					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, v((e) => e.consent?.(a));
+			},
+			get: () => u
 		}
 	};
 };
 //#endregion
-export { a as n, C as t };
+export { N as n, Z as t };

package/dist/core/consent.d.ts

@@ -0,0 +1,20 @@
+import type { ConsentState, ConsentStatus, ConsentUpdate } from './types.js';
+export declare const CONSENT_KEYS: readonly (keyof ConsentState)[];
+export declare const isConsentStatus: (value: unknown) => value is ConsentStatus;
+/** Every signal follows `consent`, except that Global Privacy Control (an ad opt-out) denies the advertising signals. */
+export declare const initialConsentState: ({ consent, gpc, }: {
+    consent: ConsentStatus;
+    gpc: boolean;
+}) => ConsentState;
+/** `ads` also sets `adUserData` and `adPersonalization`, unless the update gives them explicitly (e.g. TCF-style CMPs). */
+export declare const applyConsentUpdate: (state: ConsentState, update: ConsentUpdate) => ConsentState;
+/** Google Consent Mode v2 signals. */
+export declare const toGoogleConsent: (state: ConsentState) => {
+    analytics_storage: ConsentStatus;
+    ad_storage: ConsentStatus;
+    ad_user_data: ConsentStatus;
+    ad_personalization: ConsentStatus;
+};
+export declare const hasDeniedSignal: (state: ConsentState) => boolean;
+/** Global Privacy Control: a browser-level "do not sell or share" signal. Absent in browsers that don't support it. */
+export declare const readGlobalPrivacyControl: () => boolean;

package/dist/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type AnalyticsErrorCode = 'invalid_event' | 'invalid_param' | 'invalid_user_id' | 'pii_redacted' | 'destination_failed';
+export type AnalyticsErrorCode = 'invalid_event' | 'invalid_param' | 'invalid_user_id' | 'invalid_consent' | 'pii_redacted' | 'destination_failed';
 /** Every problem the library reports to `onError`, or throws when `debug` is on. */
 export declare class AnalyticsError extends Error {
     readonly code: AnalyticsErrorCode;

package/dist/core/types.d.ts

@@ -1,10 +1,30 @@
 import type { AnalyticsError } from './errors.js';
 export type ConsentStatus = 'granted' | 'denied';
+/**
+ * The visitor's consent, per purpose. `ads` covers advertising storage; `adUserData` (sending user data to ad platforms)
+ * and `adPersonalization` follow `ads` unless set explicitly.
+ */
+export type ConsentState = {
+    analytics: ConsentStatus;
+    ads: ConsentStatus;
+    adUserData: ConsentStatus;
+    adPersonalization: ConsentStatus;
+};
+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. */
@@ -27,9 +47,17 @@ 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()`. */
-    start(): void;
+    /**
+     * 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. */
+    consent?(state: ConsentState): void;
     /** Receives `page_view` events. Destinations without it get them through `track`. */
     page?(event: AnalyticsEvent): void;
     identify?(identity: Identity): void;
@@ -41,11 +69,48 @@ export type GtmConfig = {
     containerId: string;
     /** Set to `false` when the page already includes the GTM snippet. Defaults to `true`. */
     loadScript?: boolean;
+    /** Load `gtm.js` from this https URL instead of googletagmanager.com, e.g. your server-side GTM domain. */
+    scriptUrl?: string;
+    /** Milliseconds tags wait for a consent update when a Consent Mode signal starts denied. Defaults to 500. */
+    waitForUpdate?: number;
+};
+export type Ga4Config = {
+    /** Google Analytics 4 measurement ID, e.g. `G-XXXXXXX`. */
+    measurementId: string;
+    /**
+     * `'auto'` (default): GA4 records page views itself, including history changes when Enhanced Measurement is on.
+     * `'manual'`: only `analytics.page()` sends page views.
+     */
+    pageViews?: 'auto' | 'manual';
+    /** Set to `false` when the page already loads gtag.js. Defaults to `true`. */
+    loadScript?: boolean;
+    /** Your server-side GTM URL (https). Hits go there instead of Google, and events carry `event_id`. */
+    serverContainerUrl?: string;
+    /** 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 state. Required, so every site makes an explicit choice. */
+    /** Initial consent for every purpose. Required, so every site makes an explicit choice. */
     consent: ConsentStatus;
+    /**
+     * Honour the browser's Global Privacy Control signal by starting the advertising signals denied. Defaults to `true`.
+     * An explicit `analytics.consent.update()` still wins.
+     */
+    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. */
@@ -59,11 +124,16 @@ 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. */
     identify(userId: string, traits?: IdentityTraits): void;
     /** Forgets the identified user, e.g. on logout. */
     reset(): void;
+    consent: {
+        /** Records the visitor's choice, e.g. from your consent banner. Omitted purposes keep their current state. */
+        update(update: ConsentUpdate): void;
+        get(): ConsentState;
+    };
 };

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, ConsentStatus, Destination, EventParams, 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/ga4.d.ts

@@ -0,0 +1,6 @@
+import type { Destination, Ga4Config } from '../core/types.js';
+type Ga4DestinationOptions = Ga4Config & {
+    nonce?: string;
+};
+export declare const createGa4Destination: ({ measurementId, pageViews, loadScript, serverContainerUrl, waitForUpdate, nonce, }: Ga4DestinationOptions) => Destination;
+export {};

package/dist/destinations/googleTag.d.ts

@@ -0,0 +1,22 @@
+import type { ConsentState } from '../core/types.js';
+type Gtag = (...args: unknown[]) => void;
+export declare const dataLayer: () => unknown[];
+/**
+ * Whether the page already loads the gtag.js library (any stream, Google- or first-party-hosted). Checked by script rather
+ * than by `window.gtag`, because the Consent Mode default defines the gtag stub before any library loads.
+ */
+export declare const isGtagLibraryOnPage: () => boolean;
+/** The page's `gtag()`, defining Google's official command-queue stub when the page doesn't have one yet. */
+export declare const gtag: () => Gtag;
+/**
+ * Consent Mode v2 default. It must be queued before any config or container load. When a signal starts denied, tags
+ * wait `waitForUpdate` ms for the visitor's choice before firing.
+ */
+export declare const setDefaultConsent: ({ consent, waitForUpdate, }: {
+    consent: ConsentState;
+    waitForUpdate: number;
+}) => void;
+export declare const updateConsent: (consent: ConsentState) => void;
+/** Parses an option that must be an https:// URL, failing fast with the option's name. */
+export declare const toHttpsUrl: (value: string, option: string) => URL;
+export {};

package/dist/destinations/gtm.d.ts

@@ -2,5 +2,5 @@ import type { Destination, GtmConfig } from '../core/types.js';
 type GtmDestinationOptions = GtmConfig & {
     nonce?: string;
 };
-export declare const createGtmDestination: ({ containerId, loadScript, nonce, }: GtmDestinationOptions) => Destination;
+export declare const createGtmDestination: ({ containerId, loadScript, scriptUrl, waitForUpdate, nonce, }: GtmDestinationOptions) => Destination;
 export {};

package/dist/destinations/loadScript.d.ts

@@ -0,0 +1,6 @@
+export declare const isScriptOnPage: (src: string) => boolean;
+/** Appends an async vendor script, carrying the page's CSP nonce when there is one. */
+export declare const injectScript: ({ src, nonce, }: {
+    src: string;
+    nonce?: string;
+}) => void;

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.2",
+  "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/)",
@@ -63,21 +63,6 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   },
-  "browserslist": {
-    "production": [
-      ">0.2%",
-      "not dead",
-      "not op_mini all"
-    ],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
-  },
-  "dependencies": {
-    "device-detector-js": "^3.0.3"
-  },
   "peerDependencies": {
     "react": ">=18.0.0"
   },

package/dist/analytics/analyticsEventService.d.ts

@@ -1,13 +0,0 @@
-import { TrackAnalyticsEventOptions } from '../types/index.js';
-/**
- *
- * @paramType {object} options
- * @property {object} data this is an object of any data you want to collect in analytics
- * @property {object} eventNameInfo
- * @property {string} analyticsType
- * @property {array | undefined} userDataKeysToHashArray default for this value is null, when used it should include an array of strings you wish to hash.
- * @property {boolean} dataLayerCheck
- * @property {object} consoleLogData (optional) is an object with the following attributes, "showGlobalVars", "showJourneyPropsPayload", "showUserProps" if any of the values are true you will be able to see the respective payload in your console.
- */
-declare const trackAnalyticsEvent: (options: TrackAnalyticsEventOptions) => Promise<void>;
-export { trackAnalyticsEvent };

package/dist/analytics/ga4GoogleAnalyticsEventTracking.d.ts

@@ -1,3 +0,0 @@
-import { Ga4GoogleAnalyticsEventTracking } from '../types';
-declare const ga4GoogleAnalyticsEventTracking: (options: Ga4GoogleAnalyticsEventTracking) => Promise<void>;
-export default ga4GoogleAnalyticsEventTracking;

package/dist/analytics/handleDataLayerPush.d.ts

@@ -1,3 +0,0 @@
-import { HandleDataLayerPushOptions } from '../types';
-declare const handleDataLayerPush: (options: HandleDataLayerPushOptions) => Promise<void>;
-export default handleDataLayerPush;

package/dist/analytics/helpers.d.ts

@@ -1,41 +0,0 @@
-import DeviceDetector from 'device-detector-js';
-import { AllowedTypes, EventNameInfo } from '../types';
-/**
- *
- * @param {object} user the structure of this data is dictated by you, aka your API or DB.
- * @param {[string]} includeUserKeys is an array of strings that represent keys from your user data that you want to whitelist, the value for each key in the whitelist will be hashed.
- * @returns a new user object with all values hashed including only the whitelisted key value pairs
- */
-export declare const hashUserData: (user: Record<AllowedTypes, AllowedTypes>, includeUserKeys: Array<string>) => Promise<Record<AllowedTypes, AllowedTypes>>;
-/**
- *
- * @param {object} user the structure of this data is dictated by you, aka your API or DB.
- * @param {[string]} includeUserKeys is an array of strings that represent keys from your user data that you want to map over, if no keys are supplied the original passed in user data is returned.
- * @param {boolean} showMissingUserAttributesInConsole a boolean condition to show or hide "user" attributes that are not included in the "includeUserKeys" array, by console logging in dev tools.
- * @returns If no "includeUserKeys" are supplied the original ser object is returned, otherwise, a new user object with only the key value pairs that you included in your includeUserKeys array is returned.
- */
-export declare const buildNewUserData: (user: Record<AllowedTypes, AllowedTypes>, includeUserKeys: Array<string>, showMissingUserAttributesInConsole: boolean | undefined) => Record<string, string>;
-/**
- *
- * @paramType {Object} eventNameInfo
- * @property {analyticsPrefixActionList} actionPrefix either a built in value of JOURNEY | INTERACTION or a custom value added to the analyticsPrefixActionList object.
- * @property {string} description an OPTIONAL value passed in that is formatted like the following from 'Very descriptive description' to VERY_DESCRIPTIVE_DESCRIPTION.
- * @property {string} globalAppEvent the current event name for this track event selected from the analyticsGlobalEventActionList
- * @property {string} previousGlobalAppEvent an OPTIONAL value, the previous event name for this track event selected from the analyticsGlobalEventActionList.
- * @returns string eventName for this specific tracked event
- */
-export declare const buildAnalyticsEventName: (eventNameInfo: EventNameInfo) => string;
-/**
- *
- * @param {object} data
- * @param {string} globalAppEvent
- * @returns dataObject
- */
-export declare const buildEventDataObject: (data: Record<AllowedTypes, AllowedTypes>, globalAppEvent: string) => Promise<Record<AllowedTypes, AllowedTypes>>;
-/**
- *
- * @param {string} eventName
- * @returns a Boolean value, true if the event name is already in the dataLayer.
- */
-export declare const defaultDataLayerEventCheck: (eventName: string) => boolean;
-export declare const deviceDetectorInfo: (userAgent: string) => DeviceDetector.DeviceDetectorResult;

package/dist/buildConfig/index.d.ts

@@ -1,8 +0,0 @@
-import { BuildConfigOptions, Config, AnalyticsPlatform } from '../types/index.js';
-declare const analyticsPlatform: AnalyticsPlatform;
-declare const showMeBuildInAnalyticsPlatform: () => void;
-declare const showMeBuildInEventActionPrefixList: () => void;
-declare const showMeBuildInGlobalEventActionList: () => void;
-declare let config: Config;
-declare const buildConfig: (options: BuildConfigOptions) => void;
-export { config, analyticsPlatform, buildConfig, showMeBuildInAnalyticsPlatform, showMeBuildInGlobalEventActionList, showMeBuildInEventActionPrefixList, };

package/dist/ipInfo/index.d.ts

@@ -1,3 +0,0 @@
-import { IpInfo, ServerLocationData } from '../types';
-export declare const buildServerLocationData: (withServerLocationInfo: boolean | undefined, IP_INFO_TOKEN: string | undefined) => Promise<ServerLocationData | undefined>;
-export declare const getIpInfo: (IP_INFO_TOKEN: string) => Promise<IpInfo>;

package/dist/types/index.d.ts

@@ -1,130 +0,0 @@
-export interface AnalyticsEventActionPrefix extends Record<string, string> {
-}
-export interface AnalyticsGlobalEventAction extends Record<string, string> {
-}
-export type Event = {
-    name: string;
-    params: Record<AllowedTypes, AllowedTypes>;
-};
-export type GooglePayload = {
-    non_personalized_ads: boolean;
-    client_id: string;
-    user_id: string;
-    user_properties: {
-        user_id: string;
-        user_type: string;
-        client_id: string;
-    };
-    events: Event[];
-};
-export type EventNameInfo = {
-    eventName?: string;
-    description?: string;
-    actionPrefix: string;
-    globalAppEvent: string;
-    previousGlobalAppEvent?: string;
-};
-export type AllowedTypes = string | number;
-export type TrackAnalyticsEventOptions = {
-    data: Record<AllowedTypes, AllowedTypes>;
-    eventNameInfo: EventNameInfo;
-    analyticsType: string;
-    userDataKeysToHashArray?: Array<string> | null;
-    dataLayerCheck?: boolean;
-    consoleLogData?: object;
-};
-export type GlobalVars = {
-    app: string;
-    device_category?: string | undefined;
-    device_os?: string | undefined;
-    device_browser?: string | undefined;
-};
-export type DataLayer = {
-    event: string;
-    globalVars: GlobalVars;
-    journeyProps: Record<any, any>;
-    userProps: Record<any, any>;
-};
-export type ConsoleLogData = {
-    showGlobalVars?: boolean;
-    showJourneyPropsPayload?: boolean;
-    showUserProps?: boolean;
-};
-export interface AnalyticsTrackerDataOptions {
-    consoleLogData: ConsoleLogData | null;
-    data: Record<any, any>;
-    eventName: string;
-    globalAppEvent: string;
-    userDetails: Record<any, any>;
-}
-export interface HandleDataLayerPushOptions extends AnalyticsTrackerDataOptions {
-    dataLayerCheck: boolean;
-}
-export type ServerLocationData = {
-    SERVER_CITY: string;
-    SERVER_COUNTRY: string;
-    SERVER_HOSTNAME: string;
-    SERVER_IP: string;
-    SERVER_LOCATION: string;
-    SERVER_POSTAL: string;
-    SERVER_REGION: string;
-    SERVER_TIMEZONE: string;
-};
-export type IpInfo = {
-    city: string;
-    country: string;
-    SERVER_HOSTNAME: string;
-    hostname: string;
-    ip: string;
-    loc: string;
-    postal: string;
-    region: string;
-    timezone: string;
-};
-export type Ga4GoogleAnalyticsEventTracking = AnalyticsTrackerDataOptions;
-export type Platform = 'GOOGLE' | 'FACEBOOK' | 'DATALAYER_PUSH';
-export type AnalyticsPlatform = {
-    [key in Platform]: Platform;
-};
-export type Tokens = {
-    IP_INFO_TOKEN?: string;
-    GA4_PUBLIC_API_SECRET?: string;
-    GA4_PUBLIC_MEASUREMENT_ID?: string;
-};
-export type Config = {
-    TOKENS?: Tokens;
-    appName: string;
-    appSessionCookieName: string;
-    withDeviceInfo?: boolean;
-    includeUserKeys: Array<string>;
-    showMissingUserAttributesInConsole: boolean | undefined;
-    withServerLocationInfo: boolean | undefined;
-    eventActionPrefixList: AnalyticsEventActionPrefix;
-    analyticsGlobalEventActionList: AnalyticsGlobalEventAction;
-};
-export type BuildConfigOptions = {
-    appName: string;
-    appSessionCookieName: string;
-    eventActionPrefix?: AnalyticsEventActionPrefix;
-    globalEventActionList?: AnalyticsGlobalEventAction;
-    includeUserKeys?: Array<string> | undefined;
-    showMissingUserAttributesInConsole?: boolean;
-    showMeBuildInEventActionPrefixList?: boolean;
-    TOKENS?: Tokens;
-    withDeviceInfo?: boolean;
-    withServerLocationInfo?: boolean;
-};
-export declare let config: Config;
-export type ProviderStateProps = {
-    appName: string;
-    appSessionCookieName: string;
-    analyticsPlatform: AnalyticsPlatform;
-    eventActionPrefixList: AnalyticsEventActionPrefix;
-    analyticsGlobalEventActionList: AnalyticsGlobalEventAction;
-};
-export type ProviderApiProps = {
-    trackAnalyticsEvent: (options: TrackAnalyticsEventOptions) => Promise<void>;
-    showMeBuildInAnalyticsPlatform: () => void;
-    showMeBuildInEventActionPrefixList: () => void;
-    showMeBuildInGlobalEventActionList: () => void;
-};

package/dist/utilities/assertValueCheckers.d.ts

@@ -1 +0,0 @@
-export declare const assertIsTrue: (condition: boolean, errorMessage?: string) => void;

package/dist/utilities/commonFunctions.d.ts

@@ -1,5 +0,0 @@
-export declare const isClientSide: () => boolean;
-export declare const objectHasAttributes: (obj: object, key?: string) => boolean;
-export declare const replaceWhiteSpace: (stringValue: string, replaceValue: string) => string;
-export declare const checkAllArrayValuesReturnTrue: (valueArray: boolean[]) => boolean;
-export declare const hashString: (value: string) => Promise<string>;

package/dist/utilities/cookies.d.ts

@@ -1 +0,0 @@
-export declare const getCookieValueByName: (name: string) => string | undefined;