@affiliateo/web 2.4.0 → 3.0.0

package/dist/bot-detect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Client-side bot detection. Mirrors Datafast / PostHog / Plausible's
+ * approach: catch the obvious automation tools at SDK init so they
+ * never fire a single network request.
+ *
+ * Defense in depth:
+ *   1. This check       — catches Selenium / Puppeteer / curl / etc
+ *                         BEFORE anything hits the wire. Saves bandwidth.
+ *                         Can be bypassed by a determined attacker who
+ *                         edits the bundled SDK.
+ *   2. Server UA regex  — catches the same patterns plus legit crawlers
+ *                         (Googlebot, FB crawler, etc). Server is
+ *                         authoritative. Can't be bypassed.
+ *   3. Cloudflare       — invisible browser-attestation challenge. Real
+ *      Turnstile           browsers pass in 50-200ms; scripts that don't
+ *                         run real JS can't pass it. Catches sophisticated
+ *                         attackers who spoofed their UA past layer 2.
+ *
+ * This file implements layer 1 only. Order: layer 1 first (cheap), then
+ * layer 3 (kicks in on the request), then layer 2 (server checks before
+ * writing). If any one layer rejects, the event drops.
+ *
+ * Patterns sourced from the Datafast script tag + npm SDK (publicly
+ * inspectable). We include their full list because it represents years
+ * of accumulated bot-shape knowledge that's expensive to reproduce.
+ */
+/**
+ * Returns true if the current browser context looks like a bot or
+ * automation tool. Safe to call in SSR (returns true since there's no
+ * real visitor in that context anyway — a server-rendered page
+ * shouldn't be firing analytics).
+ *
+ * Wraps every check in try/catch so a hostile environment (frozen
+ * navigator, locked-down iframe) can't crash the SDK init. Any throw
+ * == "not a bot, let them through" so we err on the side of measuring.
+ */
+export declare function isLikelyBot(): boolean;

package/dist/bot-detect.js

