@affiliateo/web 3.0.0 → 3.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, children, }: AffiliateoConfig & {
+export declare function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, children, }: AffiliateoConfig & {
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/provider.js

@@ -100,7 +100,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, children, }) {
+export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, children, }) {
     const [state, setState] = useState({
         refCode: null,
         visitorId: null,
@@ -367,17 +367,50 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             queueRef.current = null;
             return;
         }
-        // Get or create visitor ID
-        let vid = lsGet(LS_VISITOR_ID);
+        // ── Cross-domain handoff: read incoming URL params ───────────────────
+        // When a visitor arrives from another domain in the merchant's family
+        // (configured via the `allowedHostnames` prop on the OTHER domain's
+        // <AffiliateoProvider>), the inbound link carries visitor_id + ref
+        // code as URL params. We pull those in BEFORE checking localStorage
+        // so the cross-domain identity wins over whatever this domain's
+        // sandboxed storage had. Without it, the funnel sees the same person
+        // as two unrelated visitors after every cross-domain hop, and any
+        // affiliate ref captured on the previous domain is silently lost.
+        //
+        // After consuming, we strip the params via history.replaceState so
+        // the visitor never sees `?_affiliateo_vid=...` in their URL bar.
+        // UUID + ref are validated before persistence so a malicious
+        // /?_affiliateo_vid=<garbage> URL can't poison localStorage.
+        const params = new URLSearchParams(window.location.search);
+        const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        let incomingVid = params.get('_affiliateo_vid') || '';
+        let incomingRef = params.get('_affiliateo_ref') || '';
+        if (incomingVid && !UUID_RE.test(incomingVid))
+            incomingVid = '';
+        if (incomingRef && (incomingRef.length > 64 || !/^[\w.-]+$/.test(incomingRef))) {
+            incomingRef = '';
+        }
+        if (incomingVid || incomingRef) {
+            try {
+                const cleanUrl = new URL(window.location.href);
+                cleanUrl.searchParams.delete('_affiliateo_vid');
+                cleanUrl.searchParams.delete('_affiliateo_ref');
+                history.replaceState(history.state, '', cleanUrl.toString());
+            }
+            catch { /* swallow */ }
+        }
+        // Get or create visitor ID. Cross-domain inbound wins over localStorage
+        // so the same person across two domains stays one visitor.
+        let vid = incomingVid || lsGet(LS_VISITOR_ID);
         if (!vid) {
             vid = uuid();
         }
         lsSet(LS_VISITOR_ID, vid);
         lsSet(LS_CAMPAIGN_ID, campaignIdRef.current);
         visitorIdRef.current = vid;
-        // Read ref from URL params or localStorage
-        const params = new URLSearchParams(window.location.search);
-        const ref = params.get('ref') || params.get('via') || params.get('source')
+        // Read ref. Cross-domain inbound wins, then fresh affiliate link
+        // params (?ref / ?via / ?source), then stored value.
+        const ref = incomingRef || params.get('ref') || params.get('via') || params.get('source')
             || lsGet(LS_REF) || null;
         if (ref) {
             lsSet(LS_REF, ref);
@@ -515,12 +548,78 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         // bug we hit (threshold:0 firing on hero sections, SPA mutation
         // observer races, client-side step matching from HTML). Removing it
         // also drops ~80 lines of code and one extra DOM observer per page.
+        // ── Cross-domain handoff: decorate outbound links ──────────────────
+        // When a visitor clicks an <a> link to one of the merchant's other
+        // domains (passed in via the `allowedHostnames` prop), append
+        // visitor_id + ref code as URL search params before the browser
+        // navigates. The receiving domain's <AffiliateoProvider> reads those
+        // params on landing (the inbound block above) and uses them as
+        // identity for that domain.
+        //
+        // Hostnames are normalized once and matched exact (no wildcards) so
+        // merchants who want subdomains list each one explicitly. Same-host
+        // links, non-http(s) protocols (mailto:, tel:, javascript:), and
+        // anchor links (#section) are skipped. Capture phase so we run
+        // before merchant click handlers; href mutation is advisory and the
+        // browser reads link.href when it eventually navigates.
+        const allowedHosts = Array.isArray(allowedHostnames)
+            ? allowedHostnames
+                .map((h) => (typeof h === 'string' ? h.trim().toLowerCase() : ''))
+                .filter((h) => !!h)
+            : [];
+        function decorateOutboundLink(link) {
+            if (!link || !link.href || !link.hostname)
+                return;
+            if (link.protocol !== 'http:' && link.protocol !== 'https:')
+                return;
+            const host = link.hostname.toLowerCase();
+            if (host === window.location.hostname.toLowerCase())
+                return;
+            if (allowedHosts.indexOf(host) === -1)
+                return;
+            try {
+                const u = new URL(link.href);
+                // Idempotent: skip if our params are already present.
+                if (u.searchParams.has('_affiliateo_vid'))
+                    return;
+                const currentVid = visitorIdRef.current;
+                const currentRef = lsGet(LS_REF) || '';
+                if (currentVid)
+                    u.searchParams.set('_affiliateo_vid', currentVid);
+                if (currentRef)
+                    u.searchParams.set('_affiliateo_ref', currentRef);
+                link.href = u.toString();
+            }
+            catch { /* swallow */ }
+        }
+        function onClickForLinkDecoration(ev) {
+            const t = ev.target;
+            if (!t || !t.closest)
+                return;
+            decorateOutboundLink(t.closest('a'));
+        }
+        function onKeydownForLinkDecoration(ev) {
+            if (ev.key !== 'Enter' && ev.key !== ' ')
+                return;
+            const t = ev.target;
+            if (!t || !t.closest)
+                return;
+            decorateOutboundLink(t.closest('a'));
+        }
+        if (allowedHosts.length > 0) {
+            document.addEventListener('click', onClickForLinkDecoration, true);
+            document.addEventListener('keydown', onKeydownForLinkDecoration, true);
+        }
         return () => {
             document.removeEventListener('visibilitychange', onVisibilityChange);
             window.removeEventListener('pagehide', sendEnd);
             window.removeEventListener('popstate', onUrlChange);
             history.pushState = origPushState;
             history.replaceState = origReplaceState;
+            if (allowedHosts.length > 0) {
+                document.removeEventListener('click', onClickForLinkDecoration, true);
+                document.removeEventListener('keydown', onKeydownForLinkDecoration, true);
+            }
             // Stop the queue's flush timer. The queue tries one final flush
             // before going quiet — anything still queued lives in localStorage
             // and will be picked up by the next page load's queue init.
@@ -528,6 +627,6 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             queueRef.current = null;
             providerMountCount = Math.max(0, providerMountCount - 1);
         };
-    }, [apiBase, track, identify, trackPageview, reset, optOut, optIn]);
+    }, [apiBase, allowedHostnames, track, identify, trackPageview, reset, optOut, optIn]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/types.d.ts

