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

package/dist/core/createAnalytics.d.ts

@@ -0,0 +1,6 @@
+import type { Analytics, AnalyticsConfig } from './types.js';
+/**
+ * Creates an analytics instance. It has no side effects until `start()`, so it is safe to create at module scope and
+ * during server rendering.
+ */
+export declare const createAnalytics: (config: AnalyticsConfig) => Analytics;

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

@@ -0,0 +1,69 @@
+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>;
+export type AnalyticsEvent = {
+    name: string;
+    params: EventParams;
+    /** 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. */
+    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`. */
+    containerId: string;
+    /** Set to `false` when the page already includes the GTM snippet. Defaults to `true`. */
+    loadScript?: boolean;
+};
+export type AnalyticsConfig = {
+    /** Initial consent state. Required, so every site makes an explicit choice. */
+    consent: ConsentStatus;
+    gtm?: GtmConfig;
+    /** Custom destinations, in addition to the built-in ones. */
+    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

@@ -0,0 +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';

package/dist/core.js

@@ -0,0 +1,154 @@
+//#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 }) => {
+	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}`;
+	return {
+		name: "gtm",
+		start() {
+			let e = t();
+			a && !n(s) && (e.push({
+				"gtm.start": Date.now(),
+				event: "gtm.js"
+			}), r({
+				src: s,
+				nonce: o
+			}));
+		},
+		track({ name: e, params: n, eventId: r }) {
+			t().push({
+				...n,
+				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 = 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 { 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 {
+			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() {
+			!s && b() && (s = !0, l((e) => e.start()), o.splice(0).forEach(l));
+		},
+		track(e, t = {}) {
+			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 { a as AnalyticsError, C as createAnalytics };

package/dist/destinations/gtm.d.ts

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-marketing-tools",
   "type": "module",
-  "version": "0.4.4",
+  "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/)",
@@ -29,26 +29,30 @@
     "pixel",
     "dataLayer"
   ],
-  "main": "./dist/react-marketing-tools.umd.cjs",
-  "module": "./dist/react-marketing-tools.es.js",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/react-marketing-tools.es.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/react-marketing-tools.umd.cjs"
-      }
-    }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./package.json": "./package.json"
   },
   "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "tag": "next"
+  },
   "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json && node scripts/emit-cts-types.mjs && node scripts/copy-legacy-umd.mjs",
+    "build": "vite build && tsc -p tsconfig.build.json",
     "build:watch": "vite build --watch",
-    "check:package": "publint --strict && attw --pack .",
+    "check:package": "publint --strict && attw --pack . --profile esm-only",
     "check:size": "node scripts/check-size.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",

package/dist/analytics/analyticsEventService.d.cts

@@ -1,13 +0,0 @@
-import { TrackAnalyticsEventOptions } from '../types/index.cjs';
-/**
- *
- * @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.cts

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

package/dist/analytics/handleDataLayerPush.d.cts

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

package/dist/analytics/helpers.d.cts

@@ -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.cts

@@ -1,8 +0,0 @@
-import { BuildConfigOptions, Config, AnalyticsPlatform } from '../types/index.cjs';
-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/index.d.cts

@@ -1,26 +0,0 @@
-import { ReactElement, ReactNode, Context } from 'react';
-import type { ProviderStateProps, ProviderApiProps } from './types/index.cjs';
-export type { Event, GooglePayload, EventNameInfo, AllowedTypes, TrackAnalyticsEventOptions, GlobalVars, DataLayer, ConsoleLogData, AnalyticsTrackerDataOptions, HandleDataLayerPushOptions, ServerLocationData, IpInfo, Ga4GoogleAnalyticsEventTracking, Platform, AnalyticsPlatform, Tokens, Config, BuildConfigOptions, ProviderStateProps, ProviderApiProps, AnalyticsEventActionPrefix, AnalyticsGlobalEventAction, } from './types/index.cjs';
-export { config, analyticsPlatform, buildConfig, showMeBuildInAnalyticsPlatform, showMeBuildInGlobalEventActionList, showMeBuildInEventActionPrefixList, } from './buildConfig/index.cjs';
-export { trackAnalyticsEvent } from './analytics/analyticsEventService.cjs';
-export declare const ContextState: Context<ProviderStateProps>;
-export declare const ContextApi: Context<ProviderApiProps>;
-type ReactMarketingProviderProps = {
-    children: ReactNode;
-};
-export declare const ReactMarketingProvider: ({ children, }: ReactMarketingProviderProps) => ReactElement;
-/**
- * @property {string} appName
- * @property {string} appSessionCookieName
- * @property {AnalyticsPlatform} analyticsPlatform
- * @property {AnalyticsEventActionPrefix} eventActionPrefixList
- * @property {AnalyticsGlobalEventAction} analyticsGlobalEventActionList
- */
-export declare const useMarketingState: () => ProviderStateProps;
-/**
- * @property {function} trackAnalyticsEvent(options)
- * @property {function} showMeBuildInAnalyticsPlatform
- * @property {function} showMeBuildInEventActionPrefixList
- * @property {function} showMeBuildInGlobalEventActionList
- */
-export declare const useMarketingApi: () => ProviderApiProps;

package/dist/ipInfo/index.d.cts

@@ -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>;