@@ -0,0 +1,138 @@
+/**
+ * Client-side bot detection. Mirrors Datafast / PostHog / Plausible's
+ * approach: catch the obvious automation tools at SDK init so they
+ * never fire a single network request.
+ *
+ * Defense in depth:
+ *   1. This check       — catches Selenium / Puppeteer / curl / etc
+ *                         BEFORE anything hits the wire. Saves bandwidth.
+ *                         Can be bypassed by a determined attacker who
+ *                         edits the bundled SDK.
+ *   2. Server UA regex  — catches the same patterns plus legit crawlers
+ *                         (Googlebot, FB crawler, etc). Server is
+ *                         authoritative. Can't be bypassed.
+ *   3. Cloudflare       — invisible browser-attestation challenge. Real
+ *      Turnstile           browsers pass in 50-200ms; scripts that don't
+ *                         run real JS can't pass it. Catches sophisticated
+ *                         attackers who spoofed their UA past layer 2.
+ *
+ * This file implements layer 1 only. Order: layer 1 first (cheap), then
+ * layer 3 (kicks in on the request), then layer 2 (server checks before
+ * writing). If any one layer rejects, the event drops.
+ *
+ * Patterns sourced from the Datafast script tag + npm SDK (publicly
+ * inspectable). We include their full list because it represents years
+ * of accumulated bot-shape knowledge that's expensive to reproduce.
+ */
+// Selenium/WebDriver/headless flags set on window or navigator. Modern
+// automation frameworks try to hide these but the defaults still leak.
+const AUTOMATION_GLOBALS = [
+    '__webdriver_evaluate',
+    '__selenium_evaluate',
+    '__webdriver_script_function',
+    '__webdriver_unwrapped',
+    '__fxdriver_evaluate',
+    '__driver_evaluate',
+    '_Selenium_IDE_Recorder',
+    '_selenium',
+    'calledSelenium',
+    // ChromeDriver's signature global. The dollar-sign-cdc prefix is
+    // a known fingerprint that vanilla undetected-chromedriver tries to
+    // strip but base ChromeDriver still includes.
+    '$cdc_asdjflasutopfhvcZLmcfl_',
+];
+// User-agent substrings (lowercased before match). These cover both the
+// headless browser families AND the tool families (curl/python/etc).
+// Real human UAs do contain things like "Mobile/15E148" so we match on
+// distinctive automation tokens only.
+const BOT_UA_PATTERNS = [
+    'headlesschrome',
+    'phantomjs',
+    'selenium',
+    'webdriver',
+    'puppeteer',
+    'playwright',
+    'python',
+    'curl',
+    'wget',
+    'java/',
+    'go-http',
+    'node.js',
+    'axios',
+    'postman',
+];
+// documentElement attributes some Selenium variants set. Cheap to check.
+const BOT_DOC_ATTRS = ['webdriver', 'selenium', 'driver'];
+/**
+ * Returns true if the current browser context looks like a bot or
+ * automation tool. Safe to call in SSR (returns true since there's no
+ * real visitor in that context anyway — a server-rendered page
+ * shouldn't be firing analytics).
+ *
+ * Wraps every check in try/catch so a hostile environment (frozen
+ * navigator, locked-down iframe) can't crash the SDK init. Any throw
+ * == "not a bot, let them through" so we err on the side of measuring.
+ */
+export function isLikelyBot() {
+    // SSR or non-browser context. We can't run analytics here anyway
+    // because there's no localStorage / sendBeacon / DOM events.
+    if (typeof window === 'undefined' || typeof navigator === 'undefined')
+        return true;
+    try {
+        const nav = window.navigator;
+        const win = window;
+        // Selenium / Puppeteer / Playwright signature on navigator.
+        // Modern stealth plugins try to override this but the override
+        // is detectable too (the property descriptor looks wrong) — we
+        // catch the easy case here and let Turnstile catch the rest.
+        if (nav.webdriver === true)
+            return true;
+        // Legacy headless flags (PhantomJS / Nightmare). Still present in
+        // some old scraper toolchains; cheap to check.
+        if (win.callPhantom !== undefined)
+            return true;
+        if (win._phantom !== undefined)
+            return true;
+        if (win.__nightmare !== undefined)
+            return true;
+        // Missing / suspicious UA. Real browsers always set a useful UA
+        // string; a missing or stub UA strongly implies a HTTP client
+        // (curl --user-agent "" / a python script that forgot to set one).
+        if (!nav.userAgent
+            || nav.userAgent === ''
+            || nav.userAgent === 'undefined'
+            || nav.userAgent.length < 5) {
+            return true;
+        }
+        const ua = nav.userAgent.toLowerCase();
+        // Substring match on the known automation tokens. We split into a
+        // single loop instead of one giant regex for readability — the cost
+        // difference at <20 patterns is microseconds either way.
+        for (const pattern of BOT_UA_PATTERNS) {
+            if (ua.includes(pattern))
+                return true;
+        }
+        // Selenium globals on window. Some frameworks reset navigator but
+        // forget about these.
+        for (const key of AUTOMATION_GLOBALS) {
+            if (win[key] !== undefined)
+                return true;
+        }
+        // documentElement attributes. Cheap belt-and-suspenders check; some
+        // Selenium variants annotate the HTML root for their own bookkeeping.
+        const docEl = document.documentElement;
+        if (docEl) {
+            for (const attr of BOT_DOC_ATTRS) {
+                if (docEl.getAttribute(attr))
+                    return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        // Defensive: if any of the checks throw (locked-down iframe,
+        // proxy-wrapped navigator, etc.), don't block the visitor. Server
+        // regex + Turnstile are still in place to catch whatever this is.
+        return false;
+    }
+}

package/dist/provider.js

@@ -1,10 +1,17 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { EventQueue } from './queue';
+import { isLikelyBot } from './bot-detect';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
 const LS_CAMPAIGN_ID = 'affiliateo_campaign_id';
+// Persistent opt-out flag. Mirrors Datafast's DATAFAST_IGNORE_TRACKING key —
+// when set to "true" the SDK silently noops every outbound call. Survives
+// page reloads. removed by optIn(). Checked at init time so a previously
+// opted-out visitor never re-fires auto-pageviews after a refresh.
+const LS_OPT_OUT = 'affiliateo_opt_out';
 // localStorage helpers
 function lsGet(key) {
     try {
@@ -20,6 +27,18 @@ function lsSet(key, value) {
     }
     catch { }
 }
+function lsRemove(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch { }
+}
+// True when the visitor has opted out via optOut(). Single source of truth
+// read by every outbound call so the flag works even across tabs (each tab's
+// next call re-reads localStorage).
+function isOptedOut() {
+    return lsGet(LS_OPT_OUT) === 'true';
+}
 // Generate UUID
 function uuid() {
     if (typeof crypto !== 'undefined' && crypto.randomUUID)
@@ -31,11 +50,16 @@ function uuid() {
     });
 }
 const asyncNoop = async () => { };
+const syncNoop = () => { };
 const AffiliateoContext = createContext({
     refCode: null,
     visitorId: null,
     track: asyncNoop,
     identify: asyncNoop,
+    trackPageview: asyncNoop,
+    reset: asyncNoop,
+    optOut: syncNoop,
+    optIn: syncNoop,
 });
 /**
  * Returns the affiliate ref code and visitor ID.
@@ -82,6 +106,10 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         visitorId: null,
         track: asyncNoop,
         identify: asyncNoop,
+        trackPageview: asyncNoop,
+        reset: asyncNoop,
+        optOut: syncNoop,
+        optIn: syncNoop,
     });
     const apiBase = (apiUrl || DEFAULT_API_URL).replace(/\/$/, '');
     // campaignIdRef stays current so callbacks defined inside useEffect
@@ -93,6 +121,15 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
     // prop changes without forcing a re-fetch / re-mint cycle. Same UUID
     // for the lifetime of the localStorage entry across the whole tab.
     const visitorIdRef = useRef(null);
+    // EventQueue lives in a ref so it persists across renders without
+    // forcing the methods (track / identify / trackPageview) to depend
+    // on it for useCallback equality. Initialized inside the route
+    // effect since EventQueue's constructor touches localStorage and
+    // window — both unavailable during SSR. Methods called before init
+    // (during the first render, before useEffect runs) silently noop;
+    // this is fine because methods are only ever called from event
+    // handlers, which fire after mount.
+    const queueRef = useRef(null);
     // track + identify are defined OUTSIDE the route-effect so they
     // close over refs (campaignIdRef, visitorIdRef) rather than the
     // captured-once values from inside the effect. A consumer caching
@@ -101,6 +138,10 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         try {
             if (typeof window === 'undefined')
                 return;
+            // Opt-out is checked at call time (not init time) so a visitor who
+            // opts out mid-session stops firing immediately on the next track().
+            if (isOptedOut())
+                return;
             if (!eventName || typeof eventName !== 'string')
                 return;
             const name = eventName.trim().toLowerCase();
@@ -118,19 +159,11 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             };
             if (metadata && typeof metadata === 'object')
                 payload.metadata = metadata;
-            const data = JSON.stringify(payload);
-            const endpoint = `${apiBase}/api/v1/web/event`;
-            if (navigator.sendBeacon) {
-                navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
-            }
-            else {
-                fetch(endpoint, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: data,
-                    keepalive: true,
-                }).catch(() => { });
-            }
+            // Enqueue. EventQueue handles persist, retry, and flush. If the
+            // queue hasn't initialized yet (called during first render before
+            // useEffect runs), this noops — that's a vanishingly rare race
+            // since track() is virtually always called from a click handler.
+            queueRef.current?.enqueue(`${apiBase}/api/v1/web/event`, payload);
         }
         catch { /* swallow */ }
     }, [apiBase]);
