@affiliateo/web 4.0.0 → 4.2.0

package/README.md

@@ -1,238 +1,238 @@
-# @affiliateo/web
-
-Affiliateo web SDK. track affiliate visits and pass attribution metadata to your Stripe checkout.
-
-## Install
-
-```bash
-npm install @affiliateo/web
-```
-
-## Setup
-
-1. Connect your Stripe account on the Affiliateo dashboard
-2. Wrap your app in `<AffiliateoProvider>` with your campaign ID
-3. At checkout time, call `getAttribution()` and pass the result to Stripe metadata
-
-### Step 1. wrap your app
-
-```tsx
-// app/layout.tsx (Next.js App Router) or _app.tsx (Pages Router)
-import { AffiliateoProvider } from '@affiliateo/web';
-
-export default function RootLayout({ children }) {
-  return (
-    <AffiliateoProvider campaignId="YOUR_CAMPAIGN_ID">
-      {children}
-    </AffiliateoProvider>
-  );
-}
-```
-
-The provider:
-- Reads `?ref=` from the URL when a visitor arrives
-- Stores attribution in `localStorage` so it survives navigation
-- Sends pageview events to Affiliateo for click tracking
-
-### Step 2. in your checkout button (client-side)
-
-```tsx
-'use client'
-import { getAttribution } from '@affiliateo/web';
-
-async function handleCheckout() {
-  const attribution = getAttribution();
-
-  const res = await fetch('/api/checkout', {
-    method: 'POST',
-    body: JSON.stringify({ attribution }),
-  });
-
-  const { url } = await res.json();
-  window.location.href = url;
-}
-```
-
-`getAttribution()` reads `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from `localStorage` and returns them as an object, ready to pass to Stripe.
-
-### Step 3. in your checkout API route (server-side)
-
-```ts
-// app/api/checkout/route.ts
-export async function POST(req) {
-  const { attribution } = await req.json();
-
-  const session = await stripe.checkout.sessions.create({
-    line_items: [{ price: 'price_xxx', quantity: 1 }],
-    mode: 'payment',
-    success_url: 'https://yoursite.com/success',
-    cancel_url: 'https://yoursite.com/cancel',
-    metadata: attribution,
-  });
-
-  return Response.json({ url: session.url });
-}
-```
-
-That's it. Affiliateo's webhook will automatically read the metadata and credit the right affiliate when the payment succeeds.
-
-## How it works
-
-1. Visitor clicks affiliate link → `yoursite.com?ref=pinkproton`
-2. `<AffiliateoProvider>` reads `?ref=pinkproton` from the URL and saves it in `localStorage`
-3. As the visitor browses, attribution stays in their browser
-4. At checkout, `getAttribution()` reads localStorage and returns the attribution object
-5. Your server passes it as Stripe metadata when creating the checkout session
-6. When Stripe fires the `checkout.session.completed` webhook, Affiliateo reads the metadata and credits the affiliate
-
-## Why `localStorage` and not cookies?
-
-- **Not blocked by Safari ITP or most privacy tools**
-- **No CSRF concerns**
-
-## GDPR / ePrivacy. merchant responsibility
-
-The SDK writes persistent identifiers (`affiliateo_visitor_id`, `affiliateo_ref`, `affiliateo_campaign_id`) to the visitor's `localStorage` and sends pageview events that include the visitor's IP, user agent, and approximate geolocation to Affiliateo's servers. Under EU ePrivacy (Article 5(3)) and GDPR, persistent identifiers stored on a visitor's device require prior consent the same way cookies do.
-
-If you serve visitors in the EU/EEA, UK, or any jurisdiction with equivalent rules, **you are responsible for obtaining consent before this script loads**, the same way you would for Google Analytics, Meta Pixel, or any other analytics tool. Typical approaches:
-
-- Gate the `<AffiliateoProvider>` (or the `<script src="…/t.js">` tag) behind your cookie banner's "accept" callback so it only loads after consent.
-- Document Affiliateo in your privacy policy as a processor (see our [Data Processing Agreement](https://affiliateo.com/dpa)) and list the categories of data collected.
-
-Affiliateo acts as your data processor for visitor analytics. You are the controller and decide the lawful basis for processing your visitors' data.
-
-## Alternative: vanilla HTML (no React)
-
-If you're not using React, use the tracking script directly instead of the provider:
-
-```html
-<script defer
-  data-campaign="YOUR_CAMPAIGN_ID"
-  src="https://affiliateo.com/t.js"
-></script>
-```
-
-Then in your checkout flow (vanilla JS):
-
-```js
-const attribution = {
-  affiliateo_ref: localStorage.getItem('affiliateo_ref'),
-  affiliateo_visitor_id: localStorage.getItem('affiliateo_visitor_id'),
-  affiliateo_campaign_id: localStorage.getItem('affiliateo_campaign_id'),
-};
-
-// Send to your server with the rest of your checkout payload
-fetch('/api/checkout', {
-  method: 'POST',
-  body: JSON.stringify({ attribution }),
-});
-```
-
-## Track conversion goals
-
-Pageviews auto-track. For specific moments that matter to your funnel
-(`signup_completed`, `trial_started`, `initiate_checkout`, etc.), use
-`track()` or HTML data attributes.
-
-### From React
-
-```tsx
-'use client'
-import { useEffect } from 'react'
-import { useAffiliateRef } from '@affiliateo/web'
-
-export default function SignupSuccess() {
-  const { track } = useAffiliateRef()
-  useEffect(() => {
-    track('signup_completed', { plan: 'free' })
-  }, [])
-  return <div>Welcome!</div>
-}
-```
-
-### HTML data attributes (zero JS, works everywhere)
-
-```html
-<button data-affiliateo-goal="initiate_checkout"
-        data-affiliateo-goal-price="49"
-        data-affiliateo-goal-plan="pro">
-  Subscribe
-</button>
-```
-
-The SDK auto-fires the goal on click. Optional `data-affiliateo-goal-*`
-attributes become metadata (kebab-case → snake_case, up to 10 params).
-
-### Scroll-depth tracking
-
-```html
-<section data-affiliateo-scroll="pricing_viewed">
-  ...your pricing content...
-</section>
-```
-
-Fires the first time any pixel of the section overlaps the viewport.
-Maximum permissiveness — if the user scrolled enough to see even a sliver,
-it counts. Earlier versions required 50% visibility, which was unreachable
-for tall sections (a pricing page with comparison tables silently dropped
-out of every funnel). Great for landing pages where you want to know
-which sections convert.
-
-### Goal naming rules
-
-Lowercase letters, digits, underscores, hyphens, colons. Max 64 chars.
-Metadata bounded to 4KB JSON.
-
-## Identify signed-in users (cross-device stitching)
-
-Without `identify()`, the same person browsing on phone and buying on
-laptop counts as two visitors. Call it once after sign-in:
-
-```tsx
-'use client'
-import { useEffect } from 'react'
-import { useAffiliateRef } from '@affiliateo/web'
-import { useUser } from './your-auth'
-
-export default function AuthBoundary({ children }) {
-  const { identify } = useAffiliateRef()
-  const user = useUser()
-  useEffect(() => {
-    if (user) identify(user.id)
-  }, [user])
-  return <>{children}</>
-}
-```
-
-Idempotent. safe to fire on every page load while a user is signed in.
-**user_id only.** The SDK does not accept, collect, or transmit email
-or any other PII.
-
-## API
-
-### `<AffiliateoProvider campaignId="..." apiUrl?="...">`
-
-React provider. Wrap your app once. Reads `?ref=` from URL, persists to localStorage, sends pageview events, sets up data-attribute + scroll listeners.
-
-Props:
-- `campaignId` (required): your Affiliateo campaign ID
-- `apiUrl` (optional): defaults to `https://affiliateo.com`
-
-### `useAffiliateRef()`
-
-React hook that returns `{ refCode, visitorId, track, identify }`.
-
-- `track(eventName, metadata?)`. fire a custom goal
-- `identify(userId)`. link this visitor to a merchant user_id (no PII)
-
-### `getAttribution()`
-
-Client-side function. Returns an object with `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from localStorage. Pass directly as Stripe `metadata`.
-
-## Framework support
-
-Works with any JavaScript framework or vanilla JS:
-- **Next.js** (App Router & Pages Router)
-- **Remix** / **React Router**
-- **Vite + React**
-- **Vanilla JS/HTML** (use the `<script>` tag instead)
+# @affiliateo/web
+
+Affiliateo web SDK. track affiliate visits and pass attribution metadata to your Stripe checkout.
+
+## Install
+
+```bash
+npm install @affiliateo/web
+```
+
+## Setup
+
+1. Connect your Stripe account on the Affiliateo dashboard
+2. Wrap your app in `<AffiliateoProvider>` with your campaign ID
+3. At checkout time, call `getAttribution()` and pass the result to Stripe metadata
+
+### Step 1. wrap your app
+
+```tsx
+// app/layout.tsx (Next.js App Router) or _app.tsx (Pages Router)
+import { AffiliateoProvider } from '@affiliateo/web';
+
+export default function RootLayout({ children }) {
+  return (
+    <AffiliateoProvider campaignId="YOUR_CAMPAIGN_ID">
+      {children}
+    </AffiliateoProvider>
+  );
+}
+```
+
+The provider:
+- Reads `?ref=` from the URL when a visitor arrives
+- Stores attribution in `localStorage` so it survives navigation
+- Sends pageview events to Affiliateo for click tracking
+
+### Step 2. in your checkout button (client-side)
+
+```tsx
+'use client'
+import { getAttribution } from '@affiliateo/web';
+
+async function handleCheckout() {
+  const attribution = getAttribution();
+
+  const res = await fetch('/api/checkout', {
+    method: 'POST',
+    body: JSON.stringify({ attribution }),
+  });
+
+  const { url } = await res.json();
+  window.location.href = url;
+}
+```
+
+`getAttribution()` reads `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from `localStorage` and returns them as an object, ready to pass to Stripe.
+
+### Step 3. in your checkout API route (server-side)
+
+```ts
+// app/api/checkout/route.ts
+export async function POST(req) {
+  const { attribution } = await req.json();
+
+  const session = await stripe.checkout.sessions.create({
+    line_items: [{ price: 'price_xxx', quantity: 1 }],
+    mode: 'payment',
+    success_url: 'https://yoursite.com/success',
+    cancel_url: 'https://yoursite.com/cancel',
+    metadata: attribution,
+  });
+
+  return Response.json({ url: session.url });
+}
+```
+
+That's it. Affiliateo's webhook will automatically read the metadata and credit the right affiliate when the payment succeeds.
+
+## How it works
+
+1. Visitor clicks affiliate link → `yoursite.com?ref=pinkproton`
+2. `<AffiliateoProvider>` reads `?ref=pinkproton` from the URL and saves it in `localStorage`
+3. As the visitor browses, attribution stays in their browser
+4. At checkout, `getAttribution()` reads localStorage and returns the attribution object
+5. Your server passes it as Stripe metadata when creating the checkout session
+6. When Stripe fires the `checkout.session.completed` webhook, Affiliateo reads the metadata and credits the affiliate
+
+## Why `localStorage` and not cookies?
+
+- **Not blocked by Safari ITP or most privacy tools**
+- **No CSRF concerns**
+
+## GDPR / ePrivacy. merchant responsibility
+
+The SDK writes persistent identifiers (`affiliateo_visitor_id`, `affiliateo_ref`, `affiliateo_campaign_id`) to the visitor's `localStorage` and sends pageview events that include the visitor's IP, user agent, and approximate geolocation to Affiliateo's servers. Under EU ePrivacy (Article 5(3)) and GDPR, persistent identifiers stored on a visitor's device require prior consent the same way cookies do.
+
+If you serve visitors in the EU/EEA, UK, or any jurisdiction with equivalent rules, **you are responsible for obtaining consent before this script loads**, the same way you would for Google Analytics, Meta Pixel, or any other analytics tool. Typical approaches:
+
+- Gate the `<AffiliateoProvider>` (or the `<script src="…/t.js">` tag) behind your cookie banner's "accept" callback so it only loads after consent.
+- Document Affiliateo in your privacy policy as a processor (see our [Data Processing Agreement](https://affiliateo.com/dpa)) and list the categories of data collected.
+
+Affiliateo acts as your data processor for visitor analytics. You are the controller and decide the lawful basis for processing your visitors' data.
+
+## Alternative: vanilla HTML (no React)
+
+If you're not using React, use the tracking script directly instead of the provider:
+
+```html
+<script defer
+  data-campaign="YOUR_CAMPAIGN_ID"
+  src="https://affiliateo.com/t.js"
+></script>
+```
+
+Then in your checkout flow (vanilla JS):
+
+```js
+const attribution = {
+  affiliateo_ref: localStorage.getItem('affiliateo_ref'),
+  affiliateo_visitor_id: localStorage.getItem('affiliateo_visitor_id'),
+  affiliateo_campaign_id: localStorage.getItem('affiliateo_campaign_id'),
+};
+
+// Send to your server with the rest of your checkout payload
+fetch('/api/checkout', {
+  method: 'POST',
+  body: JSON.stringify({ attribution }),
+});
+```
+
+## Track conversion goals
+
+Pageviews auto-track. For specific moments that matter to your funnel
+(`signup_completed`, `trial_started`, `initiate_checkout`, etc.), use
+`track()` or HTML data attributes.
+
+### From React
+
+```tsx
+'use client'
+import { useEffect } from 'react'
+import { useAffiliateRef } from '@affiliateo/web'
+
+export default function SignupSuccess() {
+  const { track } = useAffiliateRef()
+  useEffect(() => {
+    track('signup_completed', { plan: 'free' })
+  }, [])
+  return <div>Welcome!</div>
+}
+```
+
+### HTML data attributes (zero JS, works everywhere)
+
+```html
+<button data-affiliateo-goal="initiate_checkout"
+        data-affiliateo-goal-price="49"
+        data-affiliateo-goal-plan="pro">
+  Subscribe
+</button>
+```
+
+The SDK auto-fires the goal on click. Optional `data-affiliateo-goal-*`
+attributes become metadata (kebab-case → snake_case, up to 10 params).
+
+### Scroll-depth tracking
+
+```html
+<section data-affiliateo-scroll="pricing_viewed">
+  ...your pricing content...
+</section>
+```
+
+Fires the first time any pixel of the section overlaps the viewport.
+Maximum permissiveness — if the user scrolled enough to see even a sliver,
+it counts. Earlier versions required 50% visibility, which was unreachable
+for tall sections (a pricing page with comparison tables silently dropped
+out of every funnel). Great for landing pages where you want to know
+which sections convert.
+
+### Goal naming rules
+
+Lowercase letters, digits, underscores, hyphens, colons. Max 64 chars.
+Metadata bounded to 4KB JSON.
+
+## Identify signed-in users (cross-device stitching)
+
+Without `identify()`, the same person browsing on phone and buying on
+laptop counts as two visitors. Call it once after sign-in:
+
+```tsx
+'use client'
+import { useEffect } from 'react'
+import { useAffiliateRef } from '@affiliateo/web'
+import { useUser } from './your-auth'
+
+export default function AuthBoundary({ children }) {
+  const { identify } = useAffiliateRef()
+  const user = useUser()
+  useEffect(() => {
+    if (user) identify(user.id)
+  }, [user])
+  return <>{children}</>
+}
+```
+
+Idempotent. safe to fire on every page load while a user is signed in.
+**user_id only.** The SDK does not accept, collect, or transmit email
+or any other PII.
+
+## API
+
+### `<AffiliateoProvider campaignId="..." apiUrl?="...">`
+
+React provider. Wrap your app once. Reads `?ref=` from URL, persists to localStorage, sends pageview events, sets up data-attribute + scroll listeners.
+
+Props:
+- `campaignId` (required): your Affiliateo campaign ID
+- `apiUrl` (optional): defaults to `https://affiliateo.com`
+
+### `useAffiliateRef()`
+
+React hook that returns `{ refCode, visitorId, track, identify }`.
+
+- `track(eventName, metadata?)`. fire a custom goal
+- `identify(userId)`. link this visitor to a merchant user_id (no PII)
+
+### `getAttribution()`
+
+Client-side function. Returns an object with `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from localStorage. Pass directly as Stripe `metadata`.
+
+## Framework support
+
+Works with any JavaScript framework or vanilla JS:
+- **Next.js** (App Router & Pages Router)
+- **Remix** / **React Router**
+- **Vite + React**
+- **Vanilla JS/HTML** (use the `<script>` tag instead)

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, allowLocalhost, allowIframe, debug, 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

@@ -13,6 +13,23 @@ const LS_CAMPAIGN_ID = 'affiliateo_campaign_id';
 // 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';
+// Client-owned session id (Datafast-style). The BROWSER owns the session,
+// not the server. One id is reused for every event within a sliding
+// 10-minute activity window, then a fresh one is minted. Because the id is
+// generated here and sent on each event, a burst of pageviews (a redirect
+// bounce, multiple tabs) all carry the SAME id, so the dashboard collapses
+// them into a single visit. Server-side minting was racy: simultaneous
+// events each invented a different id. 10 min matches the server session
+// window and the live-presence window so everything ages out on one clock.
+const LS_SESSION = 'affiliateo_session';
+const SESSION_WINDOW_MS = 10 * 60 * 1000;
+// Same-URL pageview throttle, persisted in sessionStorage so it survives
+// hard navigations / redirect bounces (the old in-memory throttle reset on
+// every fresh page context, which let a 3-hop bounce fire 3 pageviews).
+// Different URLs are never throttled against each other. Mirrors Datafast's
+// 60s same-URL suppression.
+const SS_PV_THROTTLE = 'affiliateo_pv_throttle';
+const PV_THROTTLE_MS = 60 * 1000;
 // localStorage helpers
 function lsGet(key) {
     try {
@@ -34,6 +51,24 @@ function lsRemove(key) {
     }
     catch { }
 }
+// sessionStorage helpers. Used by the pageview throttle so its state lives
+// for the life of the tab (and survives hard navigations within it) but
+// resets when the tab closes, which is exactly the scope we want for
+// "don't re-fire the same URL within a minute."
+function ssGet(key) {
+    try {
+        return sessionStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function ssSet(key, value) {
+    try {
+        sessionStorage.setItem(key, value);
+    }
+    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).
@@ -50,6 +85,34 @@ function uuid() {
         return v.toString(16);
     });
 }
+// Get-or-create the current session id with a sliding 10-minute window.
+// Stored in localStorage so every tab and every page load in the same
+// browser shares one session. Each call slides the window forward (the same
+// way Datafast refreshes its session cookie on each event), so an actively
+// browsing visitor keeps one id and a returning visitor past the window
+// gets a fresh one. Returns a UUID string the server stamps onto the event.
+function getSessionId() {
+    const now = Date.now();
+    try {
+        const raw = lsGet(LS_SESSION);
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            if (parsed &&
+                typeof parsed.id === 'string' &&
+                typeof parsed.lastActive === 'number' &&
+                now - parsed.lastActive < SESSION_WINDOW_MS) {
+                lsSet(LS_SESSION, JSON.stringify({ id: parsed.id, lastActive: now }));
+                return parsed.id;
+            }
+        }
+    }
+    catch {
+        // Corrupt entry or storage blocked. Fall through and mint a fresh one.
+    }
+    const id = uuid();
+    lsSet(LS_SESSION, JSON.stringify({ id, lastActive: now }));
+    return id;
+}
 const asyncNoop = async () => { };
 const syncNoop = () => { };
 const AffiliateoContext = createContext({
@@ -102,7 +165,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, allowLocalhost, allowIframe, debug, 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,
@@ -172,6 +254,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 type: 'custom',
                 campaign_id: cid,
                 visitor_id: vid,
+                session_id: getSessionId(),
                 event_name: name,
             };
             if (metadata && typeof metadata === 'object')
@@ -247,6 +330,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 type: 'pageview',
                 campaign_id: cid,
                 visitor_id: vid,
+                session_id: getSessionId(),
                 url,
                 path: pagePath,
                 hostname: window.location.hostname,
@@ -301,6 +385,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             const newVid = uuid();
             lsSet(LS_VISITOR_ID, newVid);
             lsRemove(LS_REF);
+            lsRemove(LS_SESSION);
             visitorIdRef.current = newVid;
             setState((prev) => ({ ...prev, visitorId: newVid, refCode: null }));
         }
@@ -391,6 +476,24 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             });
             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
@@ -433,7 +536,10 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
         // 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()
@@ -517,19 +623,42 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             track, identify, trackPageview, reset, optOut, optIn, flush,
         });
         log('init', { campaign: campaignIdRef.current, visitor: vid, ref: ref || null });
-        // Throttle: max 1 pageview per second
+        // lastSendTime drives the visibility-refire heuristic below (refire a
+        // pageview when a tab returns after the session window). Duplicate
+        // suppression itself is the persisted same-URL throttle inside
+        // sendPageview, which survives hard navigations.
         let lastSendTime = 0;
         function sendPageview() {
             const now = Date.now();
-            if (now - lastSendTime < 1000)
-                return;
+            const href = window.location.href;
+            // Same-URL throttle, persisted in sessionStorage so a redirect bounce
+            // or hard navigation that lands back on the same URL within the window
+            // does not re-fire. Different URLs are never throttled against each
+            // other, so a genuine multi-page visit still records every page.
+            const prevRaw = ssGet(SS_PV_THROTTLE);
+            if (prevRaw) {
+                try {
+                    const prev = JSON.parse(prevRaw);
+                    if (prev &&
+                        prev.url === href &&
+                        typeof prev.time === 'number' &&
+                        now - prev.time < PV_THROTTLE_MS) {
+                        return;
+                    }
+                }
+                catch {
+                    // Corrupt entry. Fall through and fire.
+                }
+            }
+            ssSet(SS_PV_THROTTLE, JSON.stringify({ url: href, time: now }));
             lastSendTime = now;
             ended = false;
             queue.enqueue(endpoint, {
                 type: 'pageview',
                 campaign_id: campaignIdRef.current,
                 visitor_id: vid,
-                url: window.location.href,
+                session_id: getSessionId(),
+                url: href,
                 path: window.location.pathname,
                 hostname: window.location.hostname,
                 referrer: document.referrer || '',
@@ -607,23 +736,60 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 }
             }
         }
-        // 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) {
@@ -711,6 +877,12 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             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) {

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

@@ -57,6 +57,39 @@ export interface AffiliateoConfig {
      *  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) */

package/package.json

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