@affiliateo/web 4.0.0 → 4.1.0

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

@@ -102,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, 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,
@@ -391,6 +410,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 +470,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()
@@ -607,23 +647,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 +788,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.1.0",
   "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
   "main": "dist/index.js",
   "module": "dist/index.js",