react-marketing-tools 1.0.0-alpha.5 → 1.0.0

package/dist/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type AnalyticsErrorCode = 'invalid_event' | 'invalid_param' | 'invalid_user_id' | 'invalid_consent' | 'pii_redacted' | 'destination_failed';
+export type AnalyticsErrorCode = 'invalid_event' | 'invalid_param' | 'invalid_user_id' | 'invalid_consent' | 'pii_redacted' | 'destination_failed' | 'visitor_id_failed' | 'journey_ended';
 /** 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

@@ -15,19 +15,30 @@ export type ConsentUpdate = Partial<ConsentState>;
 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?: {
+    /**
+     * Meta Pixel and the relay: send as this event name (standard or custom), with these params merged over the mapped
+     * ones, or `false` to keep the event away from Meta.
+     */
+    meta?: false | {
         event?: string;
         params?: EventParams;
     };
 };
 export type CampaignParam = 'utm_source' | 'utm_medium' | 'utm_campaign' | 'utm_term' | 'utm_content' | 'utm_id' | 'utm_source_platform' | 'utm_creative_format' | 'utm_marketing_tactic' | 'gclid' | 'gbraid' | 'wbraid' | 'dclid' | 'fbclid' | 'msclkid' | 'ttclid' | 'li_fat_id' | 'twclid';
+/**
+ * Labels for visits that arrive from AI assistants, as `{ label: [hostname, …] }`, for example
+ * `{ chatgpt: ['chatgpt.com', 'chat.openai.com'], perplexity: ['perplexity.ai'] }`. A referrer matches a hostname
+ * exactly or as a subdomain of it. The list is yours to keep up to date: the library ships none.
+ */
+export type AiSources = Record<string, string[]>;
 /** Where a visit came from: the campaign params and ad click IDs of its landing URL. */
 export type Attribution = Partial<Record<CampaignParam, string>> & {
     /** Origin and path of the landing page, without its query string. */
     landing_page: string;
     /** Origin and path of the referring page, when there was one. */
     referrer?: string;
+    /** Your label for the AI assistant this visit came from, when the referrer matched `attribution.aiSources`. */
+    ai_source?: string;
     /** Milliseconds since the Unix epoch when the visit was captured. */
     captured_at: number;
 };
@@ -122,6 +133,33 @@ export type MetaPixelConfig = {
     /** Set to `false` when the page already includes the Meta Pixel base code. Defaults to `true`. */
     loadScript?: boolean;
 };
