@affiliateo/web 3.1.0 → 4.0.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, debug, 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,7 @@ 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, debug, children, }) {
     const [state, setState] = useState({
         refCode: null,
         visitorId: null,
@@ -110,7 +112,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 +181,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 +212,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 +258,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 +353,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 +363,69 @@ 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;
+        }
+        // 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
@@ -359,7 +454,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 +514,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 +539,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.
         //
@@ -627,6 +724,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/types.d.ts

@@ -26,6 +26,37 @@ 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;
 }
 export interface AffiliateoContextValue {
     /** The affiliate ref code from the URL (if present) */
@@ -108,4 +139,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.0.0",
   "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
   "main": "dist/index.js",
   "module": "dist/index.js",