@@ -141,6 +174,8 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         try {
             if (typeof window === 'undefined')
                 return;
+            if (isOptedOut())
+                return;
             if (!userId || typeof userId !== 'string')
                 return;
             const uid = userId.trim();
@@ -158,22 +193,109 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
                 visitor_id: vid,
                 user_id: uid,
             };
-            const data = JSON.stringify(payload);
-            const url = `${apiBase}/api/v1/web/identify`;
-            if (navigator.sendBeacon) {
-                navigator.sendBeacon(url, new Blob([data], { type: 'application/json' }));
-            }
-            else {
-                fetch(url, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: data,
-                    keepalive: true,
-                }).catch(() => { });
-            }
+            queueRef.current?.enqueue(`${apiBase}/api/v1/web/identify`, payload);
+        }
+        catch { /* swallow */ }
+    }, [apiBase]);
+    // Manual pageview. Mirrors Datafast's trackPageview(path?). Same payload
+    // shape the auto-fired pageview uses (see sendPageview inside the route
+    // effect below) so server-side routing / dedup / IP+UA enrichment behave
+    // identically for both code paths.
+    //
+    // Defined here as a useCallback (not inside the effect) so React consumers
+    // who cache the function reference across renders aren't pointing at a
+    // stale closure. Reads from refs for the per-render-stable bits and
+    // localStorage for the persisted attribution (ref code), so the call
+    // always sees the latest values.
+    const trackPageview = useCallback(async (path) => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            if (isOptedOut())
+                return;
+            const cid = campaignIdRef.current;
+            const vid = visitorIdRef.current;
+            if (!cid || !vid)
+                return;
+            const params = new URLSearchParams(window.location.search);
+            const pagePath = path || window.location.pathname;
+            // url: if caller passed a path, resolve it against origin for a full
+            // href the server can dedup on. Otherwise use the actual location.
+            const url = path
+                ? new URL(path, window.location.origin).href
+                : window.location.href;
+            const payload = {
+                type: 'pageview',
+                campaign_id: cid,
+                visitor_id: vid,
+                url,
+                path: pagePath,
+                hostname: window.location.hostname,
+                referrer: document.referrer || '',
+                ref: lsGet(LS_REF) || '',
+                utm_source: params.get('utm_source') || '',
+                utm_medium: params.get('utm_medium') || '',
+                utm_campaign: params.get('utm_campaign') || '',
+                screen_width: window.innerWidth,
+            };
+            queueRef.current?.enqueue(`${apiBase}/api/v1/web/event`, payload);
         }
         catch { /* swallow */ }
     }, [apiBase]);