@@ -2,6 +2,30 @@ export interface AffiliateoConfig {
     campaignId: string;
     /** Base URL for the API. Defaults to https://affiliateo.com */
     apiUrl?: string;
+    /** Other domains that are part of the same merchant property and should
+     *  share visitor identity + affiliate ref code. When a visitor clicks a
+     *  link from the current page to any hostname in this list, the SDK
+     *  rewrites the link URL to append `_affiliateo_vid` and `_affiliateo_ref`
+     *  search params before the browser navigates. The receiving domain's
+     *  SDK reads those params on landing, uses them as the visitor identity
+     *  for that domain, and strips them from the URL bar so the user never
+     *  sees the tracking junk.
+     *
+     *  Without this, every cross-domain hop creates a brand-new anonymous
+     *  visitor with no affiliate ref (browsers sandbox localStorage per
+     *  origin), which silently breaks attribution: `?ref=jane` lands on
+     *  marketing.com → user clicks → app.com → no ref → affiliate gets $0.
+     *
+     *  Exact-match hostnames only (no wildcards). List every subdomain you
+     *  want to share identity with explicitly. The current domain doesn't
+     *  need to be listed.
+     *
+     *  Example:
+     *    <AffiliateoProvider
+     *      campaignId="..."
+     *      allowedHostnames={['app.merchant.com', 'docs.merchant.com']}
+     *    > */
+    allowedHostnames?: string[];
 }
 export interface AffiliateoContextValue {
     /** The affiliate ref code from the URL (if present) */

package/package.json

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