@affiliateo/web 3.1.0 → 4.1.0

package/dist/dev-host.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Dev-host detection for the SDK. Returns true when the current hostname
+ * is obviously a developer's machine and not a real production site.
+ *
+ * The SDK uses this to short-circuit tracking by default (allowLocalhost
+ * defaults to false). Stops the "Quegly funnel pollution" pattern where
+ * a developer running `npm run dev` against localhost:3000 fires hundreds
+ * of pageviews into the production funnel.
+ *
+ * IMPORTANT: this list is INTENTIONALLY TIGHTER than the server-side
+ * `src/lib/analytics/dev-host.ts` helper. The server helper is used for
+ * domain-binding logic and can be aggressive about catching staging /
+ * preview deploys (.vercel.app, .pages.dev). The SDK helper cannot,
+ * because some merchants legitimately run their production site on a
+ * .vercel.app subdomain (no custom domain) and we'd silently break their
+ * tracking. So we only catch the unambiguous cases:
+ *
+ *   - localhost / 127.0.0.1 / 0.0.0.0 / ::1   (literal local)
+ *   - RFC1918 private IPs (10.x, 192.168.x, 172.16-31.x)
+ *   - .local / .test / .example / .invalid / .localhost  (RFC-reserved
+ *     dev TLDs that cannot exist in production)
+ *   - .lvh.me / .localtest.me                  (well-known dev wildcards
+ *     that ALWAYS resolve to 127.0.0.1)
+ *
+ * NOT included on the SDK side: .ngrok.io, .vercel.app, .netlify.app,
+ * .pages.dev, .workers.dev, .trycloudflare.com. A merchant doing a
+ * staging-on-Vercel preview deploy should still see tracking work; if
+ * they want it OFF for staging they can set allowLocalhost explicitly.
+ */
+export declare function isDevHost(host: string | null | undefined): boolean;

package/dist/dev-host.js