+    // reset(): wipe visitor identity. Mints a fresh UUID and clears the
+    // affiliate ref so the next pageview is a brand-new anonymous visitor.
+    // The campaign_id stays (it's a property of the site, not the visitor).
+    //
+    // Matches Datafast's reset() semantics for non-cookieless mode: new
+    // visitor, no event fired, caller handles "tell the server about it"
+    // by triggering whatever pageview / navigation comes next.
+    //
+    // Returns a Promise so callers can `await reset()` before navigating
+    // (the localStorage writes are sync but the Promise lets the API stay
+    // consistent with Datafast's async signature, future-proofing for
+    // server-minted IDs in cookieless mode).
+    const reset = useCallback(async () => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            // Drain any pending events for the OLD visitor before swapping IDs,
+            // otherwise they'd land server-side stamped to the OLD visitor_id
+            // (correct) but persisted-in-localStorage as if to-be-retried under
+            // the new identity — confusing on retry inspection. Best effort.
+            void queueRef.current?.flush();
+            queueRef.current?.clear();
+            const newVid = uuid();
+            lsSet(LS_VISITOR_ID, newVid);
+            lsRemove(LS_REF);
+            visitorIdRef.current = newVid;
+            setState((prev) => ({ ...prev, visitorId: newVid, refCode: null }));
+        }
+        catch { /* swallow */ }
+    }, []);
+    // optOut(): persistent "don't track me" flag. After this call every
+    // track / identify / trackPageview noops until optIn() is called. The
+    // flag survives reloads via localStorage, so a visitor who opts out
+    // stays opted out across browser sessions on the same device.
+    //
+    // We don't actively send a "stop tracking me" signal to the server —
+    // the server only knows about visitors who ping it, so an opted-out
+    // visitor simply stops appearing. The visitor row left behind in
+    // Postgres ages out via normal retention.
+    const optOut = useCallback(() => {
+        lsSet(LS_OPT_OUT, 'true');
+        // Drop pending events too. The visitor explicitly said no — sending
+        // queued events from before the opt-out would still violate consent
+        // even if those events were captured prior to the user's decision.
+        queueRef.current?.clear();
+    }, []);
+    // optIn(): remove the opt-out flag. Tracking RESUMES for any future
+    // calls (track / identify / trackPageview) but the in-flight auto-
+    // pageview that already noop'd on this render won't retroactively
+    // send. A page reload is the cleanest way to get a fresh auto-fired
+    // pageview after opting back in.
+    const optIn = useCallback(() => {
+        lsRemove(LS_OPT_OUT);
+    }, []);
     const sentRef = useRef(false);
     useEffect(() => {
         if (typeof window === 'undefined')
@@ -186,6 +308,65 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             // eslint-disable-next-line no-console
             console.warn('[Affiliateo] AffiliateoProvider mounted more than once. Mount it exactly once near the root of your app, or pageviews will double-fire.');
         }
+        // Client-side bot detection. If the current browser context looks
+        // like Selenium / Puppeteer / curl / a known automation tool, skip
+        // ALL tracking before we even mint a queue. The server-side UA
+        // regex + Turnstile catch anything that sneaks past this check —
+        // this just saves the bot a round-trip and saves us a request.
+        //
+        // The hook still returns the four control methods (reset / optOut /
+        // etc) so a host UI that happens to render in a headless context
+        // doesn't crash on `useAffiliateRef().reset()`. They're noops, which
+        // is the correct behavior since there's no real visitor to act on.
+        if (isLikelyBot()) {
+            setState({
+                refCode: null,
+                visitorId: null,
+                track: asyncNoop,
+                identify: asyncNoop,
+                trackPageview: asyncNoop,
+                reset: asyncNoop,
+                optOut: syncNoop,
+                optIn: syncNoop,
+            });
+            return;
+        }
+        // Initialize the event queue. Done inside useEffect (not in a useRef
+        // initializer) so the EventQueue constructor — which touches
+        // localStorage on hydration — only ever runs client-side. The queue
+        // takes over delivery for track / identify / trackPageview AND the
+        // auto-fired pageview below; only session_end stays on sendBeacon
+        // because tab-close urgency beats queue-retry reliability.
+        if (queueRef.current === null) {
+            queueRef.current = new EventQueue();
+        }
+        const queue = queueRef.current;
+        // Opt-out short-circuit. A visitor who previously called optOut()
+        // gets ZERO outbound traffic on this page load. We still mint the
+        // visitor_id (so optIn() + reload picks up the same identity rather
+        // than starting fresh, which would split their history), but skip
+        // ALL beacons including the auto-pageview, plus skip the event
+        // listeners (no point in firing session_end for a visitor we never
+        // told the server about). The hook still returns the four control
+        // methods so the host's banner UI can call optIn() / reset().
+        if (isOptedOut()) {
+            let optedOutVid = lsGet(LS_VISITOR_ID);
+            if (!optedOutVid) {
+                optedOutVid = uuid();
+                lsSet(LS_VISITOR_ID, optedOutVid);
+            }
+            visitorIdRef.current = optedOutVid;
+            setState({
+                refCode: null,
+                visitorId: optedOutVid,
+                track, identify, trackPageview, reset, optOut, optIn,
+            });
+            // Don't leave a queue running for an opted-out visitor — the timer
+            // would just keep waking up to flush nothing.
+            queue.shutdown();
+            queueRef.current = null;
+            return;
+        }
         // Get or create visitor ID
         let vid = lsGet(LS_VISITOR_ID);
         if (!vid) {
@@ -202,21 +383,11 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             lsSet(LS_REF, ref);
         }
         const endpoint = `${apiBase}/api/v1/web/event`;
-        setState({ refCode: ref, visitorId: vid, track, identify });
-        function beacon(payload) {
-            const data = JSON.stringify(payload);
-            if (navigator.sendBeacon) {
-                navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
-            }
-            else {
-                fetch(endpoint, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: data,
-                    keepalive: true,
-                }).catch(() => { });
-            }
-        }
+        setState({
+            refCode: ref,
+            visitorId: vid,
+            track, identify, trackPageview, reset, optOut, optIn,
+        });
         // Throttle: max 1 pageview per second
         let lastSendTime = 0;
         function sendPageview() {
@@ -225,7 +396,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
                 return;
             lastSendTime = now;
             ended = false;
-            beacon({
+            queue.enqueue(endpoint, {
                 type: 'pageview',
                 campaign_id: campaignIdRef.current,
                 visitor_id: vid,
@@ -240,13 +411,43 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
                 screen_width: window.innerWidth,
             });
         }
-        // Send session_end when user leaves
+        // Send session_end when user leaves.
+        //
+        // session_end intentionally bypasses the queue and uses sendBeacon
+        // directly. The queue's fetch-with-keepalive is great for normal
+        // events because it returns a status code we can retry on, but it
+        // can't guarantee the request lands when the tab is in the act of
+        // closing — fetch may be aborted mid-flight. sendBeacon was
+        // designed exactly for this case and CANNOT be cancelled by the
+        // unload handler. We also try to drain the queue's pending events
+        // here, which uses sendBeacon under the hood for the same reason.
         let ended = false;
         function sendEnd() {
             if (ended)
                 return;
             ended = true;
-            beacon({ type: 'session_end', campaign_id: campaignIdRef.current, visitor_id: vid, ref: ref || lsGet(LS_REF) || '' });
+            // Drain the queue first so any pending track / identify events
+            // get a last shot before the tab closes. flushOnUnload uses
+            // sendBeacon internally, no retry needed because there's no
+            // retry opportunity after this.
+            queue.flushOnUnload();
+            const data = JSON.stringify({
+                type: 'session_end',
+                campaign_id: campaignIdRef.current,
+                visitor_id: vid,
+                ref: ref || lsGet(LS_REF) || '',
+            });
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
+            }
+            else {
+                fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: data,
+                    keepalive: true,
+                }).catch(() => { });
+            }
         }
         // Server-side session window. Matches STALE_VISITOR_MS in the
         // tracking Durable Object — after this much idle time the server
@@ -303,113 +504,30 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             origReplaceState.apply(this, args);
             onUrlChange();
         };
-        // HTML-attribute goal tracking. match Datafast's `data-fast-goal`
-        // ergonomics. Any element with `data-affiliateo-goal="event_name"`
-        // fires that goal on click. Optional `data-affiliateo-goal-*`
-        // attributes become metadata (kebab-case to snake_case, max 10).
+        // HTML-attribute goal scanning (`data-affiliateo-goal`,
+        // `data-affiliateo-scroll`) and the IntersectionObserver that drove
+        // them were removed in 3.0.0 to match Datafast's npm SDK ergonomics:
+        // SDK does pageview + track() + identify(); merchants fire goals
+        // themselves via onClick={() => track('signup_clicked')} or by
+        // wiring their own IntersectionObserver and calling track() from it.
         //