+/**
+ * A multi-step flow, such as a checkout. Its first call also sends `journey_start`; every event carries `journey_id` and
+ * `journey_name`.
+ */
+export type Journey = {
+    /** Sends `journey_step` with `step_name` and `step_index` (1 for the first step). */
+    step(stepName: string, params?: EventParams): void;
+    /** Sends `journey_complete` with `step_count`. The journey then ends. */
+    complete(params?: EventParams): void;
+    /** Sends `journey_abandon` with `step_count`, the last `step_name` and `reason`. The journey then ends. */
+    abandon(reason?: string): void;
+};
+export type ServerRelayConfig = {
+    /**
+     * Where to post events for your `createTrackHandler()` endpoint, which forwards them to the Meta Conversions API with
+     * the Pixel's event ID. A path on your site (`'/api/track'`) or an https URL.
+     */
+    endpoint: string;
+};
+/**
+ * How the visitor ID is made. `'random'`: a random ID kept in the browser's storage, with analytics consent.
+ * `{ fingerprint }`: your function's browser fingerprint, with analytics and advertising consent, never stored.
+ * `false`: no visitor ID.
+ */
+export type VisitorIdConfig = 'random' | false | {
+    fingerprint: () => Promise<string>;
+};
 export type AnalyticsConfig = {
     /** Initial consent for every purpose. Required, so every site makes an explicit choice. */
     consent: ConsentStatus;
@@ -132,14 +170,24 @@ export type AnalyticsConfig = {
     respectGpc?: boolean;
     /**
      * Capture UTM params and ad click IDs from landing URLs. Defaults to `true`. First and last touch are stored in the
-     * browser only with analytics consent; `ttlDays` (default 90) is how long a first touch is kept.
+     * browser only with analytics consent; `ttlDays` (default 90) is how long a first touch is kept. `aiSources` labels
+     * visits that arrive from AI assistants.
      */
     attribution?: boolean | {
         ttlDays?: number;
+        aiSources?: AiSources;
+    };
+    /** A stable ID for this visitor, only with consent and never sent to GA4. Defaults to `'random'`. */
+    visitorId?: VisitorIdConfig;
+    /** `clicks`: track clicks on elements with a `data-analytics-event` attribute. Off by default. */
+    autocapture?: {
+        clicks?: boolean;
     };
     gtm?: GtmConfig;
     ga4?: Ga4Config;
     metaPixel?: MetaPixelConfig;
+    /** Relays events to your server for the Meta Conversions API. Only with `adUserData` consent. */
+    server?: ServerRelayConfig;
     /** Custom destinations, in addition to the built-in ones. */
     destinations?: Destination[];
     /** Content-Security-Policy nonce added to every script the library injects. */
@@ -156,12 +204,19 @@ export type Analytics = {
     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;
+    /** Starts tracking a multi-step flow. Create it once per flow (not on every render): each journey has its own ID. */
+    journey(name: string): Journey;
     /** 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;
     /** Campaign attribution for this visitor. Empty outside the browser. */
     getAttribution(): AttributionSnapshot;
+    /**
+     * This visitor's ID, once `start()` has run. `undefined` without the consent it needs, with `visitorId: false`, or
+     * outside the browser.
+     */
+    getVisitorId(): Promise<string | undefined>;
     consent: {
         /** Records the visitor's choice, e.g. from your consent banner. Omitted purposes keep their current state. */
         update(update: ConsentUpdate): void;

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, Attribution, AttributionSnapshot, CampaignParam, ConsentState, ConsentStatus, ConsentUpdate, Destination, EventParams, Ga4Config, GtmConfig, Identity, IdentityTraits, MetaPixelConfig, TrackOptions, } from './core/types.js';
+export type { AiSources, Analytics, AnalyticsConfig, AnalyticsEvent, Attribution, AttributionSnapshot, CampaignParam, ConsentState, ConsentStatus, ConsentUpdate, Destination, EventParams, Ga4Config, GtmConfig, Identity, IdentityTraits, Journey, MetaPixelConfig, ServerRelayConfig, TrackOptions, VisitorIdConfig, } from './core/types.js';

package/dist/destinations/serverRelay.d.ts

@@ -0,0 +1,34 @@
+import { AnalyticsError } from '../core/errors.js';
+import type { ConsentStatus, Destination, EventParams, ServerRelayConfig } from '../core/types.js';
+export type RelayUserData = {
+    externalId?: string;
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    fbc?: string;
+    fbp?: string;
+};
+/** The body posted to your endpoint and read by `createTrackHandler()`. Versioned, so pages cached before a change keep working. */
+export type RelayPayload = {
+    v: 1;
+    /** The name the Pixel received: Meta only deduplicates events whose name and ID both match. */
+    eventName: string;
+    /** The Pixel's `eventID`. */
+    eventId: string;
+    customData: EventParams;
+    eventSourceUrl: string;
+    consent: {
+        adUserData: ConsentStatus;
+    };
+    userData: RelayUserData;
+};
+type ServerRelayOptions = ServerRelayConfig & {
+    /** Off when the Pixel sends its own page views: they carry no event ID, so relayed ones would be counted twice. */
+    relayPageViews: boolean;
+    /** The visitor ID, if it's allowed and available: Meta's `external_id` for a visitor who isn't identified. */
+    visitorId: () => string | undefined;
+    onError: (error: AnalyticsError) => void;
+};
+export declare const createServerRelayDestination: ({ endpoint, relayPageViews, visitorId, onError, }: ServerRelayOptions) => Destination;
+export {};

package/dist/fingerprintjs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A browser fingerprint from FingerprintJS, for `visitorId: { fingerprint: fingerprintjs() }`. Install the MIT-licensed
+ * v5 first: `npm install @fingerprintjs/fingerprintjs@^5` (4.x is under a non-open-source licence).
+ *
+ * FingerprintJS is loaded the first time the library asks for a visitor ID, which is only with the visitor's analytics
+ * and advertising consent, so apps that never get consent never download it.
+ */
+export declare const fingerprintjs: () => (() => Promise<string>);

package/dist/fingerprintjs.js

@@ -0,0 +1,7 @@
+//#region lib/fingerprintjs.ts
+var e = () => async () => {
+	let { load: e } = await import("@fingerprintjs/fingerprintjs"), { visitorId: t } = await (await e({ monitoring: !1 })).get();
+	return t;
+};
+//#endregion
+export { e as fingerprintjs };

package/dist/identity/visitorId.d.ts

@@ -0,0 +1,14 @@
+import { AnalyticsError } from '../core/errors.js';
+import type { ConsentState, VisitorIdConfig } from '../core/types.js';
+/** The caller decides when this may run: after `start()`, and it passes the current consent on every call. */
+export type VisitorIdSource = {
+    /** The ID if it's available right now: the random ID (created on first use), or a fingerprint already computed. */
+    peek(consent: ConsentState): string | undefined;
+    get(consent: ConsentState): Promise<string | undefined>;
+    /** Forgets the ID, when analytics consent is withdrawn. */
+    erase(): void;
+};
+export declare const createVisitorIdSource: ({ config, onError, }: {
+    config: VisitorIdConfig;
+    onError: (error: AnalyticsError) => void;
+}) => VisitorIdSource | undefined;

package/dist/journeys/journey.d.ts

@@ -0,0 +1,8 @@
+import { AnalyticsError } from '../core/errors.js';
+import type { EventParams, Journey } from '../core/types.js';
+/** A journey built only on `track`, so every destination, validation rule and the relay apply to its events. */
+export declare const createJourney: ({ name, track, fail, }: {
+    name: string;
+    track: (eventName: string, params: EventParams) => void;
+    fail: (error: AnalyticsError) => void;
+}) => Journey;

package/dist/server/aiCrawlers.d.ts

@@ -0,0 +1,37 @@
+import type { MeasurementProtocolOptions, MeasurementProtocolResult } from './measurementProtocol.js';
+/**
+ * The AI crawlers you want to recognise, as `{ label: [user-agent fragment, …] }`, for example
+ * `{ gptbot: ['GPTBot'], claudebot: ['ClaudeBot'] }`. Matching ignores case. The list is yours to keep up to date:
+ * crawlers come and go, so the library ships none.
+ */
+export type AiAgents = Record<string, string[]>;
+/**
+ * How this traffic is kept out of your visitor reports. Crawler hits are not people, and mixing them in inflates every
+ * number you report.
+ *
+ * - `'separate-property'`: `measurementId` is a GA4 property used only for crawlers.
+ * - `{ trafficType }`: the events carry that `traffic_type` value, and you exclude it with a data filter in
+ *   **Admin → Data settings → Data filters** of the property you send to.
+ */
+export type AiCrawlerReporting = 'separate-property' | {
+    trafficType: string;
+};
+export type AiCrawlerOptions = Omit<MeasurementProtocolOptions, 'consent'> & {
+    /** Your label for the crawler, from `matchAiAgent()`. */
+    agent: string;
+    keepSeparate: AiCrawlerReporting;
+};
+/** Your label for the crawler behind a user agent, or undefined when it isn't one you listed. */
+export declare const matchAiAgent: ({ userAgent, agents, }: {
+    userAgent: string;
+    agents: AiAgents;
+}) => string | undefined;
+/**
+ * Sends a crawler's visit to GA4, tagged so it can never be mistaken for a person: every event carries your `ai_agent`
+ * label and a `traffic_type`. You must say how the traffic is kept separate, because crawler hits in a visitor property
+ * quietly ruin sessions, engagement and conversion rates.
+ *
+ * Crawlers have no GA4 cookie, so pick the `clientId` yourself: one per crawler (`crawler.gptbot`) counts each crawler
+ * as one visitor, a random one per request counts every fetch separately.
+ */
+export declare const sendAiCrawlerEvent: (options: AiCrawlerOptions) => Promise<MeasurementProtocolResult>;

package/dist/server/conversionsApi.d.ts

@@ -0,0 +1,38 @@
+import type { EventParams } from '../core/types.js';
+import { type ConversionsApiUserData } from './normalize.js';
+/** Graph API version used unless a call passes `graphApiVersion`. */
+export declare const META_GRAPH_API_VERSION = "v26.0";
+export type ConversionsApiEvent = {
+    /** A Meta standard event (`Purchase`, `Lead`, …) or a custom name. */
+    eventName: string;
+    /** The Pixel's `eventID` for the same action, so Meta counts it once. */
+    eventId?: string;
+    /** Defaults to now. */
+    eventTime?: Date;
+    /** Defaults to `'website'`. */
+    actionSource?: 'website' | 'app' | 'email' | 'phone_call' | 'chat' | 'physical_store' | 'system_generated' | 'business_messaging' | 'other';
+    /** Required for website events: the page URL. */
+    eventSourceUrl?: string;
+    userData: ConversionsApiUserData;
+    /** `value`, `currency`, `content_ids`, `contents`… */
+    customData?: EventParams;
+};
+export type ConversionsApiOptions = {
+    pixelId: string;
+    /** Keep it on your server, e.g. `process.env.META_CAPI_TOKEN`. */
+    accessToken: string;
+    events: ConversionsApiEvent[];
+    /** From Events Manager → Test events, to see the events there. Remove it in production. */
+    testEventCode?: string;
+    graphApiVersion?: string;
+};
+export type ConversionsApiResult = {
+    ok: boolean;
+    status: number;
+    /** Meta's response, e.g. `{ events_received: 1, fbtrace_id: '…' }` or `{ error: … }`. */
+    body: unknown;
+    /** Personal data removed from `customData`. */
+    warnings: string[];
+};
+/** Sends events to Meta from your server. Customer information is normalised and hashed as Meta requires. */
+export declare const sendConversionsApiEvent: (options: ConversionsApiOptions) => Promise<ConversionsApiResult>;

package/dist/server/createTrackHandler.d.ts

@@ -0,0 +1,20 @@
+export type TrackHandlerOptions = {
+    /** Sites allowed to send events, e.g. `['https://shop.example.com']`. Other origins get 403. */
+    allowedOrigins: string[];
+    meta: {
+        pixelId: string;
+        /** Keep it on your server, e.g. `process.env.META_CAPI_TOKEN`. */
+        accessToken: string;
+        /** From Events Manager → Test events, to see the events there. Remove it in production. */
+        testEventCode?: string;
+        graphApiVersion?: string;
+    };
+    /** Receives Meta's rejections and network failures. Defaults to `console.error`. */
+    onError?: (error: Error) => void;
+};
+/**
+ * A Web-standard `(Request) => Response` endpoint for the `server` destination: it forwards each relayed Pixel event to
+ * the Meta Conversions API with the same event ID, so Meta counts it once. Events are never forwarded to GA4, which
+ * can't deduplicate them.
+ */
+export declare const createTrackHandler: (options: TrackHandlerOptions) => ((request: Request) => Promise<Response>);

package/dist/server/ga4Cookies.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The GA4 client and session IDs from the browser's `_ga` and `_ga_<stream>` cookies, as sent to your server in the
+ * `Cookie` header. Needed for Measurement Protocol events to join the visitor's existing GA4 session.
+ */
+export declare const readGa4Cookies: ({ cookieHeader, measurementId, }: {
+    cookieHeader: string;
+    measurementId: string;
+}) => {
+    clientId?: string;
+    sessionId?: string;
+};

package/dist/server/measurementProtocol.d.ts

@@ -0,0 +1,34 @@
+import type { ConsentStatus, EventParams } from '../core/types.js';
+export type MeasurementProtocolEvent = {
+    name: string;
+    params?: EventParams;
+};
+export type MeasurementProtocolOptions = {
+    measurementId: string;
+    /** Keep it on your server: Google says the API secret must not be exposed in client-side code. */
+    apiSecret: string;
+    /** The visitor's GA4 client ID, from the `_ga` cookie (see `readGa4Cookies`). */
+    clientId: string;
+    /** The visitor's GA4 session ID, from the `_ga_<stream>` cookie, so events join their session. */
+    sessionId?: string;
+    userId?: string;
+    /** Up to 25 events. Each gets `session_id` and `engagement_time_msec` (1 ms unless the params set it). */
+    events: MeasurementProtocolEvent[];
+    consent?: {
+        adUserData?: ConsentStatus;
+        adPersonalization?: ConsentStatus;
+    };
+    /** Send to the validation endpoint instead: nothing is recorded, and GA4's findings come back as `validationMessages`. */
+    validate?: boolean;
+    region?: 'global' | 'eu';
+};
+export type MeasurementProtocolResult = {
+    /** The request was accepted (GA4 accepts malformed payloads too; use `validate` to check them). */
+    ok: boolean;
+    status: number;
+    /** GA4 limit problems and personal data removed from params. */
+    warnings: string[];
+    validationMessages?: unknown[];
+};
+/** Sends events to GA4 from your server, e.g. a purchase confirmed by a payment webhook. */
+export declare const sendMeasurementProtocolEvent: (options: MeasurementProtocolOptions) => Promise<MeasurementProtocolResult>;

package/dist/server/normalize.d.ts

@@ -0,0 +1,19 @@
+export type ConversionsApiUserData = {
+    email?: string;
+    /** Include the country code, e.g. `+44 7700 900123`. */
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    /** Your own user ID. */
+    externalId?: string;
+    /** The visitor's IP address, e.g. from your request. */
+    clientIpAddress?: string;
+    /** The visitor's User-Agent header. */
+    clientUserAgent?: string;
+    /** Meta click ID (`_fbc` cookie, or `getAttribution().fbc`). */
+    fbc?: string;
+    /** Meta browser ID (`_fbp` cookie, or `getAttribution().fbp`). */
+    fbp?: string;
+};
+/** Meta `user_data`: identifiers normalised and SHA-256 hashed (already-hashed values kept), browser signals as they are. */
+export declare const toMetaUserData: (userData: ConversionsApiUserData) => Promise<Record<string, string>>;

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+export { META_GRAPH_API_VERSION, sendConversionsApiEvent, } from './server/conversionsApi.js';
+export type { ConversionsApiEvent, ConversionsApiOptions, ConversionsApiResult, } from './server/conversionsApi.js';
+export { matchAiAgent, sendAiCrawlerEvent } from './server/aiCrawlers.js';
+export type { AiAgents, AiCrawlerOptions, AiCrawlerReporting, } from './server/aiCrawlers.js';
+export { createTrackHandler } from './server/createTrackHandler.js';
+export type { TrackHandlerOptions } from './server/createTrackHandler.js';
+export { readGa4Cookies } from './server/ga4Cookies.js';
+export { sendMeasurementProtocolEvent } from './server/measurementProtocol.js';
+export type { MeasurementProtocolEvent, MeasurementProtocolOptions, MeasurementProtocolResult, } from './server/measurementProtocol.js';
+export type { ConversionsApiUserData } from './server/normalize.js';

package/dist/server.js

@@ -0,0 +1,252 @@
+import { a as e, i as t, n, r, t as i } from "./chunks/cookies.js";
+//#region lib/shared/hash.ts
+var a = async (e) => {
+	let t = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(e));
+	return Array.from(new Uint8Array(t), (e) => e.toString(16).padStart(2, "0")).join("");
+}, o = /^[a-f0-9]{64}$/, s = (e) => o.test(e), c = (e) => e.trim().toLowerCase().replace(/[^\p{L}\p{M}]/gu, ""), l = {
+	em: {
+		from: "email",
+		normalize: (e) => e.trim().toLowerCase()
+	},
+	ph: {
+		from: "phone",
+		normalize: (e) => e.replace(/\D/g, "").replace(/^0+/, "")
+	},
+	fn: {
+		from: "firstName",
+		normalize: c
+	},
+	ln: {
+		from: "lastName",
+		normalize: c
+	},
+	external_id: {
+		from: "externalId",
+		normalize: (e) => e.trim()
+	}
+}, u = {
+	client_ip_address: "clientIpAddress",
+	client_user_agent: "clientUserAgent",
+	fbc: "fbc",
+	fbp: "fbp"
+}, d = async (e) => {
+	let t = await Promise.all(Object.entries(l).map(async ([t, { from: n, normalize: r }]) => {
+		let i = e[n];
+		if (!i) return [];
+		if (s(i)) return [[t, i]];
+		let o = r(i);
+		return o ? [[t, await a(o)]] : [];
+	})), n = Object.entries(u).flatMap(([t, n]) => e[n] ? [[t, e[n]]] : []);
+	return Object.fromEntries([...t.flat(), ...n]);
+}, f = "v26.0", p = /^\d+$/, m = 1e3, h = (e) => /* @__PURE__ */ TypeError(`[react-marketing-tools] sendConversionsApiEvent: ${e}`), g = ({ pixelId: e, accessToken: t, events: n }) => {
+	if (!p.test(e)) throw h(`pixelId must be the numeric pixel ID (received ${JSON.stringify(e)})`);
+	if (!t) throw h("accessToken is required");
+	if (n.length === 0 || n.length > m) throw h(`send between 1 and ${m} events per request (received ${n.length})`);
+	for (let e of n) {
+		if (!e.eventName) throw h("every event needs an eventName");
+		if ((e.actionSource ?? "website") === "website" && !(e.eventSourceUrl && e.userData.clientUserAgent)) throw h(`website event "${e.eventName}" needs eventSourceUrl and userData.clientUserAgent`);
+	}
+}, _ = async ({ event: t, warnings: n }) => {
+	let { params: r, redactedKeys: i } = e(t.customData ?? {});
+	return i.length > 0 && n.push(`event "${t.eventName}": personal data redacted from customData ${i.join(", ")}`), {
+		event_name: t.eventName,
+		event_time: Math.floor((t.eventTime ?? /* @__PURE__ */ new Date()).getTime() / 1e3),
+		action_source: t.actionSource ?? "website",
+		...t.eventId && { event_id: t.eventId },
+		...t.eventSourceUrl && { event_source_url: t.eventSourceUrl },
+		user_data: await d(t.userData),
+		...Object.keys(r).length > 0 && { custom_data: r }
+	};
+}, v = async (e) => {
+	g(e);
+	let { pixelId: t, accessToken: n, events: r, testEventCode: i, graphApiVersion: a = f } = e, o = [], s = await Promise.all(r.map((e) => _({
+		event: e,
+		warnings: o
+	}))), c = new URL(`https://graph.facebook.com/${a}/${t}/events`);
+	c.searchParams.set("access_token", n);
+	let l = await fetch(c, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			data: s,
+			...i && { test_event_code: i }
+		})
+	}), u = await l.json().catch(() => void 0);
+	return {
+		ok: l.ok,
+		status: l.status,
+		body: u,
+		warnings: o
+	};
+}, y = {
+	global: "https://www.google-analytics.com",
+	eu: "https://region1.google-analytics.com"
+}, b = /^G-[A-Z0-9]+$/, x = 25, S = (e) => /* @__PURE__ */ TypeError(`[react-marketing-tools] sendMeasurementProtocolEvent: ${e}`), C = ({ measurementId: e, apiSecret: t, clientId: i, userId: a, events: o }) => {
+	if (!b.test(e)) throw S(`measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)})`);
+	if (!t) throw S("apiSecret is required");
+	if (!i) throw S("clientId is required; read it from the _ga cookie with readGa4Cookies()");
+	if (a !== void 0 && (!a || n(a))) throw S("userId must be your own identifier, not personal data such as an email address");
+	if (o.length === 0 || o.length > x) throw S(`send between 1 and ${x} events per request (received ${o.length})`);
+	for (let { name: e } of o) {
+		let t = r(e);
+		if (t) throw S(t);
+	}
+}, w = ({ event: { name: n, params: r = {} }, sessionId: i, warnings: a }) => {
+	for (let e of t(r)) a.push(`event "${n}" ${e}`);
+	let { params: o, redactedKeys: s } = e(r);
+	return s.length > 0 && a.push(`event "${n}": personal data redacted from ${s.join(", ")}`), {
+		name: n,
+		params: {
+			...i && { session_id: i },
+			engagement_time_msec: 1,
+			...o
+		}
+	};
+}, T = ({ adUserData: e, adPersonalization: t }) => ({
+	...e && { ad_user_data: e.toUpperCase() },
+	...t && { ad_personalization: t.toUpperCase() }
+}), E = async (e) => {
+	C(e);
+	let { measurementId: t, apiSecret: n, clientId: r, sessionId: i, userId: a, events: o, consent: s, validate: c = !1, region: l = "global" } = e, u = [], d = {
+		client_id: r,
+		...a && { user_id: a },
+		...s && { consent: T(s) },
+		events: o.map((e) => w({
+			event: e,
+			sessionId: i,
+			warnings: u
+		}))
+	}, f = new URL(c ? "/debug/mp/collect" : "/mp/collect", y[l]);
+	f.searchParams.set("measurement_id", t), f.searchParams.set("api_secret", n);
+	let p = await fetch(f, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(d)
+	});
+	if (!c) return {
+		ok: p.ok,
+		status: p.status,
+		warnings: u
+	};
+	let { validationMessages: m = [] } = await p.json().catch(() => ({}));
+	return {
+		ok: p.ok && m.length === 0,
+		status: p.status,
+		warnings: u,
+		validationMessages: m
+	};
+}, D = ({ userAgent: e, agents: t }) => {
+	let n = e.toLowerCase();
+	return Object.entries(t).find(([, e]) => e.some((e) => n.includes(e.toLowerCase())))?.[0];
+}, O = (e) => /* @__PURE__ */ TypeError(`[react-marketing-tools] sendAiCrawlerEvent: ${e}`), k = ["traffic_type", "ai_agent"], A = async (e) => {
+	let { agent: t, keepSeparate: n, events: r, ...i } = e;
+	if (!t) throw O("agent is required");
+	let a = n === "separate-property" ? "ai_crawler" : n?.trafficType;
+	if (!a) throw O("keepSeparate is required: 'separate-property' when measurementId is a crawler-only property, or { trafficType } matching a GA4 data filter. Crawler hits must never land in a visitor property untagged.");
+	let o = r.flatMap((e) => k.filter((t) => e.params?.[t] !== void 0).map((t) => `event "${e.name}" param "${t}" was replaced: sendAiCrawlerEvent sets it`)), s = await E({
+		...i,
+		events: r.map((e) => ({
+			...e,
+			params: {
+				...e.params,
+				traffic_type: a,
+				ai_agent: t
+			}
+		}))
+	});
+	return {
+		...s,
+		warnings: [...o, ...s.warnings]
+	};
+}, j = 16384, M = /^\d+$/, N = [
+	"externalId",
+	"email",
+	"phone",
+	"firstName",
+	"lastName",
+	"fbc",
+	"fbp"
+], P = (e) => /* @__PURE__ */ TypeError(`[react-marketing-tools] createTrackHandler: ${e}`), F = ({ allowedOrigins: e, meta: t }) => {
+	if (e.length === 0) throw P("allowedOrigins needs at least one origin, e.g. 'https://shop.example.com'");
+	for (let t of e) if (!URL.canParse(t) || new URL(t).origin !== t) throw P(`allowedOrigins entries must be origins such as 'https://shop.example.com', without a path or trailing slash (received ${JSON.stringify(t)})`);
+	if (!M.test(t.pixelId)) throw P(`meta.pixelId must be the numeric pixel ID (received ${JSON.stringify(t.pixelId)})`);
+	if (!t.accessToken) throw P("meta.accessToken is required");
+}, I = (e, t) => new Response(t, { status: e }), L = async (e) => {
+	if (Number(e.headers.get("content-length")) > j) return;
+	if (!e.body) return "";
+	let t = e.body.getReader(), n = new TextDecoder(), r = "", i = 0;
+	for (;;) {
+		let { done: e, value: a } = await t.read();
+		if (e) return r + n.decode();
+		if (i += a.byteLength, i > j) {
+			await t.cancel();
+			return;
+		}
+		r += n.decode(a, { stream: !0 });
+	}
+}, R = (e) => typeof e == "object" && !!e && !Array.isArray(e), z = (e) => typeof e == "string" && e.length > 0, B = (e) => typeof e == "string" && URL.canParse(e) && ["http:", "https:"].includes(new URL(e).protocol), V = (e) => {
+	let t;
+	try {
+		t = JSON.parse(e);
+	} catch {
+		return;
+	}
+	if (!R(t) || t.v !== 1) return;
+	let { eventName: n, eventId: r, customData: i, eventSourceUrl: a, consent: o, userData: s } = t;
+	if (z(n) && z(r) && R(i) && B(a) && R(o) && (o.adUserData === "granted" || o.adUserData === "denied") && R(s) && !N.some((e) => s[e] !== void 0 && typeof s[e] != "string")) return {
+		v: 1,
+		eventName: n,
+		eventId: r,
+		customData: i,
+		eventSourceUrl: a,
+		consent: { adUserData: o.adUserData },
+		userData: Object.fromEntries(N.filter((e) => s[e] !== void 0).map((e) => [e, s[e]]))
+	};
+}, H = (e) => {
+	F(e);
+	let { meta: t, onError: n = console.error } = e, r = new Set(e.allowedOrigins);
+	return async (e) => {
+		if (e.method !== "POST") return new Response("Use POST", {
+			status: 405,
+			headers: { allow: "POST" }
+		});
+		let i = e.headers.get("origin");
+		if (!i || !r.has(i)) return I(403, "Origin not allowed");
+		let a = await L(e);
+		if (a === void 0) return I(413, "Body too large");
+		let o = V(a);
+		if (!o) return I(400, "Invalid event");
+		let s = e.headers.get("user-agent");
+		if (!s) return I(400, "Missing User-Agent");
+		if (o.consent.adUserData !== "granted") return I(204);
+		try {
+			let r = await v({
+				...t,
+				events: [{
+					eventName: o.eventName,
+					eventId: o.eventId,
+					eventSourceUrl: o.eventSourceUrl,
+					userData: {
+						...o.userData,
+						clientIpAddress: e.headers.get("x-forwarded-for")?.split(",")[0].trim(),
+						clientUserAgent: s
+					},
+					customData: o.customData
+				}]
+			});
+			if (r.ok) return I(204);
+			n(Error(`[react-marketing-tools] createTrackHandler: Meta rejected "${o.eventName}" (HTTP ${r.status})`, { cause: r.body }));
+		} catch (e) {
+			n(Error(`[react-marketing-tools] createTrackHandler: could not send "${o.eventName}" to Meta`, { cause: e }));
+		}
+		return I(502, "Meta did not accept the event");
+	};
+}, U = ({ cookieHeader: e, measurementId: t }) => {
+	let n = /^GA\d\.\d\.(\d+\.\d+)$/.exec(i(e, "_ga") ?? "")?.[1], r = i(e, `_ga_${t.replace(/^G-/, "")}`) ?? "", a = /^GS1\.\d\.(\d+)\./.exec(r)?.[1] ?? /^GS2\.\d\.s(\d+)/.exec(r)?.[1];
+	return {
+		...n && { clientId: n },
+		...a && { sessionId: a }
+	};
+};
+//#endregion
+export { f as META_GRAPH_API_VERSION, H as createTrackHandler, D as matchAiAgent, U as readGa4Cookies, A as sendAiCrawlerEvent, v as sendConversionsApiEvent, E as sendMeasurementProtocolEvent };

package/dist/shared/hash.d.ts

@@ -0,0 +1,4 @@
+/** SHA-256 of a UTF-8 string, as lowercase hex. Uses Web Crypto, so it runs in browsers, Node.js and edge runtimes. */
+export declare const sha256Hex: (value: string) => Promise<string>;
+/** True for a value that is already a SHA-256 hex digest, so it isn't hashed twice. */
+export declare const isSha256Hex: (value: string) => boolean;

package/dist/shared/uuid.d.ts

@@ -0,0 +1 @@
+export declare const randomUuid: () => string;

package/dist/webVitals.d.ts

@@ -0,0 +1,8 @@
+import type { Analytics } from './core/types.js';
+/**
+ * Reports Core Web Vitals (LCP, INP and CLS) as events, the way the `web-vitals` library recommends for GA4. Install it
+ * first: `npm install web-vitals@^6`. It's downloaded when this is first called, and does nothing outside the browser.
+ *
+ * The events reach GA4 and Tag Manager, never the Meta Pixel or the relay.
+ */
+export declare const trackWebVitals: (analytics: Pick<Analytics, 'track'>) => Promise<void>;