@@ -0,0 +1,48 @@
+/**
+ * Dev-host detection for the SDK. Returns true when the current hostname
+ * is obviously a developer's machine and not a real production site.
+ *
+ * The SDK uses this to short-circuit tracking by default (allowLocalhost
+ * defaults to false). Stops the "Quegly funnel pollution" pattern where
+ * a developer running `npm run dev` against localhost:3000 fires hundreds
+ * of pageviews into the production funnel.
+ *
+ * IMPORTANT: this list is INTENTIONALLY TIGHTER than the server-side
+ * `src/lib/analytics/dev-host.ts` helper. The server helper is used for
+ * domain-binding logic and can be aggressive about catching staging /
+ * preview deploys (.vercel.app, .pages.dev). The SDK helper cannot,
+ * because some merchants legitimately run their production site on a
+ * .vercel.app subdomain (no custom domain) and we'd silently break their
+ * tracking. So we only catch the unambiguous cases:
+ *
+ *   - localhost / 127.0.0.1 / 0.0.0.0 / ::1   (literal local)
+ *   - RFC1918 private IPs (10.x, 192.168.x, 172.16-31.x)
+ *   - .local / .test / .example / .invalid / .localhost  (RFC-reserved
+ *     dev TLDs that cannot exist in production)
+ *   - .lvh.me / .localtest.me                  (well-known dev wildcards
+ *     that ALWAYS resolve to 127.0.0.1)
+ *
+ * NOT included on the SDK side: .ngrok.io, .vercel.app, .netlify.app,
+ * .pages.dev, .workers.dev, .trycloudflare.com. A merchant doing a
+ * staging-on-Vercel preview deploy should still see tracking work; if
+ * they want it OFF for staging they can set allowLocalhost explicitly.
+ */
+const RFC1918_RE = /^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)/;
+const DEV_TLD_SUFFIXES = ['.local', '.test', '.example', '.invalid', '.localhost'];
+const DEV_HOST_SUFFIXES = ['.lvh.me', '.localtest.me'];
+export function isDevHost(host) {
+    if (!host)
+        return false;
+    const h = host.toLowerCase();
+    if (h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0' || h === '::1')
+        return true;
+    if (RFC1918_RE.test(h))
+        return true;
+    for (const s of DEV_TLD_SUFFIXES)
+        if (h.endsWith(s))
+            return true;
+    for (const s of DEV_HOST_SUFFIXES)
+        if (h.endsWith(s))
+            return true;
+    return false;
+}

package/dist/provider.d.ts

@@ -18,6 +18,6 @@ export declare function useAffiliateRef(): AffiliateoContextValue;
  * ```
  */
 export declare function getAttribution(): Record<string, string>;
-export declare function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, children, }: AffiliateoConfig & {
+export declare function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }: AffiliateoConfig & {
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/provider.js

@@ -3,6 +3,7 @@ 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';
+import { isDevHost } from './dev-host';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
@@ -60,6 +61,7 @@ const AffiliateoContext = createContext({
     reset: asyncNoop,
     optOut: syncNoop,
     optIn: syncNoop,
+    flush: asyncNoop,
 });
 /**
  * Returns the affiliate ref code and visitor ID.
@@ -100,7 +102,26 @@ export function getAttribution() {
 // mount (host has the call sites) but we can shout in dev so the
 // mistake is visible.
 let providerMountCount = 0;
-export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, children, }) {
+export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }) {
+    // Normalize autoCapturePageviews. Three shapes:
+    //   - undefined / true / object → auto-capture ON (with object overrides)
+    //   - false → auto-capture OFF entirely (host must call trackPageview)
+    // Defaults match Datafast: captureInitialPageview true, trackHashChanges
+    // false, debounceMs 100.
+    const autoCfg = autoCapturePageviews === false
+        ? { enabled: false, captureInitialPageview: false, trackHashChanges: false, debounceMs: 100 }
+        : {
+            enabled: true,
+            captureInitialPageview: typeof autoCapturePageviews === 'object'
+                ? autoCapturePageviews?.captureInitialPageview ?? true
+                : true,
+            trackHashChanges: typeof autoCapturePageviews === 'object'
+                ? autoCapturePageviews?.trackHashChanges ?? false
+                : false,
+            debounceMs: typeof autoCapturePageviews === 'object'
+                ? autoCapturePageviews?.debounceMs ?? 100
+                : 100,
+        };
     const [state, setState] = useState({
         refCode: null,
         visitorId: null,
@@ -110,7 +131,22 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
         reset: asyncNoop,
         optOut: syncNoop,
         optIn: syncNoop,
+        flush: asyncNoop,
     });
+    // Debug logger. Closes over the `debug` prop so flipping it on/off at
+    // runtime (e.g. by changing a feature flag) takes effect on the next
+    // render without remounting. eslint-disable for the intentional
+    // console.log — that's the whole point of this helper.
+    const log = useCallback((msg, data) => {
+        if (!debug)
+            return;
+        // eslint-disable-next-line no-console
+        if (data !== undefined)
+            console.log('[Affiliateo] ' + msg, data);
+        // eslint-disable-next-line no-console
+        else
+            console.log('[Affiliateo] ' + msg);
+    }, [debug]);
     const apiBase = (apiUrl || DEFAULT_API_URL).replace(/\/$/, '');
     // campaignIdRef stays current so callbacks defined inside useEffect
     // always read the latest value, even after a prop change. Closures
@@ -164,9 +200,10 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
             // 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);
+            log('track', { event: name, metadata });
         }
         catch { /* swallow */ }
-    }, [apiBase]);
+    }, [apiBase, log]);
     // identify(userId). user_id only — the SDK does NOT accept, collect,
     // or transmit email or any other PII. Cross-device stitching uses the
     // merchant's own user_id; we never touch identifying personal data.
@@ -194,9 +231,10 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
                 user_id: uid,
             };
             queueRef.current?.enqueue(`${apiBase}/api/v1/web/identify`, payload);
+            log('identify', { user_id: uid });
         }
         catch { /* swallow */ }
-    }, [apiBase]);
+    }, [apiBase, log]);
     // 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
@@ -239,9 +277,24 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
                 screen_width: window.innerWidth,
             };
             queueRef.current?.enqueue(`${apiBase}/api/v1/web/event`, payload);
+            log('pageview (manual)', { path: pagePath });
         }
         catch { /* swallow */ }
-    }, [apiBase]);
+    }, [apiBase, log]);
+    // flush(): force immediate delivery of all queued events. The queue
+    // batches and auto-flushes every 5s; this is the escape hatch for the
+    // "I'm about to redirect, don't lose my events" case.
+    //
+    // Resolves when the underlying queue.flush() completes — success OR
+    // failure. Events that fail to deliver stay in the queue and get
+    // retried on the next normal flush cycle. Safe to await; never throws.
+    const flush = useCallback(async () => {
+        try {
+            log('flush requested');
+            await queueRef.current?.flush();
+        }
+        catch { /* swallow */ }
+    }, [log]);
     // 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).
@@ -319,6 +372,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
         // 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()) {
+            log('blocked: bot detected');
             setState({
                 refCode: null,
                 visitorId: null,
@@ -328,9 +382,87 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
                 reset: asyncNoop,
                 optOut: syncNoop,
                 optIn: syncNoop,
+                flush: asyncNoop,
             });
             return;
         }
+        // Dev-host guard. Default behavior is "block localhost / 127.0.0.1 /
+        // RFC1918 / .local / .test so merchant doesn't accidentally pollute
+        // their production funnel while running `npm run dev`." Merchants who
+        // legitimately want dev events flowing (e.g. end-to-end testing
+        // against staging that needs server-side events) opt in via
+        // <AffiliateoProvider allowLocalhost />.
+        //
+        // Tighter list than the server-side dev-host helper. see dev-host.ts
+        // for the rationale (must not block real merchants on .vercel.app).
+        if (!allowLocalhost && isDevHost(window.location.hostname)) {
+            log('blocked: localhost (set allowLocalhost={true} on AffiliateoProvider to enable)');
+            setState({
+                refCode: null,
+                visitorId: null,
+                track: asyncNoop,
+                identify: asyncNoop,
+                trackPageview: asyncNoop,
+                reset: asyncNoop,
+                optOut: syncNoop,
+                optIn: syncNoop,
+                flush: asyncNoop,
+            });
+            return;
+        }
+        // File-protocol guard. Pages served via file:// (someone double-clicking
+        // a built HTML file rather than running a server) almost certainly aren't
+        // real merchant traffic. Block by default; opt in via allowFileProtocol.
+        if (!allowFileProtocol && window.location.protocol === 'file:') {
+            log('blocked: file:// protocol (set allowFileProtocol={true} to enable)');
+            setState({
+                refCode: null,
+                visitorId: null,
+                track: asyncNoop,
+                identify: asyncNoop,
+                trackPageview: asyncNoop,
+                reset: asyncNoop,
+                optOut: syncNoop,
+                optIn: syncNoop,
+                flush: asyncNoop,
+            });
+            return;
+        }
+        // Iframe guard. Default behavior is "if we're inside an iframe, don't
+        // track" so scrapers, preview tools, and archive crawlers embedding
+        // the merchant's site don't count as pageviews. Cross-origin iframe
+        // access throws on the property read, which is ITSELF a signal we're
+        // inside a foreign frame, so the catch branch also bails out.
+        //
+        // Same-origin iframe (e.g. merchant embeds their own checkout) lets
+        // window.top return without throwing, and we compare against window.self
+        // to detect the embedded case. Merchants who legitimately render the
+        // SDK inside an iframe (embed widgets shipped to partners) opt in via
+        // <AffiliateoProvider allowIframe />.
+        if (!allowIframe) {
+            let insideIframe = false;
+            try {
+                insideIframe = window.self !== window.top;
+            }
+            catch {
+                insideIframe = true;
+            }
+            if (insideIframe) {
+                log('blocked: iframe (set allowIframe={true} on AffiliateoProvider to enable)');
+                setState({
+                    refCode: null,
+                    visitorId: null,
+                    track: asyncNoop,
+                    identify: asyncNoop,
+                    trackPageview: asyncNoop,
+                    reset: asyncNoop,
+                    optOut: syncNoop,
+                    optIn: syncNoop,
+                    flush: asyncNoop,
+                });
+                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
@@ -338,7 +470,10 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
         // 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();
+            queueRef.current = new EventQueue({
+                flushIntervalMs: flushInterval,
+                maxQueueSize: maxQueueSize,
+            });
         }
         const queue = queueRef.current;
         // Opt-out short-circuit. A visitor who previously called optOut()
@@ -359,7 +494,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
             setState({
                 refCode: null,
                 visitorId: optedOutVid,
-                track, identify, trackPageview, reset, optOut, optIn,
+                track, identify, trackPageview, reset, optOut, optIn, flush,
             });
             // Don't leave a queue running for an opted-out visitor — the timer
             // would just keep waking up to flush nothing.
@@ -419,8 +554,9 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
         setState({
             refCode: ref,
             visitorId: vid,
-            track, identify, trackPageview, reset, optOut, optIn,
+            track, identify, trackPageview, reset, optOut, optIn, flush,
         });
+        log('init', { campaign: campaignIdRef.current, visitor: vid, ref: ref || null });
         // Throttle: max 1 pageview per second
         let lastSendTime = 0;
         function sendPageview() {
@@ -443,6 +579,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
                 utm_campaign: params.get('utm_campaign') || '',
                 screen_width: window.innerWidth,
             });
+            log('pageview', { path: window.location.pathname });
         }
         // Send session_end when user leaves.
         //
@@ -510,23 +647,60 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
                 }
             }
         }
-        // Send pageview on mount
-        if (!sentRef.current) {
+        // Send pageview on mount. captureInitialPageview === false skips this
+        // for cookie-consent flows where the host wants to defer until the
+        // user accepts (then call trackPageview() manually).
+        if (!sentRef.current && autoCfg.captureInitialPageview && autoCfg.enabled) {
             sentRef.current = true;
             sendPageview();
         }
         // Detect user leaving
         document.addEventListener('visibilitychange', onVisibilityChange);
         window.addEventListener('pagehide', sendEnd);
-        // SPA support: detect URL changes
+        // SPA support: detect URL changes. We track BOTH pathname (modern
+        // pushState-based routers: React Router v6, Next.js App Router, Vue
+        // Router 4) AND hash (legacy hash routing: Vue Router with hash mode,
+        // React Router HashRouter, old Angular). Hash tracking is opt-in via
+        // autoCapturePageviews.trackHashChanges because modern SPAs never use
+        // it and firing on every #anchor click would inflate pageview counts.
+        //
+        // Debouncing collapses back-to-back navigation events into one. Some
+        // frameworks (Next.js, certain Vue routers) fire pushState then
+        // replaceState in the same tick to canonicalize the URL; without
+        // debouncing that's two pageviews per real navigation. Default 100ms
+        // matches Datafast; set debounceMs to 0 to disable.
         let lastPath = window.location.pathname;
+        let lastHash = window.location.hash;
+        let pendingPageviewTimer = null;
         function onUrlChange() {
-            if (window.location.pathname !== lastPath) {
-                lastPath = window.location.pathname;
+            const pathChanged = window.location.pathname !== lastPath;
+            const hashChanged = autoCfg.trackHashChanges && window.location.hash !== lastHash;
+            if (!pathChanged && !hashChanged)
+                return;
+            lastPath = window.location.pathname;
+            lastHash = window.location.hash;
+            if (!autoCfg.enabled)
+                return;
+            // Debounce: if a pending pageview is already scheduled, the later
+            // urlchange wins (the URL the browser ends up on after both calls
+            // is what we want to report).
+            if (pendingPageviewTimer !== null) {
+                clearTimeout(pendingPageviewTimer);
+            }
+            if (autoCfg.debounceMs > 0) {
+                pendingPageviewTimer = setTimeout(() => {
+                    pendingPageviewTimer = null;
+                    sendPageview();
+                }, autoCfg.debounceMs);
+            }
+            else {
                 sendPageview();
             }
         }
         window.addEventListener('popstate', onUrlChange);
+        if (autoCfg.trackHashChanges) {
+            window.addEventListener('hashchange', onUrlChange);
+        }
         const origPushState = history.pushState;
         const origReplaceState = history.replaceState;
         history.pushState = function (...args) {
@@ -614,6 +788,12 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
             document.removeEventListener('visibilitychange', onVisibilityChange);
             window.removeEventListener('pagehide', sendEnd);
             window.removeEventListener('popstate', onUrlChange);
+            if (autoCfg.trackHashChanges) {
+                window.removeEventListener('hashchange', onUrlChange);
+            }
+            if (pendingPageviewTimer !== null) {
+                clearTimeout(pendingPageviewTimer);
+            }
             history.pushState = origPushState;
             history.replaceState = origReplaceState;
             if (allowedHosts.length > 0) {
@@ -627,6 +807,6 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, child
             queueRef.current = null;
             providerMountCount = Math.max(0, providerMountCount - 1);
         };
-    }, [apiBase, allowedHostnames, track, identify, trackPageview, reset, optOut, optIn]);
+    }, [apiBase, allowedHostnames, allowLocalhost, allowIframe, log, track, identify, trackPageview, reset, optOut, optIn, flush]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/queue.d.ts

@@ -41,6 +41,12 @@
  *   - SIZE_FLUSH_THRESHOLD = 10   triggers a flush when queue grows
  *                                 past this even before the timer fires
  */
+export interface EventQueueOptions {
+    /** Override the auto-flush cadence. Defaults to 5000ms. */
+    flushIntervalMs?: number;
+    /** Override the hard cap on queued events. Defaults to 100. */
+    maxQueueSize?: number;
+}
 export interface QueuedEvent {
     /** Stable id used to identify the event across retries. UUID v4
      *  generated client-side; collisions are astronomically unlikely so
@@ -63,7 +69,9 @@ export declare class EventQueue {
     private flushTimer;
     private isFlushing;
     private shuttingDown;
-    constructor();
+    private readonly flushIntervalMs;
+    private readonly maxQueueSize;
+    constructor(opts?: EventQueueOptions);
     /** 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. */

package/dist/queue.js

@@ -43,8 +43,8 @@
  */
 const STORAGE_KEY = 'affiliateo_event_queue';
 const MAX_RETRIES = 3;
-const MAX_QUEUE_SIZE = 100;
-const FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_QUEUE_SIZE = 100;
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
 const SIZE_FLUSH_THRESHOLD = 10;
 function lsGet(key) {
     try {
@@ -76,11 +76,16 @@ function uuid() {
     });
 }
 export class EventQueue {
-    constructor() {
+    constructor(opts = {}) {
         this.queue = [];
         this.flushTimer = null;
         this.isFlushing = false;
         this.shuttingDown = false;
+        // Bounds: refuse pathological values silently. Minimum 1s flush so we
+        // don't hammer the network; minimum 10 events so the queue is useful;
+        // maximum 1000 events so a misconfigured app can't fill localStorage.
+        this.flushIntervalMs = Math.max(1000, opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
+        this.maxQueueSize = Math.max(10, Math.min(1000, opts.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE));
         // 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
@@ -125,8 +130,8 @@ export class EventQueue {
         // 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);
+        if (this.queue.length > this.maxQueueSize) {
+            this.queue.splice(0, this.queue.length - this.maxQueueSize);
         }
         this.persist();
         // Burst protection: when many events fire in quick succession
@@ -261,6 +266,6 @@ export class EventQueue {
             return;
         this.flushTimer = setInterval(() => {
             void this.flush();
-        }, FLUSH_INTERVAL_MS);
+        }, this.flushIntervalMs);
     }
 }

package/dist/types.d.ts

@@ -26,6 +26,70 @@ export interface AffiliateoConfig {
      *      allowedHostnames={['app.merchant.com', 'docs.merchant.com']}
      *    > */
     allowedHostnames?: string[];
+    /** Allow tracking when the page is served from a developer machine
+     *  (localhost, 127.0.0.1, RFC1918 IPs, .local / .test TLDs). Defaults
+     *  to false so a developer running `npm run dev` doesn't pollute the
+     *  merchant's production funnel with test pageviews.
+     *
+     *  Set to true ONLY when you actually want dev traffic in your
+     *  dashboard (e.g. for an end-to-end test that needs the events to
+     *  land server-side).
+     *
+     *  Example:
+     *    <AffiliateoProvider campaignId="..." allowLocalhost> */
+    allowLocalhost?: boolean;
+    /** Allow tracking when the page is rendered inside an iframe. Defaults
+     *  to false so scrapers, preview tools, and other sites embedding yours
+     *  don't count as pageviews.
+     *
+     *  Set to true if you legitimately render your site inside iframes
+     *  (e.g. an embed widget you ship to partners). */
+    allowIframe?: boolean;
+    /** Print decision logs to the browser console. Defaults to false. When
+     *  true, the SDK logs every action it takes (init, pageview fired,
+     *  goal tracked, blocked by bot detection, blocked by localhost, queue
+     *  flush attempted, etc.). Only the merchant or anyone manually opening
+     *  DevTools sees these — normal visitors never look at the console.
+     *
+     *  Turn on temporarily when investigating "why aren't my events
+     *  showing up?". Leave off in production.
+     *
+     *  Example:
+     *    <AffiliateoProvider campaignId="..." debug> */
+    debug?: boolean;
+    /** Allow tracking from pages served via the `file://` protocol (someone
+     *  double-clicking a built HTML file instead of running a server).
+     *  Defaults to false. Almost never useful. set true only if you're
+     *  intentionally testing an offline-first build. */
+    allowFileProtocol?: boolean;
+    /** How often the event queue tries to flush, in milliseconds. Defaults
+     *  to 5000 (every 5 seconds). Lower for chattier delivery (more
+     *  requests, fresher data); raise for a quieter queue (fewer requests,
+     *  bigger batches). */
+    flushInterval?: number;
+    /** Maximum number of events the queue holds before dropping the oldest
+     *  FIFO. Defaults to 100. Acts as a backstop against a long network
+     *  outage filling localStorage. */
+    maxQueueSize?: number;
+    /** Pageview auto-capture behavior. Pass `false` to disable entirely
+     *  (you'll call `trackPageview()` yourself). Pass an object to fine-tune.
+     *  Defaults to `true` (auto-capture everything). */
+    autoCapturePageviews?: boolean | {
+        /** Fire the initial pageview on mount. Defaults to true. Set false
+         *  for cookie-consent flows where you want to defer until the user
+         *  accepts. */
+        captureInitialPageview?: boolean;
+        /** Fire pageviews on URL hash changes (e.g. `/#/about` → `/#/pricing`
+         *  in older Vue / Angular / React Router HashRouter setups). Defaults
+         *  to false. modern SPAs use pushState (already tracked). Turn on
+         *  only for legacy hash routing. */
+        trackHashChanges?: boolean;
+        /** Debounce window for back-to-back pushState / replaceState calls,
+         *  in milliseconds. Some frameworks (Next.js, some Vue routers) fire
+         *  both within one tick, producing two pageviews per navigation
+         *  without debouncing. Defaults to 100ms. Set 0 to disable. */
+        debounceMs?: number;
+    };
 }
 export interface AffiliateoContextValue {
     /** The affiliate ref code from the URL (if present) */
@@ -108,4 +172,25 @@ export interface AffiliateoContextValue {
      *  the cleanest way to bring the SDK back to its normal "auto-fire on
      *  mount" state. */
     optIn: () => void;
+    /** Force immediate delivery of all queued events. The SDK batches events
+     *  (track / identify / pageview) and flushes them every 5 seconds; this
+     *  method flushes RIGHT NOW.
+     *
+     *  Use case: call before a redirect (e.g. window.location.href = stripeUrl)
+     *  so events queued right before the navigation don't get lost. The
+     *  default behavior would wait for the 5-second timer, but the page
+     *  is gone by then.
+     *
+     *  Example:
+     *    const { track, flush } = useAffiliateRef()
+     *    async function startCheckout() {
+     *      track('initiate_checkout')
+     *      await flush()
+     *      window.location.href = stripeCheckoutUrl
+     *    }
+     *
+     *  Returns a Promise that resolves when the flush attempt completes
+     *  (success OR failure — failed events stay in the queue for the next
+     *  flush). Safe to await without timeout concerns. */
+    flush: () => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affiliateo/web",
-  "version": "3.1.0",
+  "version": "4.1.0",
   "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
   "main": "dist/index.js",
   "module": "dist/index.js",