-        // Delegated listener on document.body so the merchant doesn't have
-        // to re-attach handlers when their SPA re-renders. Capture phase off
-        // so React's synthetic event ordering isn't disturbed.
-        function onDocClick(e) {
-            const target = e.target;
-            if (!(target instanceof Element))
-                return;
-            const el = target.closest('[data-affiliateo-goal]');
-            if (!el)
-                return;
-            const goal = el.getAttribute('data-affiliateo-goal');
-            if (!goal)
-                return;
-            const meta = {};
-            let count = 0;
-            for (const { name, value } of Array.from(el.attributes)) {
-                if (!name.startsWith('data-affiliateo-goal-'))
-                    continue;
-                // Skip the bare "data-affiliateo-goal" attribute itself
-                // (slice would produce an empty key).
-                if (name === 'data-affiliateo-goal')
-                    continue;
-                if (count >= 10)
-                    break;
-                const key = name.slice('data-affiliateo-goal-'.length).replace(/-/g, '_');
-                // Skip the reserved `event` key so an attribute like
-                // `data-affiliateo-goal-event="x"` can't override the actual
-                // goal name when the SDK / server folds metadata.event in.
-                if (!key || key === 'event')
-                    continue;
-                if (value) {
-                    meta[key] = String(value).slice(0, 255);
-                    count++;
-                }
-            }
-            track(goal, count ? meta : undefined);
-        }
-        document.addEventListener('click', onDocClick);
-        // Scroll-depth goal tracking. `data-affiliateo-scroll="event_name"`
-        // on any element fires that goal the first time the element enters
-        // the viewport. Use IntersectionObserver (cheap, off the scroll hot
-        // path) and unobserve after the first fire so the same element can't
-        // double-count if the user scrolls back up.
-        //
-        // No options object → IntersectionObserver defaults to
-        // { threshold: 0, rootMargin: '0px 0px 0px 0px' }, which fires the
-        // instant ANY pixel of the section overlaps the viewport. That's
-        // exactly the semantic merchants want for "did the visitor reach
-        // this section": if they scrolled enough to see even a sliver of
-        // it, count it. Earlier versions used { threshold: 0.5 }, which
-        // was unreachable for tall sections (a 1600px pricing section in
-        // an 800px viewport tops out at ~50% intersection ratio and never
-        // crossed the threshold) — funnel steps tied to those sections
-        // silently dropped from every merchant's conversion count.
-        const scrollFired = new WeakSet();
-        let scrollObserver = null;
-        let scrollMo = null;
-        if (typeof IntersectionObserver !== 'undefined') {
-            scrollObserver = new IntersectionObserver((entries) => {
-                for (const entry of entries) {
-                    if (!entry.isIntersecting)
-                        continue;
-                    if (scrollFired.has(entry.target))
-                        continue;
-                    scrollFired.add(entry.target);
-                    const goal = entry.target.getAttribute('data-affiliateo-scroll');
-                    if (goal)
-                        track(goal);
-                    scrollObserver?.unobserve(entry.target);
-                }
-            });
-            // Observe everything that exists at mount time.
-            document.querySelectorAll('[data-affiliateo-scroll]').forEach((el) => {
-                scrollObserver?.observe(el);
-            });
-            // SPA-rendered sections that appear later get observed via
-            // MutationObserver. Cheap because we only scan added nodes, not
-            // the whole tree on each mutation.
-            scrollMo = new MutationObserver((mutations) => {
-                for (const m of mutations) {
-                    m.addedNodes.forEach((node) => {
-                        if (!(node instanceof Element))
-                            return;
-                        if (node.hasAttribute('data-affiliateo-scroll'))
-                            scrollObserver?.observe(node);
-                        node.querySelectorAll?.('[data-affiliateo-scroll]').forEach((el) => scrollObserver?.observe(el));
-                    });
-                }
-            });
-            scrollMo.observe(document.body, { childList: true, subtree: true });
-        }
+        // Why removed: the scanning layer was the source of every funnel
+        // bug we hit (threshold:0 firing on hero sections, SPA mutation
+        // observer races, client-side step matching from HTML). Removing it
+        // also drops ~80 lines of code and one extra DOM observer per page.
         return () => {
             document.removeEventListener('visibilitychange', onVisibilityChange);
             window.removeEventListener('pagehide', sendEnd);
             window.removeEventListener('popstate', onUrlChange);
-            document.removeEventListener('click', onDocClick);
-            scrollMo?.disconnect();
-            scrollObserver?.disconnect();
             history.pushState = origPushState;
             history.replaceState = origReplaceState;
+            // Stop the queue's flush timer. The queue tries one final flush
+            // before going quiet — anything still queued lives in localStorage
+            // and will be picked up by the next page load's queue init.
+            queue.shutdown();
+            queueRef.current = null;
             providerMountCount = Math.max(0, providerMountCount - 1);
         };
-    }, [apiBase, track, identify]);
+    }, [apiBase, track, identify, trackPageview, reset, optOut, optIn]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/queue.d.ts

