react-marketing-tools 1.0.0-beta.3 → 1.0.1

package/README.md

@@ -1,146 +1,397 @@
 # React Marketing Tools
 
-[![npm next](https://img.shields.io/npm/v/react-marketing-tools/next?label=npm%40next)](https://www.npmjs.com/package/react-marketing-tools?activeTab=versions)
+[![npm](https://img.shields.io/npm/v/react-marketing-tools)](https://www.npmjs.com/package/react-marketing-tools)
+[![downloads](https://img.shields.io/npm/dm/react-marketing-tools)](https://www.npmjs.com/package/react-marketing-tools)
+[![bundle size](https://img.shields.io/bundlejs/size/react-marketing-tools?externals=react,react-dom,react/jsx-runtime)](https://bundlejs.com/?q=react-marketing-tools)
+[![types](https://img.shields.io/npm/types/react-marketing-tools)](https://www.npmjs.com/package/react-marketing-tools)
+[![node](https://img.shields.io/node/v/react-marketing-tools?logo=nodedotjs)](https://www.npmjs.com/package/react-marketing-tools)
 [![license](https://img.shields.io/npm/l/react-marketing-tools)](./LICENSE)
 
-One `track()` call for Google Tag Manager, Google Analytics 4 and the Meta Pixel, with Consent Mode v2, UTM attribution
-and personal-data redaction built in.
-
-**[Try it in the playground](https://bronz3beard.github.io/react-marketing-tools/)**: see what each vendor receives for
-every event, without sending anything.
-
-> **1.0 is in beta** on the `next` tag. `npm install react-marketing-tools` still installs 0.4.x, whose API 1.0
-> replaces; see the [migration guide](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/migration-v1.md)
-> and the [changelog](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/CHANGELOG.md).
+[![CI](https://img.shields.io/github/actions/workflow/status/bronz3beard/react-marketing-tools/ci.yml?branch=main&label=CI&logo=github)](https://github.com/bronz3beard/react-marketing-tools/actions/workflows/ci.yml)
+[![CodeQL](https://img.shields.io/github/actions/workflow/status/bronz3beard/react-marketing-tools/codeql.yml?branch=main&label=CodeQL&logo=github)](https://github.com/bronz3beard/react-marketing-tools/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/bronz3beard/react-marketing-tools?label=openssf%20scorecard)](https://scorecard.dev/viewer/?uri=github.com/bronz3beard/react-marketing-tools)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14943/badge)](https://www.bestpractices.dev/projects/14943)
+[![last commit](https://img.shields.io/github/last-commit/bronz3beard/react-marketing-tools)](https://github.com/bronz3beard/react-marketing-tools/commits/main)
+
+[![AI setup prompt](https://img.shields.io/badge/AI%20setup-prompt-blueviolet)](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/agent-setup.md)
+[![discussions](https://img.shields.io/github/discussions/bronz3beard/react-marketing-tools)](https://github.com/bronz3beard/react-marketing-tools/discussions)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/bronz3beard/react-marketing-tools/blob/main/CONTRIBUTING.md)
+
+Send one event from your React app and it reaches Google Tag Manager, Google Analytics 4 and the Meta Pixel at once.
+The library keeps the visitor's privacy choices, remembers which campaign brought them, strips personal data out of
+events, and can send the same events again from your server so they still arrive when a browser blocks tracking.
+
+**[Try it in the playground](https://bronz3beard.github.io/react-marketing-tools/)**: press a button and see exactly
+what each of those services would receive. Nothing is sent anywhere.
+
+> **Setting this up with an AI assistant?** There's a prompt written for that:
+> [Set this up with an AI assistant](#set-this-up-with-an-ai-assistant). It interviews you, writes the wiring, and
+> tells you what to click in each service.
+
+> **Coming from 0.4?** 1.0 is a rewrite, and the API is different. The
+> [migration guide](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/migration-v1.md) maps the old
+> names to the new ones, and the
+> [changelog](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/CHANGELOG.md) lists everything that
+> changed.
+
+## Contents
+
+- [What you need before you start](#what-you-need-before-you-start)
+- [Install](#install)
+- [Set this up with an AI assistant](#set-this-up-with-an-ai-assistant)
+- [Quick start](#quick-start)
+  - [1. Create the analytics instance](#1-create-the-analytics-instance)
+  - [2. Hand it to your app](#2-hand-it-to-your-app)
+  - [3. Track an event](#3-track-an-event)
+- [Track clicks without writing code](#track-clicks-without-writing-code)
+- [Follow a multi-step flow](#follow-a-multi-step-flow)
+- [Tell the library who the visitor is](#tell-the-library-who-the-visitor-is)
+- [Record what the visitor consented to](#record-what-the-visitor-consented-to)
+- [Recognise a returning visitor](#recognise-a-returning-visitor)
+- [Report how fast your pages are](#report-how-fast-your-pages-are)
+- [Send events from your server](#send-events-from-your-server)
+  - [A purchase confirmed by a payment webhook](#a-purchase-confirmed-by-a-payment-webhook)
+  - [Send the Pixel's events from your server too](#send-the-pixels-events-from-your-server-too)
+- [Use it without React](#use-it-without-react)
+- [What each service receives](#what-each-service-receives)
+- [Documentation](#documentation)
+- [License](#license)
+
+## What you need before you start
+
+This library sends events to accounts you already have. It doesn't create or configure them for you, and it isn't a
+replacement for them. Before you install it, set up the ones you want to use:
+
+| You want | What you need first | What the library needs from it |
+| --- | --- | --- |
+| Google Tag Manager | A container, with the tags and triggers that decide what happens to each event | The container ID, like `GTM-XXXXXXX` |
+| Google Analytics 4 | A property with a web data stream | The measurement ID, like `G-XXXXXXX` |
+| Meta Pixel | A dataset (pixel) in Meta Events Manager | The pixel ID, a long number |
+| Events sent from your server to GA4 | An API secret on that same data stream | The secret, kept on your server |
+| Events sent from your server to Meta | A Conversions API access token in Events Manager | The token, kept on your server |
+
+Two things worth knowing:
+
+- **With Tag Manager, your container still decides what happens.** The library puts each event into the dataLayer, the
+  list of events Tag Manager watches. Until you add a trigger and a tag for an event name, the event is recorded but
+  goes nowhere.
+- **With Google Analytics 4, events arrive on their own.** They show up as events with the name you tracked. Using the
+  names Google recommends, such as `purchase` or `sign_up`, fills in GA4's built-in reports; your own names appear in
+  reports and explorations once you use them.
+
+You only configure the services you use. Many teams start with Tag Manager alone and add the rest later.
 
 ## Install
 
 ```sh
-npm install react-marketing-tools@next
+npm install react-marketing-tools
 ```
 
-Requires React 18 or 19. The package is ESM-only; server rendering needs Node.js 22.12 or later.
+Works with React 18 and 19. The package is published as ES modules, the `import` style of JavaScript, so it works in
+every current bundler and in Node.js 22.12 or later; it can't be loaded with `require()`.
+
+## Set this up with an AI assistant
+
+There's a prompt you can paste into any AI coding assistant. It reads your project, asks what you want to measure and
+which analytics accounts you have, then writes the setup, a checklist of what to click in Google Tag Manager, Google
+Analytics and Meta, and the steps to check it all worked.
+
+**[Get the prompt](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/agent-setup.md)**, paste it into
+your assistant, and answer its questions. That page also lists the six things to check before you trust what it wrote,
+and an `AGENTS.md` block to keep in your repo so later sessions don't re-guess the conventions this one chose.
 
-## Usage
+The prompt is tested: three assistants set up a Next.js app and a Vite app from scratch, and what they got wrong is
+what those rules are there to prevent.
 
-Create one instance:
+Working by hand is just as quick for a simple setup: the [quick start](#quick-start) below, or the
+[integration walkthrough](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/integration-walkthrough.md)
+for an app that already has analytics in it.
+
+## Quick start
+
+Adding this to an app that already exists, with analytics already in it? Follow the
+[integration walkthrough](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/integration-walkthrough.md)
+instead: same steps, plus how to prove events arrive and how to retire the library you're replacing.
+
+### 1. Create the analytics instance
 
 ```ts
 // analytics.ts
 import { createAnalytics } from 'react-marketing-tools'
 
 export const analytics = createAnalytics({
-  consent: 'denied', // until your consent banner records the visitor's choice
+  // Nothing is stored or sent until you record the visitor's choice; see "Record what the visitor consented to".
+  consent: 'denied',
   gtm: { containerId: 'GTM-XXXXXXX' },
   ga4: { measurementId: 'G-XXXXXXX' },
   metaPixel: { pixelId: '1234567890123456' },
 })
 ```
 
-Provide it to your app:
+Creating the instance does nothing on its own: no scripts load and no cookies are written until your app starts it,
+which the provider below does. That makes this file safe to import anywhere, including in server-rendered pages.
+
+### 2. Hand it to your app
 
 ```tsx
 // main.tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
 import { AnalyticsProvider } from 'react-marketing-tools'
 import { analytics } from './analytics'
+import { App } from './App'
 
 createRoot(document.getElementById('root')!).render(
-  <AnalyticsProvider analytics={analytics}>
-    <App />
-  </AnalyticsProvider>,
+  <StrictMode>
+    <AnalyticsProvider analytics={analytics}>
+      <App />
+    </AnalyticsProvider>
+  </StrictMode>,
 )
 ```
 
-Track from any component:
+The provider loads the vendor scripts once your app is running in the browser. Anything you track before that is held
+and sent in order afterwards, so you never lose an event that happened during startup.
+
+### 3. Track an event
 
 ```tsx
+// SignUpButton.tsx
 import { useAnalytics } from 'react-marketing-tools'
 
 export const SignUpButton = () => {
   const { track } = useAnalytics()
 
-  // Reaches GTM, GA4 and Meta (as CompleteRegistration) with one shared event_id
-  return <button onClick={() => track('sign_up', { method: 'google' })}>Sign up</button>
+  return (
+    <button onClick={() => track('sign_up', { method: 'google' })}>
+      Sign up
+    </button>
+  )
 }
 ```
 
-Or without code, with `autocapture: { clicks: true }` in the config:
+That one call reaches all three services: Tag Manager gets a `sign_up` event, Google Analytics 4 gets `sign_up`, and
+the Meta Pixel gets `CompleteRegistration`, the name Meta uses for the same thing. All three carry the same event ID,
+so when the same action arrives twice, from the browser and from your server, Meta counts it once.
 
-```html
-<button data-analytics-event="cta_click" data-analytics-param-location="hero">Start</button>
+## Track clicks without writing code
+
+Turn it on once, and then mark the elements you care about. No analytics code in your components:
+
+```ts
+// analytics.ts
+import { createAnalytics } from 'react-marketing-tools'
+
+export const analytics = createAnalytics({
+  consent: 'denied',
+  gtm: { containerId: 'GTM-XXXXXXX' },
+  autocapture: { clicks: true },
+})
 ```
 
-Follow a multi-step flow as a funnel:
+```tsx
+// PricingPage.tsx
+export const PricingPage = () => (
+  <section>
+    <h1>Pricing</h1>
+    <button
+      data-analytics-event="cta_click"
+      data-analytics-param-location="pricing_header"
+      data-analytics-param-plan="pro"
+    >
+      Start free trial
+    </button>
+  </section>
+)
+```
+
+A click anywhere inside that button, including on an icon or text inside it, sends the same event as
+`track('cta_click', { location: 'pricing_header', plan: 'pro' })`.
+
+- `data-analytics-event` is the event name. Every `data-analytics-param-*` attribute becomes one detail on the event,
+  with dashes turned into underscores: `data-analytics-param-button-text` arrives as `button_text`.
+- Values are text. For numbers, such as a price you want to add up, call `track()` instead.
+- It works for elements added later, for example after a route change, and for links as well as buttons.
+- If several marked elements are nested, the closest one to the click wins.
+
+## Follow a multi-step flow
+
+A journey groups the steps of a flow such as a checkout, so you can see where people drop out:
+
+```tsx
+// Checkout.tsx
+import { useState } from 'react'
+import { useAnalytics } from 'react-marketing-tools'
+
+export const Checkout = () => {
+  const { journey } = useAnalytics()
+  // Create it once for this flow, not on every render: each journey has its own ID.
+  const [checkout] = useState(() => journey('checkout'))
+
+  return (
+    <>
+      <button onClick={() => checkout.step('shipping')}>Continue to payment</button>
+      <button onClick={() => checkout.complete({ value: 42, currency: 'USD' })}>Pay</button>
+      <button onClick={() => checkout.abandon('changed_mind')}>Cancel</button>
+    </>
+  )
+}
+```
+
+The first call also sends a `journey_start` event, and every event in the flow carries the same journey ID. In Google
+Analytics 4 you can then build a funnel from `journey_start`, `journey_step` and `journey_complete`.
+
+## Tell the library who the visitor is
 
 ```ts
-const checkout = analytics.journey('checkout')
-checkout.step('shipping') // journey_start, then journey_step
-checkout.complete({ value: 42, currency: 'USD' }) // journey_complete
+// after your sign-in code succeeds
+import { analytics } from './analytics'
+
+analytics.identify('user-42', { email: 'ada@example.com' })
 ```
 
-Report Core Web Vitals (LCP, INP, CLS) to GA4 and Tag Manager, after `npm install web-vitals@^6`:
+The ID is your own user ID: it goes to Tag Manager and Google Analytics 4 so you can join sessions to accounts. The
+email address is not sent to Google. It goes only to Meta, which uses contact details to match a visitor to a Facebook
+or Instagram account, and it's scrambled into an unreadable fingerprint (a hash) before it's sent. Call
+`analytics.reset()` when someone signs out.
+
+## Record what the visitor consented to
 
 ```ts
-import { trackWebVitals } from 'react-marketing-tools/web-vitals'
+// from your cookie banner, when the visitor answers
+import { analytics } from './analytics'
 
-void trackWebVitals(analytics)
+analytics.consent.update({ analytics: 'granted', ads: 'granted' })
 ```
 
-The same instance identifies users, records consent and gives a consenting visitor a stable ID:
+Until this is called, the instance follows the `consent` value you passed when you created it. The library passes the
+choice to Google's Consent Mode, which is how Google's tags are told what a visitor agreed to, and to the Meta Pixel,
+which holds events until it's allowed to send them. The same choice controls what the library itself stores in the
+browser. Both parts of the choice can be set separately if your banner asks separately.
+
+## Recognise a returning visitor
 
 ```ts
-analytics.identify('user-42', { email: 'ada@example.com' }) // user id for GTM and GA4, advanced matching for Meta
-analytics.consent.update({ analytics: 'granted', ads: 'granted' }) // Google Consent Mode v2 and Meta consent
-const visitorId = await analytics.getVisitorId() // random by default, or a fingerprint; never sent to GA4
+import { analytics } from './analytics'
+
+// inside an async function, any time after your app has started
+const visitorId = await analytics.getVisitorId()
+```
+
+This is a random ID kept in the browser, given only to visitors who consented to analytics, so you can join a person's
+visits in your own systems. It's never sent to Google Analytics. You can swap it for a browser fingerprint if you want
+to recognise people who clear their cookies; see [Visitor ID](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/visitor-id.md).
+
+## Report how fast your pages are
+
+Core Web Vitals are Google's three measures of page experience: how fast the main content appears, how quickly the page
+responds to a tap or click, and how much the layout jumps around. Install Google's measuring library and pass it your
+instance:
+
+```sh
+npm install web-vitals@^6
 ```
 
-Configure only the destinations you use. Without React, import `createAnalytics` from `react-marketing-tools/core` and
-call `analytics.start()` yourself.
+```ts
+// main.tsx, after the render call
+import { trackWebVitals } from 'react-marketing-tools/web-vitals'
+import { analytics } from './analytics'
+
+void trackWebVitals(analytics)
+```
+
+Each measurement arrives as an event named `LCP`, `INP` or `CLS` in Google Analytics 4 and Tag Manager. They're never
+sent to Meta.
+
+## Send events from your server
+
+Some things happen where the browser can't see them, such as a payment your payment provider confirms minutes later.
+Other events simply never make it, because an extension or browser setting blocks the tracking scripts. For both, send
+the event from your server.
 
-Send events that happen on your server, such as a purchase confirmed by a payment webhook, from
-`react-marketing-tools/server`:
+### A purchase confirmed by a payment webhook
 
 ```ts
+// inside your payment webhook, where `order` is the order you just confirmed
 import { sendMeasurementProtocolEvent } from 'react-marketing-tools/server'
 
 await sendMeasurementProtocolEvent({
   measurementId: 'G-XXXXXXX',
   apiSecret: process.env.GA4_API_SECRET!,
-  clientId: order.ga4ClientId, // saved at checkout with readGa4Cookies()
-  events: [{ name: 'purchase', params: { transaction_id: order.id, value: 42, currency: 'USD' } }],
+  // Saved when the visitor started checkout, with readGa4Cookies() from the same import.
+  clientId: order.ga4ClientId,
+  events: [
+    {
+      name: 'purchase',
+      params: { transaction_id: order.id, value: order.total, currency: 'USD' },
+    },
+  ],
 })
 ```
 
-`sendConversionsApiEvent` does the same for Meta, hashing customer information as Meta requires. To have Meta receive
-the events the browser Pixel misses, counted once, relay them through your server:
+The same import has `sendConversionsApiEvent` for Meta, which scrambles customer details into hashes the way Meta
+requires before sending them.
+
+### Send the Pixel's events from your server too
+
+Point the page at an address on your own site, and mount the handler there. Every event the Pixel receives is then sent
+from your server as well, and Meta counts each one once:
 
 ```ts
 // analytics.ts
-createAnalytics({ /* …as above */ server: { endpoint: '/api/track' } })
+import { createAnalytics } from 'react-marketing-tools'
+
+export const analytics = createAnalytics({
+  consent: 'denied',
+  metaPixel: { pixelId: '1234567890123456' },
+  server: { endpoint: '/api/track' },
+})
+```
 
-// app/api/track/route.ts (Next.js; any Request → Response server works)
+```ts
+// app/api/track/route.ts — a Next.js route; any server that speaks Request and Response works
 import { createTrackHandler } from 'react-marketing-tools/server'
 
 export const POST = createTrackHandler({
   allowedOrigins: ['https://shop.example.com'],
-  meta: { pixelId: '1234567890123456', accessToken: process.env.META_CAPI_TOKEN! },
+  meta: {
+    pixelId: '1234567890123456',
+    accessToken: process.env.META_CAPI_TOKEN!,
+  },
 })
 ```
 
-## What each destination receives
+## Use it without React
+
+```ts
+// analytics.ts
+import { createAnalytics } from 'react-marketing-tools/core'
+
+export const analytics = createAnalytics({
+  consent: 'granted',
+  gtm: { containerId: 'GTM-XXXXXXX' },
+})
+
+analytics.start() // the React provider does this for you
+analytics.track('sign_up', { method: 'google' })
+```
+
+## What each service receives
 
-| | Google Tag Manager | Google Analytics 4 | Meta Pixel | Conversions API relay |
+| | Google Tag Manager | Google Analytics 4 | Meta Pixel | Your server, for Meta |
 | --- | --- | --- | --- | --- |
-| `track()` | dataLayer push with `event_id` | gtag.js event | standard or custom event with `eventID` | the same event from your server |
-| `identify()` | `user_id` | `user_id` | advanced matching | user data, hashed on your server |
-| `consent.update()` | Consent Mode v2 | Consent Mode v2 | `grant` / `revoke` | only with `adUserData` |
-| Attribution | `attribution` (last touch) | read from the page URL | `fbc` | `fbc`, `fbp` |
+| `track()` | the event in the dataLayer, with an event ID | the event through Google's tag | Meta's name for the event, with the same event ID | the same event again, so it still arrives when the browser is blocked |
+| `identify()` | your user ID | your user ID | contact details, hashed by the Pixel | contact details, hashed by your server |
+| `consent.update()` | Google Consent Mode | Google Consent Mode | permission to send, or to hold | only sends with permission to share data with ad platforms |
+| Campaign the visitor came from | the campaign on every event | read from the page address by Google's tag | the Meta click ID | the Meta click and browser IDs |
 
 ## Documentation
 
 - [All docs](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/README.md)
 - [Getting started](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/getting-started.md)
-- [React](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/react.md): provider, hook, Next.js App Router, single-page apps
+- [Integration walkthrough](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/integration-walkthrough.md): add it to an existing app, step by step, and prove events arrive
+- [React](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/react.md): provider, hook, single-page apps
+- [Next.js](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/nextjs.md): a complete App Router setup, client and server
 - [Tracking events](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/tracking-events.md): naming rules, page views, journeys, click autocapture, Web Vitals, users, personal data, errors
 - [Configuration](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/configuration.md)
 - [Consent](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/consent.md): Consent Mode v2 and Global Privacy Control
@@ -149,11 +400,16 @@ export const POST = createTrackHandler({
 - [Google Tag Manager](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/google-tag-manager.md)
 - [Google Analytics 4](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/google-analytics-4.md)
 - [Meta Pixel](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/meta-pixel.md)
+- [Other tools](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/custom-destinations.md): PostHog, Umami, Plausible, your own endpoint
+- [Measuring AI activity](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/ai-traffic.md): AI features, visits from AI assistants, AI crawlers
 - [Server-side tagging](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/server-side-tagging.md)
 - [GA4 Measurement Protocol](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/measurement-protocol.md): GA4 events from your server
 - [Meta Conversions API](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/meta-conversions-api.md): Meta events from your server
+- [Error tracking](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/error-tracking.md): report errors to Google Analytics 4
 - [Debugging](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/debugging.md): see what's sent, and fix common problems
 - [Migrating from 0.4](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/migration-v1.md)
+- [API summary](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/api-summary.md): every option, method and limit on one page
+- [Set up with an AI assistant](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/agent-setup.md): a prompt that interviews you and writes the setup
 - [Changelog](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/CHANGELOG.md)
 
 ## License

package/dist/attribution/attribution.d.ts

@@ -1,13 +1,20 @@
-import type { Attribution, CampaignParam } from '../core/types.js';
+import type { AiSources, Attribution, CampaignParam } from '../core/types.js';
 export declare const CAMPAIGN_PARAMS: readonly CampaignParam[];
+/** Your label for the AI assistant a referrer belongs to: an exact hostname match, or a subdomain of one. */
+export declare const matchAiSource: ({ referrer, aiSources, }: {
+    referrer?: string;
+    aiSources?: AiSources;
+}) => string | undefined;
 /**
- * The campaign behind a visit, from its landing URL. `undefined` when the URL carries no campaign params, so a plain
- * navigation never replaces an earlier touch. Values are email-redacted (email tools put addresses in `utm_term`).
+ * The campaign behind a visit, from its landing URL, or the AI assistant that sent it. `undefined` when the URL carries
+ * no campaign params and the referrer isn't one of `aiSources`, so a plain navigation never replaces an earlier touch.
+ * Values are email-redacted (email tools put addresses in `utm_term`).
  */
-export declare const parseAttribution: ({ url, referrer, capturedAt, }: {
+export declare const parseAttribution: ({ url, referrer, capturedAt, aiSources, }: {
     url: string;
     referrer?: string;
     capturedAt: number;
+    aiSources?: AiSources;
 }) => Attribution | undefined;
 /** Stored attribution is untrusted input: anything that isn't a well-formed touch is discarded. */
 export declare const toAttribution: (value: unknown) => Attribution | undefined;

package/dist/chunks/core.js

@@ -23,75 +23,87 @@ var a = [
 	if (!URL.canParse(e)) return;
 	let { origin: t, pathname: n } = new URL(e);
 	return t + n;
-}, c = ({ url: t, referrer: n, capturedAt: r }) => {
+}, c = ({ referrer: e, aiSources: t }) => {
+	if (!e || !t || !URL.canParse(e)) return;
+	let n = new URL(e).hostname.toLowerCase();
+	return Object.entries(t).find(([, e]) => e.some((e) => {
+		let t = e.toLowerCase();
+		return n === t || n.endsWith(`.${t}`);
+	}))?.[0];
+}, l = ({ url: t, referrer: n, capturedAt: r, aiSources: i }) => {
 	if (!URL.canParse(t)) return;
-	let { searchParams: i } = new URL(t), c = a.flatMap((e) => {
-		let t = i.get(e)?.trim();
+	let { searchParams: l } = new URL(t), u = a.flatMap((e) => {
+		let t = l.get(e)?.trim();
 		return t ? [[e, t]] : [];
+	}), d = c({
+		referrer: n,
+		aiSources: i
 	});
-	if (c.length === 0) return;
-	let { params: l } = e(Object.fromEntries(c)), u = Object.fromEntries(Object.entries(l).map(([e, t]) => [e, String(t).slice(0, o)])), d = n ? s(n) : void 0;
+	if (u.length === 0 && !d) return;
+	let { params: f } = e(Object.fromEntries(u)), p = Object.fromEntries(Object.entries(f).map(([e, t]) => [e, String(t).slice(0, o)])), m = n ? s(n) : void 0;
 	return {
-		...u,
+		...p,
 		landing_page: s(t) ?? t,
-		...d ? { referrer: d } : {},
+		...m ? { referrer: m } : {},
+		...d ? { ai_source: d } : {},
 		captured_at: r
 	};
-}, l = (e) => typeof e == "object" && !!e, u = (e) => {
-	if (l(e) && typeof e.captured_at == "number" && typeof e.landing_page == "string") return {
+}, u = (e) => typeof e == "object" && !!e, d = (e) => {
+	if (u(e) && typeof e.captured_at == "number" && typeof e.landing_page == "string") return {
 		...Object.fromEntries(a.flatMap((t) => typeof e[t] == "string" ? [[t, e[t]]] : [])),
 		landing_page: e.landing_page,
 		...typeof e.referrer == "string" ? { referrer: e.referrer } : {},
+		...typeof e.ai_source == "string" ? { ai_source: e.ai_source } : {},
 		captured_at: e.captured_at
 	};
-}, d = ({ fbcCookie: e, touch: t }) => e ?? (t?.fbclid ? `fb.1.${t.captured_at}.${t.fbclid}` : void 0), f = "rmt:attribution:first", p = "rmt:attribution:last", m = 864e5, h = (e, t) => {
+}, f = ({ fbcCookie: e, touch: t }) => e ?? (t?.fbclid ? `fb.1.${t.captured_at}.${t.fbclid}` : void 0), p = "rmt:attribution:first", m = "rmt:attribution:last", h = 864e5, g = (e, t) => {
 	try {
 		return t(window[e]);
 	} catch {
 		return;
 	}
-}, g = (e, t) => h(e, (e) => {
+}, _ = (e, t) => g(e, (e) => {
 	let n = e.getItem(t);
-	return n === null ? void 0 : u(JSON.parse(n));
+	return n === null ? void 0 : d(JSON.parse(n));
 }), ee = ({ ttlDays: e }) => {
-	let t, n, r = (t) => Date.now() - t.captured_at < e * m;
+	let t, n, r = (t) => Date.now() - t.captured_at < e * h;
 	return {
 		observe(e) {
 			e && (t ??= e, n = e);
 		},
 		restore() {
-			let e = g("localStorage", f);
-			e && r(e) && (!t || e.captured_at <= t.captured_at) && (t = e), n ??= g("sessionStorage", p);
+			let e = _("localStorage", p);
+			e && r(e) && (!t || e.captured_at <= t.captured_at) && (t = e), n ??= _("sessionStorage", m);
 		},
 		persist() {
-			h("localStorage", (e) => t && r(t) ? e.setItem(f, JSON.stringify(t)) : e.removeItem(f)), n && h("sessionStorage", (e) => e.setItem(p, JSON.stringify(n)));
+			g("localStorage", (e) => t && r(t) ? e.setItem(p, JSON.stringify(t)) : e.removeItem(p)), n && g("sessionStorage", (e) => e.setItem(m, JSON.stringify(n)));
 		},
 		erase() {
-			h("localStorage", (e) => e.removeItem(f)), h("sessionStorage", (e) => e.removeItem(p));
+			g("localStorage", (e) => e.removeItem(p)), g("sessionStorage", (e) => e.removeItem(m));
 		},
 		get: () => ({
 			firstTouch: t,
 			lastTouch: n
 		})
 	};
-}, _ = "data-analytics-event", v = "data-analytics-param-", y = (e) => {
+}, v = "data-analytics-event", y = "data-analytics-param-", b = (e) => {
 	if (!(e instanceof Element)) return;
-	let t = e.closest(`[${_}]`), n = t?.getAttribute(_);
+	let t = e.closest(`[${v}]`), n = t?.getAttribute(v);
 	if (t && n) return {
 		name: n,
-		params: Object.fromEntries(Array.from(t.attributes).filter((e) => e.name.startsWith(v)).map((e) => [e.name.slice(21).replaceAll("-", "_"), e.value]))
+		params: Object.fromEntries(Array.from(t.attributes).filter((e) => e.name.startsWith(y)).map((e) => [e.name.slice(21).replaceAll("-", "_"), e.value]))
 	};
-}, b = (e) => {
+}, te = (e) => {
 	document.addEventListener("click", (t) => {
-		let n = y(t.target);
+		let n = b(t.target);
 		n && e(n.name, n.params);
 	}, { capture: !0 });
-}, x = [
+}, ne = [
 	"analytics",
 	"ads",
 	"adUserData",
 	"adPersonalization"
-], te = (e) => e === "granted" || e === "denied", ne = ({ consent: e, gpc: t }) => {
+], x = (e) => e === "granted" || e === "denied", S = ({ consent: e, gpc: t }) => {
 	let n = t ? "denied" : e;
 	return {
 		analytics: e,
@@ -99,7 +111,7 @@ var a = [
 		adUserData: n,
 		adPersonalization: n
 	};
-}, S = (e, t) => ({
+}, re = (e, t) => ({
 	analytics: t.analytics ?? e.analytics,
 	ads: t.ads ?? e.ads,
 	adUserData: t.adUserData ?? t.ads ?? e.adUserData,
@@ -109,7 +121,7 @@ var a = [
 	ad_storage: e.ads,
 	ad_user_data: e.adUserData,
 	ad_personalization: e.adPersonalization
-}), w = (e) => Object.values(e).includes("denied"), re = () => typeof navigator < "u" && navigator.globalPrivacyControl === !0, T = () => window.dataLayer ??= [], E = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/gtag/js")), D = () => window.gtag ??= function() {
+}), w = (e) => Object.values(e).includes("denied"), ie = () => typeof navigator < "u" && navigator.globalPrivacyControl === !0, T = () => window.dataLayer ??= [], E = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/gtag/js")), D = () => window.gtag ??= function() {
 	T().push(arguments);
 }, O = ({ consent: e, waitForUpdate: t }) => {
 	D()("consent", "default", {
@@ -125,8 +137,8 @@ var a = [
 }, j = (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);
-}, ie = /^G-[A-Z0-9]+$/, ae = ({ measurementId: e, pageViews: t = "auto", loadScript: n = !0, serverContainerUrl: r, waitForUpdate: i = 500, nonce: a }) => {
-	if (!ie.test(e)) throw Error(`[react-marketing-tools] ga4.measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)}).`);
+}, ae = /^G-[A-Z0-9]+$/, oe = ({ measurementId: e, pageViews: t = "auto", loadScript: n = !0, serverContainerUrl: r, waitForUpdate: i = 500, nonce: a }) => {
+	if (!ae.test(e)) throw Error(`[react-marketing-tools] ga4.measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)}).`);
 	r !== void 0 && A(r, "ga4.serverContainerUrl");
 	let o = `https://www.googletagmanager.com/gtag/js?id=${e}`, s = (e, t) => r ? {
 		...e,
@@ -276,7 +288,7 @@ var a = [
 	ph: t.phone,
 	fn: t.firstName,
 	ln: t.lastName
-}).filter(([, e]) => e !== void 0)), q = (e) => e.adUserData === "granted" ? "grant" : "revoke", oe = ({ pixelId: e, pageViews: t = "auto", loadScript: n = !0, nonce: r }) => {
+}).filter(([, e]) => e !== void 0)), q = (e) => e.adUserData === "granted" ? "grant" : "revoke", se = ({ pixelId: e, pageViews: t = "auto", loadScript: n = !0, nonce: r }) => {
 	if (!H.test(e)) throw Error(`[react-marketing-tools] metaPixel.pixelId must be the numeric pixel ID (received ${JSON.stringify(e)}).`);
 	return {
 		name: "metaPixel",
@@ -304,10 +316,10 @@ var a = [
 	constructor(e, t, n) {
 		super(`[react-marketing-tools] ${t}`, n), this.name = "AnalyticsError", this.code = e;
 	}
-}, se = (e) => e.startsWith("/") && !e.startsWith("//") || URL.canParse(e) && new URL(e).protocol === "https:", ce = ({ endpoint: e, relayPageViews: t, visitorId: n, onError: r }) => {
-	if (!se(e)) throw Error(`[react-marketing-tools] server.endpoint must be a path on your site, such as '/api/track', or an https:// URL (received ${JSON.stringify(e)}).`);
+}, ce = (e) => e.startsWith("/") && !e.startsWith("//") || URL.canParse(e) && new URL(e).protocol === "https:", le = ({ endpoint: e, relayPageViews: t, visitorId: n, onError: r }) => {
+	if (!ce(e)) throw Error(`[react-marketing-tools] server.endpoint must be a path on your site, such as '/api/track', or an https:// URL (received ${JSON.stringify(e)}).`);
 	let a = "denied", o, s = (e) => {
-		let t = i(document.cookie, "_fbp"), r = d({
+		let t = i(document.cookie, "_fbp"), r = f({
 			fbcCookie: i(document.cookie, "_fbc"),
 			touch: e.attribution
 		}), a = o?.userId ?? n();
@@ -367,31 +379,31 @@ var a = [
 			o = void 0;
 		}
 	};
-}, 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 = "rmt:vid", le = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, Z = () => {
+}, 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 = "rmt:vid", ue = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, de = () => {
 	try {
 		let e = localStorage.getItem(X);
-		return e !== null && le.test(e) ? e : void 0;
+		return e !== null && ue.test(e) ? e : void 0;
 	} catch {
 		return;
 	}
-}, Q = (e) => {
+}, Z = (e) => {
 	try {
 		e ? localStorage.setItem(X, e) : localStorage.removeItem(X);
 	} catch {}
-}, ue = () => {
+}, fe = () => {
 	let e, t = (t) => {
 		if (t.analytics !== "granted") return;
-		let n = Z();
-		return n ? e = n : (e ??= Y(), Q(e), e);
+		let n = de();
+		return n ? e = n : (e ??= Y(), Z(e), e);
 	};
 	return {
 		peek: t,
 		get: (e) => Promise.resolve(t(e)),
 		erase() {
-			e = void 0, Q(void 0);
+			e = void 0, Z(void 0);
 		}
 	};
-}, de = ({ fingerprint: e, onError: t }) => {
+}, pe = ({ fingerprint: e, onError: t }) => {
 	let n, r, i = (e) => e.analytics === "granted" && e.ads === "granted";
 	return {
 		peek: (e) => i(e) ? r : void 0,
@@ -407,16 +419,16 @@ var a = [
 			n = void 0, r = void 0;
 		}
 	};
-}, fe = ({ config: e, onError: t }) => {
+}, me = ({ config: e, onError: t }) => {
 	if (e !== !1) {
-		if (e === "random") return ue();
-		if (typeof e?.fingerprint == "function") return de({
+		if (e === "random") return fe();
+		if (typeof e?.fingerprint == "function") return pe({
 			fingerprint: e.fingerprint,
 			onError: t
 		});
 		throw Error(`[react-marketing-tools] visitorId must be 'random', false or { fingerprint: () => Promise<string> } (received ${JSON.stringify(e)}).`);
 	}
-}, pe = ({ name: e, track: t, fail: n }) => {
+}, he = ({ name: e, track: t, fail: n }) => {
 	let r = {
 		journey_id: Y(),
 		journey_name: e
@@ -446,14 +458,14 @@ var a = [
 			}));
 		}
 	};
-}, $ = () => typeof window < "u", me = 90, he = (e) => {
+}, Q = () => typeof window < "u", ge = 90, $ = (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)}).`);
-}, ge = (a) => {
-	he(a);
-	let { debug: o = !1, onError: s = console.error, respectGpc: l = !0 } = a, u = ne({
+}, _e = (a) => {
+	$(a);
+	let { debug: o = !1, onError: s = console.error, respectGpc: c = !0 } = a, u = S({
 		consent: a.consent,
-		gpc: l && re()
-	}), f = u, p, m = fe({
+		gpc: c && ie()
+	}), d = u, p, m = me({
 		config: a.visitorId ?? "random",
 		onError: s
 	}), h = () => {}, g = new Promise((e) => {
@@ -463,29 +475,30 @@ var a = [
 			...a.gtm,
 			nonce: a.nonce
 		})] : [],
-		...a.ga4 ? [ae({
+		...a.ga4 ? [oe({
 			...a.ga4,
 			nonce: a.nonce
 		})] : [],
-		...a.metaPixel ? [oe({
+		...a.metaPixel ? [se({
 			...a.metaPixel,
 			nonce: a.nonce
 		})] : [],
-		...a.server ? [ce({
+		...a.server ? [le({
 			...a.server,
 			relayPageViews: !a.metaPixel || a.metaPixel.pageViews === "manual",
-			visitorId: () => m?.peek(f),
+			visitorId: () => m?.peek(d),
 			onError: s
 		})] : [],
 		...a.destinations ?? []
-	], v = [], y = !1, C = a.attribution === !1 ? void 0 : ee({ ttlDays: typeof a.attribution == "object" && a.attribution.ttlDays || me }), w = !1, T = () => {
-		w || (w = !0, C?.observe(c({
+	], v = [], y = !1, b = a.attribution === !1 ? void 0 : ee({ ttlDays: typeof a.attribution == "object" && a.attribution.ttlDays || ge }), C = typeof a.attribution == "object" ? a.attribution.aiSources : void 0, w = !1, T = () => {
+		w || (w = !0, b?.observe(l({
 			url: location.href,
 			referrer: document.referrer,
-			capturedAt: Date.now()
+			capturedAt: Date.now(),
+			aiSources: C
 		})));
-	}, E = () => y && f.analytics === "granted", D = () => {
-		y && a.server && m?.get(f);
+	}, E = () => y && d.analytics === "granted", D = () => {
+		y && a.server && m?.get(d);
 	}, O = (e) => {
 		if (o) throw e;
 		s(e);
@@ -506,7 +519,7 @@ var a = [
 		for (let e of t(i)) O(new J("invalid_param", `event "${n}" ${e}`));
 		let s = e(i), c = a?.meta || void 0, l = c?.params && e(c.params), u = [...s.redactedKeys, ...l?.redactedKeys.map((e) => `meta.${e}`) ?? []];
 		u.length > 0 && O(new J("pii_redacted", `event "${n}": personal data redacted from ${u.join(", ")}`)), T();
-		let d = C?.get().lastTouch;
+		let d = b?.get().lastTouch;
 		return {
 			name: n,
 			params: s.params,
@@ -522,7 +535,7 @@ var a = [
 			timestamp: Date.now()
 		};
 	}, M = (e, t = {}, n) => {
-		if (!$()) return;
+		if (!Q()) return;
 		let r = j({
 			name: e,
 			params: t,
@@ -532,23 +545,24 @@ var a = [
 	};
 	return {
 		start() {
-			!y && $() && (y = !0, T(), E() && (C?.restore(), C?.persist()), D(), k((e) => e.start({
+			!y && Q() && (y = !0, T(), E() && (b?.restore(), b?.persist()), D(), k((e) => e.start({
 				consent: u,
 				identity: p
-			})), v.splice(0).forEach(k), a.autocapture?.clicks && b(M), h());
+			})), v.splice(0).forEach(k), a.autocapture?.clicks && te(M), h());
 		},
 		track: M,
-		journey: (e) => pe({
+		journey: (e) => he({
 			name: e,
 			track: M,
 			fail: O
 		}),
 		page(e = {}) {
-			if (!$()) return;
-			T(), C?.observe(c({
+			if (!Q()) return;
+			T(), b?.observe(l({
 				url: location.href,
-				capturedAt: Date.now()
-			})), E() && C?.persist();
+				capturedAt: Date.now(),
+				aiSources: C
+			})), E() && b?.persist();
 			let t = j({
 				name: "page_view",
 				params: {
@@ -560,7 +574,7 @@ var a = [
 			t && A((e) => e.page ? e.page(t) : e.track(t));
 		},
 		identify(e, t = {}) {
-			if (!$()) return;
+			if (!Q()) return;
 			if (!e || n(e)) {
 				O(new J("invalid_user_id", "identify() needs a non-empty user id that is not personal data such as an email address"));
 				return;
@@ -572,27 +586,27 @@ var a = [
 			p = r, A((e) => e.identify?.(r));
 		},
 		reset() {
-			$() && (p = void 0, A((e) => e.reset?.()));
+			Q() && (p = void 0, A((e) => e.reset?.()));
 		},
 		consent: {
 			update(e) {
-				if (!$()) return;
-				let t = Object.entries(e).filter(([e, t]) => t !== void 0 && !(x.includes(e) && te(t)));
+				if (!Q()) return;
+				let t = Object.entries(e).filter(([e, t]) => t !== void 0 && !(ne.includes(e) && x(t)));
 				if (t.length > 0) {
 					O(new J("invalid_consent", `consent.update() ignored: ${t.map(([e, t]) => `${e}=${JSON.stringify(t)}`).join(", ")}. Use analytics, ads, adUserData or adPersonalization with 'granted' or 'denied'.`));
 					return;
 				}
-				let n = f, r = S(f, e);
-				f = r, n.analytics === "granted" && r.analytics === "denied" ? (C?.erase(), m?.erase()) : E() && (C?.restore(), C?.persist()), D(), A((e) => e.consent?.(r));
+				let n = d, r = re(d, e);
+				d = r, n.analytics === "granted" && r.analytics === "denied" ? (b?.erase(), m?.erase()) : E() && (b?.restore(), b?.persist()), D(), A((e) => e.consent?.(r));
 			},
-			get: () => f
+			get: () => d
 		},
 		getAttribution() {
-			if (!$()) return {};
+			if (!Q()) return {};
 			T();
-			let e = C?.get() ?? {};
-			if (f.adUserData !== "granted") return e;
-			let t = i(document.cookie, "_fbp"), n = d({
+			let e = b?.get() ?? {};
+			if (d.adUserData !== "granted") return e;
+			let t = i(document.cookie, "_fbp"), n = f({
 				fbcCookie: i(document.cookie, "_fbc"),
 				touch: e.lastTouch
 			});
@@ -603,9 +617,9 @@ var a = [
 			};
 		},
 		getVisitorId() {
-			return !$() || !m ? Promise.resolve(void 0) : g.then(() => m.get(f));
+			return !Q() || !m ? Promise.resolve(void 0) : g.then(() => m.get(d));
 		}
 	};
 };
 //#endregion
-export { J as n, ge as t };
+export { J as n, _e as t };

package/dist/core/types.d.ts

@@ -25,12 +25,20 @@ export type TrackOptions = {
     };
 };
 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;
 };
@@ -162,10 +170,12 @@ 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;

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, Journey, MetaPixelConfig, ServerRelayConfig, TrackOptions, VisitorIdConfig, } 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/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.d.ts

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

package/dist/server.js

@@ -78,7 +78,87 @@ var a = async (e) => {
 		body: u,
 		warnings: o
 	};
-}, y = 16384, b = /^\d+$/, x = [
+}, 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",
@@ -86,44 +166,44 @@ var a = async (e) => {
 	"lastName",
 	"fbc",
 	"fbp"
-], S = (e) => /* @__PURE__ */ TypeError(`[react-marketing-tools] createTrackHandler: ${e}`), C = ({ allowedOrigins: e, meta: t }) => {
-	if (e.length === 0) throw S("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 S(`allowedOrigins entries must be origins such as 'https://shop.example.com', without a path or trailing slash (received ${JSON.stringify(t)})`);
-	if (!b.test(t.pixelId)) throw S(`meta.pixelId must be the numeric pixel ID (received ${JSON.stringify(t.pixelId)})`);
-	if (!t.accessToken) throw S("meta.accessToken is required");
-}, w = (e, t) => new Response(t, { status: e }), T = async (e) => {
-	if (Number(e.headers.get("content-length")) > y) return;
+], 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 > y) {
+		if (i += a.byteLength, i > j) {
 			await t.cancel();
 			return;
 		}
 		r += n.decode(a, { stream: !0 });
 	}
-}, E = (e) => typeof e == "object" && !!e && !Array.isArray(e), D = (e) => typeof e == "string" && e.length > 0, O = (e) => typeof e == "string" && URL.canParse(e) && ["http:", "https:"].includes(new URL(e).protocol), k = (e) => {
+}, 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 (!E(t) || t.v !== 1) return;
+	if (!R(t) || t.v !== 1) return;
 	let { eventName: n, eventId: r, customData: i, eventSourceUrl: a, consent: o, userData: s } = t;
-	if (D(n) && D(r) && E(i) && O(a) && E(o) && (o.adUserData === "granted" || o.adUserData === "denied") && E(s) && !x.some((e) => s[e] !== void 0 && typeof s[e] != "string")) return {
+	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(x.filter((e) => s[e] !== void 0).map((e) => [e, s[e]]))
+		userData: Object.fromEntries(N.filter((e) => s[e] !== void 0).map((e) => [e, s[e]]))
 	};
-}, A = (e) => {
-	C(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", {
@@ -131,14 +211,14 @@ var a = async (e) => {
 			headers: { allow: "POST" }
 		});
 		let i = e.headers.get("origin");
-		if (!i || !r.has(i)) return w(403, "Origin not allowed");
-		let a = await T(e);
-		if (a === void 0) return w(413, "Body too large");
-		let o = k(a);
-		if (!o) return w(400, "Invalid event");
+		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 w(400, "Missing User-Agent");
-		if (o.consent.adUserData !== "granted") return w(204);
+		if (!s) return I(400, "Missing User-Agent");
+		if (o.consent.adUserData !== "granted") return I(204);
 		try {
 			let r = await v({
 				...t,
@@ -154,76 +234,19 @@ var a = async (e) => {
 					customData: o.customData
 				}]
 			});
-			if (r.ok) return w(204);
+			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 w(502, "Meta did not accept the event");
+		return I(502, "Meta did not accept the event");
 	};
-}, j = ({ cookieHeader: e, measurementId: t }) => {
+}, 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 }
 	};
-}, M = {
-	global: "https://www.google-analytics.com",
-	eu: "https://region1.google-analytics.com"
-}, N = /^G-[A-Z0-9]+$/, P = 25, F = (e) => /* @__PURE__ */ TypeError(`[react-marketing-tools] sendMeasurementProtocolEvent: ${e}`), I = ({ measurementId: e, apiSecret: t, clientId: i, userId: a, events: o }) => {
-	if (!N.test(e)) throw F(`measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)})`);
-	if (!t) throw F("apiSecret is required");
-	if (!i) throw F("clientId is required; read it from the _ga cookie with readGa4Cookies()");
-	if (a !== void 0 && (!a || n(a))) throw F("userId must be your own identifier, not personal data such as an email address");
-	if (o.length === 0 || o.length > P) throw F(`send between 1 and ${P} events per request (received ${o.length})`);
-	for (let { name: e } of o) {
-		let t = r(e);
-		if (t) throw F(t);
-	}
-}, L = ({ 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
-		}
-	};
-}, R = ({ adUserData: e, adPersonalization: t }) => ({
-	...e && { ad_user_data: e.toUpperCase() },
-	...t && { ad_personalization: t.toUpperCase() }
-}), z = async (e) => {
-	I(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: R(s) },
-		events: o.map((e) => L({
-			event: e,
-			sessionId: i,
-			warnings: u
-		}))
-	}, f = new URL(c ? "/debug/mp/collect" : "/mp/collect", M[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
-	};
 };
 //#endregion
-export { f as META_GRAPH_API_VERSION, A as createTrackHandler, j as readGa4Cookies, v as sendConversionsApiEvent, z as sendMeasurementProtocolEvent };
+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/package.json

@@ -1,11 +1,11 @@
 {
   "name": "react-marketing-tools",
   "type": "module",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.1",
   "description": "One track() call for Google Tag Manager, Google Analytics 4 and the Meta Pixel, with Consent Mode v2, UTM attribution and personal-data redaction built in. React bindings included.",
   "license": "MIT",
   "author": "bronz3beard <exempli.gratia.webdesign@gmail.com> (https://www.heyrory.com/)",
-  "homepage": "https://www.heyrory.com/",
+  "homepage": "https://bronz3beard.github.io/react-marketing-tools/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bronz3beard/react-marketing-tools.git"
@@ -32,7 +32,14 @@
     "gdpr",
     "utm",
     "attribution",
-    "server-side-tagging"
+    "server-side-tagging",
+    "conversions-api",
+    "measurement-protocol",
+    "web-vitals",
+    "consent",
+    "privacy",
+    "nextjs",
+    "typescript"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -69,6 +76,7 @@
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json",
     "build:watch": "vite build --watch",
+    "check:api-summary": "node scripts/check-api-summary.mjs",
     "check:links": "node scripts/check-links.mjs",
     "check:package": "publint --strict && attw --pack . --profile esm-only",
     "check:size": "node scripts/check-size.mjs",
@@ -79,6 +87,7 @@
     "lint": "eslint .",
     "mock:publish": "npm pack --dry-run",
     "prepublishOnly": "npm run build && npm run check:size",
+    "release": "node scripts/release.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
@@ -107,6 +116,7 @@
     "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react-hooks": "^7.1.1",
+    "fast-check": "^4.10.2",
     "jsdom": "^30.1.0",
     "prettier": "^3.9.8",
     "publint": "^0.3.24",