react-marketing-tools 1.0.0-alpha.0 → 1.0.0-alpha.1

package/dist/core/errors.d.ts

@@ -0,0 +1,8 @@
+export type AnalyticsErrorCode = 'invalid_event' | 'invalid_param' | 'invalid_user_id' | '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;
+    constructor(code: AnalyticsErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/core/types.d.ts

@@ -1,3 +1,4 @@
+import type { AnalyticsError } from './errors.js';
 export type ConsentStatus = 'granted' | 'denied';
 /** Event parameters, passed to every destination as-is. */
 export type EventParams = Record<string, unknown>;
@@ -9,12 +10,31 @@ export type AnalyticsEvent = {
     /** Milliseconds since the Unix epoch at the moment `track()` was called. */
     timestamp: number;
 };
+/**
+ * Personal data about the identified user. It is only given to destinations that match users with it (hashed by the
+ * vendor or on your server). It is never added to event params or the dataLayer.
+ */
+export type IdentityTraits = {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+};
+export type Identity = {
+    userId: string;
+    traits: IdentityTraits;
+};
 /** 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;
     track(event: AnalyticsEvent): void;
+    /** Receives `page_view` events. Destinations without it get them through `track`. */
+    page?(event: AnalyticsEvent): void;
+    identify?(identity: Identity): void;
+    /** Forget the identified user, e.g. on logout. */
+    reset?(): void;
 };
 export type GtmConfig = {
     /** Google Tag Manager container ID, e.g. `GTM-XXXXXXX`. */
@@ -30,10 +50,20 @@ export type AnalyticsConfig = {
     destinations?: Destination[];
     /** Content-Security-Policy nonce added to every script the library injects. */
     nonce?: string;
+    /** Throw on invalid events and personal data instead of reporting them. Turn on in development. */
+    debug?: boolean;
+    /** Receives every problem the library reports. Defaults to `console.error`. */
+    onError?: (error: AnalyticsError) => void;
 };
 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;
+    /** 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;
 };

package/dist/core/validate.d.ts

@@ -0,0 +1,15 @@
+import type { EventParams } from './types.js';
+export declare const REDACTED = "[redacted]";
+/** Why `name` can't be used as an event name, or `undefined` when it can. */
+export declare const findEventNameProblem: (name: string) => string | undefined;
+/** Param problems GA4 would handle by truncating or ignoring; reported, but the event is still sent. */
+export declare const findParamProblems: (params: EventParams) => string[];
+export declare const containsEmail: (value: string) => boolean;
+/**
+ * Removes personal data from top-level params: deny-listed keys lose their whole value, and email addresses are replaced
+ * inside any string. Booleans and nested values are left alone.
+ */
+export declare const redactPii: (params: EventParams) => {
+    params: EventParams;
+    redactedKeys: string[];
+};

package/dist/core.d.ts

@@ -1,2 +1,4 @@
 export { createAnalytics } from './core/createAnalytics.js';
-export type { Analytics, AnalyticsConfig, AnalyticsEvent, ConsentStatus, Destination, EventParams, GtmConfig, } from './core/types.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';

package/dist/core.js

@@ -23,37 +23,132 @@ var e = /^GTM-[A-Z0-9]+$/, t = () => window.dataLayer ??= [], n = (e) => Array.f
 				event: e,
 				event_id: r
 			});
+		},
+		identify({ userId: e }) {
+			t().push({
+				event: "identify",
+				user_id: e
+			});
+		},
+		reset() {
+			t().push({
+				event: "reset",
+				user_id: void 0
+			});
 		}
 	};
-}, a = () => typeof window < "u", o = () => 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) => {
+}, a = 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 = [
+	"google_",
+	"ga_",
+	"firebase_"
+], c = 25, l = 100, u = {
+	page_location: 1e3,
+	page_referrer: 420,
+	page_title: 300
+}, d = [
+	"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));
+	return t && `must not start with the reserved prefix "${t}"`;
+}, h = (e) => {
+	let t = m(e);
+	return t && `event name "${e}" ${t}`;
+}, g = (e) => {
+	let t = Object.keys(e), n = t.flatMap((t) => {
+		let n = m(t);
+		if (n) return [`param "${t}" ${n}`];
+		let r = e[t], i = u[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) => {
+	let t = Object.entries(e).map(([e, t]) => [
+		e,
+		t,
+		v(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) => {
 	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 t = [...e.gtm ? [i({
+}, C = (e) => {
+	S(e);
+	let { debug: t = !1, onError: n = console.error } = e, r = [...e.gtm ? [i({
 		...e.gtm,
 		nonce: e.nonce
-	})] : [], ...e.destinations ?? []], n = [], r = !1, c = (e) => {
-		for (let n of t) n.track(e);
+	})] : [], ...e.destinations ?? []], o = [], s = !1, c = (e) => {
+		if (t) throw e;
+		n(e);
+	}, l = (e) => {
+		for (let t of r) try {
+			e(t);
+		} catch (e) {
+			n(new a("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));
+			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(", ")}`)), {
+			name: e,
+			params: r,
+			eventId: x(),
+			timestamp: Date.now()
+		};
 	};
 	return {
 		start() {
-			if (!r && a()) {
-				r = !0;
-				for (let e of t) e.start();
-				n.splice(0).forEach(c);
-			}
+			!s && b() && (s = !0, l((e) => e.start()), o.splice(0).forEach(l));
 		},
 		track(e, t = {}) {
-			if (!a()) return;
-			let i = {
-				name: e,
-				params: t,
-				eventId: o(),
-				timestamp: Date.now()
-			};
-			r ? c(i) : n.push(i);
+			if (!b()) return;
+			let n = d(e, t);
+			n && u((e) => e.track(n));
+		},
+		page(e = {}) {
+			if (!b()) return;
+			let t = d("page_view", {
+				page_location: location.href,
+				page_title: document.title,
+				...e
+			});
+			t && u((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
+				}));
+			}
+		},
+		reset() {
+			b() && u((e) => e.reset?.());
 		}
 	};
 };
 //#endregion
-export { c as createAnalytics };
+export { a as AnalyticsError, C as createAnalytics };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-marketing-tools",
   "type": "module",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.1",
   "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/)",