@@ -0,0 +1,99 @@
+/**
+ * EventQueue: durable best-effort delivery for analytics events.
+ *
+ * Why this exists:
+ *   Before this module, every track / identify / pageview was fire-and-forget
+ *   via navigator.sendBeacon. If the visitor's network blinked, the server
+ *   was briefly overloaded, or any other transient failure hit, the event
+ *   was lost with no retry, no log, no observability. On flaky mobile
+ *   networks (train wifi, subway transitions, dropping 4G) merchants saw
+ *   ~10-15% fewer events than they should have.
+ *
+ *   This queue mirrors the pattern PostHog / Segment / Amplitude / Datafast
+ *   all converged on: in-memory queue, localStorage persistence so events
+ *   survive page reload, periodic auto-flush, retry on failure up to N
+ *   times, drop after N tries to bound memory.
+ *
+ * Design notes:
+ *   - Persisted state is JSON in localStorage under STORAGE_KEY. The
+ *     persisted shape is intentionally simple (id + payload + retries)
+ *     so a future schema bump doesn't break a visitor who upgraded
+ *     mid-session and has events from the old shape sitting around.
+ *   - Failures are silent. The host app should never see an analytics
+ *     error bubble up. Console-noise during dev is the only signal.
+ *   - sendBeacon is NOT used here. sendBeacon is great for "fire on
+ *     unload" but it doesn't return a response we can branch on for
+ *     retry. fetch + keepalive gives us a status code AND lets the
+ *     browser keep the request alive across navigation. Trade-off: a
+ *     queued event fired right before the visitor closes the tab might
+ *     not land. That's why session_end stays on sendBeacon (see
+ *     provider.tsx, sendEnd helper).
+ *   - The flush timer uses setInterval. Stopped on shutdown(). The
+ *     provider only ever creates one queue per mount, so timer leaks
+ *     aren't a practical concern.
+ *
+ * Caps:
+ *   - MAX_RETRIES = 3   per-event retry ceiling before drop
+ *   - MAX_QUEUE_SIZE   hard cap so a long network outage can't fill
+ *                      localStorage and break the host app. Events
+ *                      beyond the cap are dropped FIFO (oldest first).
+ *   - FLUSH_INTERVAL_MS = 5_000   matches Datafast's web SDK default
+ *   - SIZE_FLUSH_THRESHOLD = 10   triggers a flush when queue grows
+ *                                 past this even before the timer fires
+ */
+export interface QueuedEvent {
+    /** Stable id used to identify the event across retries. UUID v4
+     *  generated client-side; collisions are astronomically unlikely so
+     *  we don't bother with a fallback. */
+    id: string;
+    /** The exact body the server expects. We persist the full payload
+     *  (not a delta) so a visitor who reloads mid-flush can still recover
+     *  every queued event without needing to know the original call site. */
+    payload: Record<string, unknown>;
+    /** Endpoint to POST to. Keyed per-event so a single queue can hold
+     *  both /api/v1/web/event (track + pageview) and /api/v1/web/identify
+     *  events without a separate queue per endpoint. */
+    endpoint: string;
+    /** Retry counter. Incremented on each failed flush. Event is dropped
+     *  when this hits MAX_RETRIES. */
+    retries: number;
+}
+export declare class EventQueue {
+    private queue;
+    private flushTimer;
+    private isFlushing;
+    private shuttingDown;
+    constructor();
+    /** Add an event. Persists synchronously to localStorage so a tab
+     *  close right after enqueue doesn't lose the event from memory
+     *  before it's safely on disk. */
+    enqueue(endpoint: string, payload: Record<string, unknown>): void;
+    /** Try to deliver every queued event. Each event gets one attempt
+     *  per flush; failures bump retries and stay in the queue for the
+     *  next flush. Events that hit MAX_RETRIES get dropped.
+     *
+     *  Concurrency: guarded by isFlushing so overlapping calls (the
+     *  burst path + the timer firing simultaneously) only run one
+     *  flush at a time. */
+    flush(): Promise<void>;
+    /** Best-effort sync flush triggered on page unload. Uses sendBeacon
+     *  for each event so it survives the tab closing. No retry — this is
+     *  the last chance.
+     *
+     *  Called from the provider's pagehide / visibilitychange=hidden
+     *  handlers so any events still queued at unload get one last shot.
+     *  After this call, the in-memory queue is cleared (events that
+     *  sendBeacon couldn't queue are lost — that's the cost of the
+     *  guaranteed-fast unload path). */
+    flushOnUnload(): void;
+    /** Wipe the queue. Called by reset() and optOut(). Removes the
+     *  localStorage entry entirely so a reload doesn't re-hydrate the
+     *  wiped events. */
+    clear(): void;
+    /** Stop the flush timer and try one final flush. Idempotent. */
+    shutdown(): void;
+    /** Read-only size getter. Used by tests / debug consoles. */
+    get size(): number;
+    private persist;
+    private startFlushTimer;
+}

package/dist/queue.js

@@ -0,0 +1,266 @@
+/**
+ * EventQueue: durable best-effort delivery for analytics events.
+ *
+ * Why this exists:
+ *   Before this module, every track / identify / pageview was fire-and-forget
+ *   via navigator.sendBeacon. If the visitor's network blinked, the server
+ *   was briefly overloaded, or any other transient failure hit, the event
+ *   was lost with no retry, no log, no observability. On flaky mobile
+ *   networks (train wifi, subway transitions, dropping 4G) merchants saw
+ *   ~10-15% fewer events than they should have.
+ *
+ *   This queue mirrors the pattern PostHog / Segment / Amplitude / Datafast
+ *   all converged on: in-memory queue, localStorage persistence so events
+ *   survive page reload, periodic auto-flush, retry on failure up to N
+ *   times, drop after N tries to bound memory.
+ *
+ * Design notes:
+ *   - Persisted state is JSON in localStorage under STORAGE_KEY. The
+ *     persisted shape is intentionally simple (id + payload + retries)
+ *     so a future schema bump doesn't break a visitor who upgraded
+ *     mid-session and has events from the old shape sitting around.
+ *   - Failures are silent. The host app should never see an analytics
+ *     error bubble up. Console-noise during dev is the only signal.
+ *   - sendBeacon is NOT used here. sendBeacon is great for "fire on
+ *     unload" but it doesn't return a response we can branch on for
+ *     retry. fetch + keepalive gives us a status code AND lets the
+ *     browser keep the request alive across navigation. Trade-off: a
+ *     queued event fired right before the visitor closes the tab might
+ *     not land. That's why session_end stays on sendBeacon (see
+ *     provider.tsx, sendEnd helper).
+ *   - The flush timer uses setInterval. Stopped on shutdown(). The
+ *     provider only ever creates one queue per mount, so timer leaks
+ *     aren't a practical concern.
+ *
+ * Caps:
+ *   - MAX_RETRIES = 3   per-event retry ceiling before drop
+ *   - MAX_QUEUE_SIZE   hard cap so a long network outage can't fill
+ *                      localStorage and break the host app. Events
+ *                      beyond the cap are dropped FIFO (oldest first).
+ *   - FLUSH_INTERVAL_MS = 5_000   matches Datafast's web SDK default
+ *   - SIZE_FLUSH_THRESHOLD = 10   triggers a flush when queue grows
+ *                                 past this even before the timer fires
+ */
+const STORAGE_KEY = 'affiliateo_event_queue';
+const MAX_RETRIES = 3;
+const MAX_QUEUE_SIZE = 100;
+const FLUSH_INTERVAL_MS = 5000;
+const SIZE_FLUSH_THRESHOLD = 10;
+function lsGet(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function lsSet(key, value) {
+    try {
+        localStorage.setItem(key, value);
+    }
+    catch { /* quota / private mode */ }
+}
+function lsRemove(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch { /* swallow */ }
+}
+function uuid() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID)
+        return crypto.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export class EventQueue {
+    constructor() {
+        this.queue = [];
+        this.flushTimer = null;
+        this.isFlushing = false;
+        this.shuttingDown = false;
+        // Hydrate from localStorage so events from a prior page load survive
+        // a refresh / navigation. Guards against corrupt JSON or wrong-shape
+        // entries by resetting to empty if anything looks off — better to
+        // lose a few stuck events than crash the host app on init.
+        try {
+            const raw = lsGet(STORAGE_KEY);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed)) {
+                    this.queue = parsed.filter((e) => !!e && typeof e === 'object'
+                        && typeof e.id === 'string'
+                        && typeof e.endpoint === 'string'
+                        && typeof e.payload === 'object'
+                        && typeof e.retries === 'number');
+                }
+            }
+        }
+        catch {
+            this.queue = [];
+        }
+        this.startFlushTimer();
+        // Try an immediate flush on construction so events left over from
+        // a previous session get a head start (especially useful on the
+        // page-load-after-an-outage scenario).
+        if (this.queue.length > 0) {
+            void this.flush();
+        }
+    }
+    /** Add an event. Persists synchronously to localStorage so a tab
+     *  close right after enqueue doesn't lose the event from memory
+     *  before it's safely on disk. */
+    enqueue(endpoint, payload) {
+        if (this.shuttingDown)
+            return;
+        this.queue.push({
+            id: uuid(),
+            endpoint,
+            payload,
+            retries: 0,
+        });
+        // FIFO drop when over cap. Network outage edge case: if we're way
+        // over budget the oldest events are likely already stale (the
+        // visitor moved on, the page they were on isn't current) so
+        // dropping them preserves more value than dropping the new ones.
+        if (this.queue.length > MAX_QUEUE_SIZE) {
+            this.queue.splice(0, this.queue.length - MAX_QUEUE_SIZE);
+        }
+        this.persist();
+        // Burst protection: when many events fire in quick succession
+        // (auto-pageview + immediate track + identify on app boot), don't
+        // wait for the 5s timer — flush right away. The isFlushing guard
+        // inside flush() makes overlapping calls safe.
+        if (this.queue.length >= SIZE_FLUSH_THRESHOLD) {
+            void this.flush();
+        }
+    }
+    /** Try to deliver every queued event. Each event gets one attempt
+     *  per flush; failures bump retries and stay in the queue for the
+     *  next flush. Events that hit MAX_RETRIES get dropped.
+     *
+     *  Concurrency: guarded by isFlushing so overlapping calls (the
+     *  burst path + the timer firing simultaneously) only run one
+     *  flush at a time. */
+    async flush() {
+        if (this.isFlushing || this.queue.length === 0)
+            return;
+        this.isFlushing = true;
+        // Snapshot the queue so we iterate a stable list — new enqueue()
+        // calls during the flush land in the live queue and get picked up
+        // by the next flush rather than this one (avoids infinite loops
+        // and reasoning headaches).
+        const batch = this.queue.slice();
+        for (const event of batch) {
+            let ok = false;
+            try {
+                const res = await fetch(event.endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(event.payload),
+                    // keepalive lets the request survive a navigation. paired
+                    // with the queue so even if this fetch errors, we'll retry.
+                    keepalive: true,
+                });
+                // 2xx = success. Anything else (4xx, 5xx) counts as a failure
+                // and bumps retries. A 4xx is usually a permanent error
+                // (bad payload, dead campaign) so retrying 3 times then
+                // dropping is the right move — keeps the queue clean.
+                ok = res.ok;
+            }
+            catch {
+                ok = false;
+            }
+            if (ok) {
+                // Remove from live queue (not the snapshot) by id
+                this.queue = this.queue.filter((e) => e.id !== event.id);
+            }
+            else {
+                // Find the live entry and bump its retry counter. Use id
+                // because the index may have shifted if other events were
+                // already removed on this pass.
+                const live = this.queue.find((e) => e.id === event.id);
+                if (live) {
+                    live.retries++;
+                    if (live.retries >= MAX_RETRIES) {
+                        this.queue = this.queue.filter((e) => e.id !== event.id);
+                    }
+                }
+            }
+        }
+        this.persist();
+        this.isFlushing = false;
+    }
+    /** Best-effort sync flush triggered on page unload. Uses sendBeacon
+     *  for each event so it survives the tab closing. No retry — this is
+     *  the last chance.
+     *
+     *  Called from the provider's pagehide / visibilitychange=hidden
+     *  handlers so any events still queued at unload get one last shot.
+     *  After this call, the in-memory queue is cleared (events that
+     *  sendBeacon couldn't queue are lost — that's the cost of the
+     *  guaranteed-fast unload path). */
+    flushOnUnload() {
+        if (this.queue.length === 0)
+            return;
+        if (typeof navigator === 'undefined' || !navigator.sendBeacon) {
+            // No sendBeacon (very old browser) — try a sync fetch with
+            // keepalive as a fallback. Won't actually finish, but it's our
+            // last shot.
+            for (const event of this.queue) {
+                try {
+                    fetch(event.endpoint, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify(event.payload),
+                        keepalive: true,
+                    }).catch(() => { });
+                }
+                catch { /* swallow */ }
+            }
+            this.queue = [];
+            this.persist();
+            return;
+        }
+        for (const event of this.queue) {
+            try {
+                navigator.sendBeacon(event.endpoint, new Blob([JSON.stringify(event.payload)], { type: 'application/json' }));
+            }
+            catch { /* swallow */ }
+        }
+        this.queue = [];
+        this.persist();
+    }
+    /** Wipe the queue. Called by reset() and optOut(). Removes the
+     *  localStorage entry entirely so a reload doesn't re-hydrate the
+     *  wiped events. */
+    clear() {
+        this.queue = [];
+        lsRemove(STORAGE_KEY);
+    }
+    /** Stop the flush timer and try one final flush. Idempotent. */
+    shutdown() {
+        this.shuttingDown = true;
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        void this.flush();
+    }
+    /** Read-only size getter. Used by tests / debug consoles. */
+    get size() {
+        return this.queue.length;
+    }
+    persist() {
+        lsSet(STORAGE_KEY, JSON.stringify(this.queue));
+    }
+    startFlushTimer() {
+        if (this.flushTimer !== null)
+            return;
+        this.flushTimer = setInterval(() => {
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+    }
+}

package/dist/types.d.ts

@@ -34,4 +34,54 @@ export interface AffiliateoContextValue {
      *    const { identify } = useAffiliateRef()
      *    useEffect(() => { if (user) identify(user.id) }, [user]) */
     identify: (userId: string) => Promise<void>;
+    /** Manually fire a pageview. The SDK already auto-fires on mount and on
+     *  SPA route changes; use this only when you want extra control (e.g.
+     *  tracking modal opens as virtual pageviews, or merchants who disabled
+     *  auto-pageviews for custom routing).
+     *
+     *  - With no args: tracks the CURRENT page (same as the auto-fired one).
+     *  - With a path: tracks that path. Useful for virtual pages.
+     *
+     *  Example:
+     *    const { trackPageview } = useAffiliateRef()
+     *    function PricingModal({ open }: { open: boolean }) {
+     *      useEffect(() => { if (open) trackPageview('/pricing-modal') }, [open])
+     *    } */
+    trackPageview: (path?: string) => Promise<void>;
+    /** Wipe the visitor identity. Mints a fresh visitor_id and clears the
+     *  affiliate ref + campaign_id from localStorage so the next pageview
+     *  is treated as a brand-new anonymous visitor.
+     *
+     *  Use case: call on user logout so a different person sitting down at
+     *  the same browser doesn't get their actions merged into the previous
+     *  user's funnel. Without this, shared family computers / kiosks /
+     *  hot-desks silently pollute attribution.
+     *
+     *  Example:
+     *    const { reset } = useAffiliateRef()
+     *    async function handleLogout() {
+     *      await supabase.auth.signOut()
+     *      await reset()
+     *      router.push('/')
+     *    } */
+    reset: () => Promise<void>;
+    /** Stop tracking this visitor. Sets a persistent opt-out flag in
+     *  localStorage and silences all subsequent track / identify / pageview
+     *  calls until optIn() is called. Survives reloads, doesn't survive a
+     *  hard browser reset.
+     *
+     *  Use case: GDPR / CCPA cookie banner where the visitor picked
+     *  "Don't track me." Call optOut() once and the SDK noops everything
+     *  for that visitor.
+     *
+     *  Example:
+     *    const { optOut } = useAffiliateRef()
+     *    <button onClick={() => optOut()}>Don't track me</button> */
+    optOut: () => void;
+    /** Re-enable tracking after a previous optOut(). Removes the persistent
+     *  flag. Note: tracking only resumes for events fired AFTER this call,
+     *  the current pageview won't retroactively send. A full page reload is
+     *  the cleanest way to bring the SDK back to its normal "auto-fire on
+     *  mount" state. */
+    optIn: () => void;
 }

package/package.json

@@ -1,34 +1,34 @@
-{
-  "name": "@affiliateo/web",
-  "version": "2.4.0",
-  "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/react": "^19.0.0",
-    "typescript": "^5.0.0"
-  },
-  "keywords": ["affiliateo", "affiliate", "attribution", "stripe", "web", "session", "tracking"],
-  "license": "MIT",
-  "files": ["dist"]
-}
+{
+  "name": "@affiliateo/web",
+  "version": "3.0.0",
+  "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": ["affiliateo", "affiliate", "attribution", "stripe", "web", "session", "tracking"],
+  "license": "MIT",
+  "files": ["dist"]
+}