@affiliateo/web 2.0.0 → 2.2.0

package/README.md

@@ -1,44 +1,234 @@
-# @affiliateo/web
-
-Affiliateo web SDK — pass affiliate attribution metadata to your Stripe checkout.
-
-## Install
-
-```bash
-npm install @affiliateo/web
-```
-
-## Setup
-
-1. Make sure you have the Affiliateo tracking script on your site (for visitor tracking)
-2. Connect your Stripe account on the Affiliateo dashboard
-3. Add one line to your Stripe checkout creation:
-
-```ts
-import { getMetadata } from '@affiliateo/web';
-
-// Your existing checkout route
-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: getMetadata(req),
-});
-```
-
-That's it. Affiliateo will automatically attribute the purchase to the right affiliate.
-
-## How it works
-
-1. Your tracking script (`t.js`) sets cookies when a visitor arrives via an affiliate link
-2. `getMetadata(req)` reads those cookies and returns them as Stripe metadata
-3. When the payment completes, Affiliateo's webhook reads the metadata and credits the affiliate
-
-## Framework support
-
-Works with any Node.js framework:
-- **Next.js** (App Router & Pages Router)
-- **Express**
-- **Fastify**
-- Any framework that exposes request cookies
+# @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 once when the section becomes 50%+ visible. 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.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useRef, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
@@ -30,9 +30,12 @@ function uuid() {
         return v.toString(16);
     });
 }
+const asyncNoop = async () => { };
 const AffiliateoContext = createContext({
     refCode: null,
     visitorId: null,
+    track: asyncNoop,
+    identify: asyncNoop,
 });
 /**
  * Returns the affiliate ref code and visitor ID.
@@ -66,17 +69,123 @@ export function getAttribution() {
         data.affiliateo_campaign_id = cid;
     return data;
 }
+// Double-mount detection. The host app should mount AffiliateoProvider
+// exactly once near the root. Mounting twice produces double pageviews,
+// duplicate history.pushState patches stacking on each other, and
+// competing session_end signals. We can't always *prevent* the second
+// 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, }) {
     const [state, setState] = useState({
         refCode: null,
         visitorId: null,
+        track: asyncNoop,
+        identify: asyncNoop,
     });
     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
+    // captured by host-side `useRef` no longer drift to a stale id.
     const campaignIdRef = useRef(campaignId);
+    campaignIdRef.current = campaignId;
+    // Mint visitorId once and put it in a ref so it survives campaignId
+    // prop changes without forcing a re-fetch / re-mint cycle. Same UUID
+    // for the lifetime of the localStorage entry across the whole tab.
+    const visitorIdRef = useRef(null);
+    // track + identify are defined OUTSIDE the route-effect so they
+    // close over refs (campaignIdRef, visitorIdRef) rather than the
+    // captured-once values from inside the effect. A consumer caching
+    // `track` keeps firing under the LATEST (campaignId, visitorId).
+    const track = useCallback(async (eventName, metadata) => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            if (!eventName || typeof eventName !== 'string')
+                return;
+            const name = eventName.trim().toLowerCase();
+            if (!name || name.length > 64 || !/^[a-z0-9_:-]+$/.test(name))
+                return;
+            const cid = campaignIdRef.current;
+            const vid = visitorIdRef.current;
+            if (!cid || !vid)
+                return;
+            const payload = {
+                type: 'custom',
+                campaign_id: cid,
+                visitor_id: vid,
+                event_name: name,
+            };
+            if (metadata && typeof metadata === 'object')
+                payload.metadata = metadata;
+            const data = JSON.stringify(payload);
+            const endpoint = `${apiBase}/api/v1/web/event`;
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
+            }
+            else {
+                fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: data,
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
+        catch { /* swallow */ }
+    }, [apiBase]);
+    // 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.
+    const identify = useCallback(async (userId) => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            if (!userId || typeof userId !== 'string')
+                return;
+            const uid = userId.trim();
+            // Cap at 128 chars (matches the server). Covers every common
+            // foreign user-id shape: uuid, ulid, mongo objectId, auth0 sub,
+            // firebase uid, supabase uuid.
+            if (!uid || uid.length > 128)
+                return;
+            const cid = campaignIdRef.current;
+            const vid = visitorIdRef.current;
+            if (!cid || !vid)
+                return;
+            const payload = {
+                campaign_id: cid,
+                visitor_id: vid,
+                user_id: uid,
+            };
+            const data = JSON.stringify(payload);
+            const url = `${apiBase}/api/v1/web/identify`;
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(url, new Blob([data], { type: 'application/json' }));
+            }
+            else {
+                fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: data,
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
+        catch { /* swallow */ }
+    }, [apiBase]);
     const sentRef = useRef(false);
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
+        // Mount-count warning. Fires only when more than one Provider has
+        // ever mounted in the page lifetime. Dev-only; production swallows
+        // the warning to avoid noise in real merchant consoles.
+        providerMountCount += 1;
+        if (providerMountCount > 1 && process.env.NODE_ENV !== 'production') {
+            // eslint-disable-next-line no-console
+            console.warn('[Affiliateo] AffiliateoProvider mounted more than once. Mount it exactly once near the root of your app, or pageviews will double-fire.');
+        }
         // Get or create visitor ID
         let vid = lsGet(LS_VISITOR_ID);
         if (!vid) {
@@ -84,6 +193,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         }
         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')
@@ -91,7 +201,22 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         if (ref) {
             lsSet(LS_REF, ref);
         }
-        setState({ refCode: ref, visitorId: vid });
+        const endpoint = `${apiBase}/api/v1/web/event`;
+        setState({ refCode: ref, visitorId: vid, track, identify });
+        function beacon(payload) {
+            const data = JSON.stringify(payload);
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
+            }
+            else {
+                fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: data,
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
         // Throttle: max 1 pageview per second
         let lastSendTime = 0;
         function sendPageview() {
@@ -99,7 +224,8 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             if (now - lastSendTime < 1000)
                 return;
             lastSendTime = now;
-            const payload = {
+            ended = false;
+            beacon({
                 type: 'pageview',
                 campaign_id: campaignIdRef.current,
                 visitor_id: vid,
@@ -112,26 +238,32 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
                 utm_medium: params.get('utm_medium') || '',
                 utm_campaign: params.get('utm_campaign') || '',
                 screen_width: window.innerWidth,
-            };
-            fetch(`${apiBase}/api/v1/web/event`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(payload),
-                keepalive: true,
-            }).then(async (r) => {
-                if (!r.ok) {
-                    const text = await r.text().catch(() => '');
-                    console.error(`[Affiliateo] Event failed (${r.status}):`, text);
-                }
-            }).catch((err) => {
-                console.error('[Affiliateo] Event send error:', err);
             });
         }
+        // Send session_end when user leaves
+        let ended = false;
+        function sendEnd() {
+            if (ended)
+                return;
+            ended = true;
+            beacon({ type: 'session_end', campaign_id: campaignIdRef.current, visitor_id: vid, ref: ref || lsGet(LS_REF) || '' });
+        }
+        function onVisibilityChange() {
+            if (document.visibilityState === 'hidden') {
+                sendEnd();
+            }
+            else {
+                ended = false;
+            } // reset if they come back (tab switch)
+        }
         // Send pageview on mount
         if (!sentRef.current) {
             sentRef.current = true;
             sendPageview();
         }
+        // Detect user leaving
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        window.addEventListener('pagehide', sendEnd);
         // SPA support: detect URL changes
         let lastPath = window.location.pathname;
         function onUrlChange() {
@@ -151,11 +283,102 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             origReplaceState.apply(this, args);
             onUrlChange();
         };
+        // HTML-attribute goal tracking. match Datafast's `data-fast-goal`
+        // ergonomics. Any element with `data-affiliateo-goal="event_name"`
+        // fires that goal on click. Optional `data-affiliateo-goal-*`
+        // attributes become metadata (kebab-case to snake_case, max 10).
+        //
+        // Delegated listener on document.body so the merchant doesn't have
+        // to re-attach handlers when their SPA re-renders. Capture phase off
+        // so React's synthetic event ordering isn't disturbed.
+        function onDocClick(e) {
+            const target = e.target;
+            if (!(target instanceof Element))
+                return;
+            const el = target.closest('[data-affiliateo-goal]');
+            if (!el)
+                return;
+            const goal = el.getAttribute('data-affiliateo-goal');
+            if (!goal)
+                return;
+            const meta = {};
+            let count = 0;
+            for (const { name, value } of Array.from(el.attributes)) {
+                if (!name.startsWith('data-affiliateo-goal-'))
+                    continue;
+                // Skip the bare "data-affiliateo-goal" attribute itself
+                // (slice would produce an empty key).
+                if (name === 'data-affiliateo-goal')
+                    continue;
+                if (count >= 10)
+                    break;
+                const key = name.slice('data-affiliateo-goal-'.length).replace(/-/g, '_');
+                // Skip the reserved `event` key so an attribute like
+                // `data-affiliateo-goal-event="x"` can't override the actual
+                // goal name when the SDK / server folds metadata.event in.
+                if (!key || key === 'event')
+                    continue;
+                if (value) {
+                    meta[key] = String(value).slice(0, 255);
+                    count++;
+                }
+            }
+            track(goal, count ? meta : undefined);
+        }
+        document.addEventListener('click', onDocClick);
+        // Scroll-depth goal tracking. `data-affiliateo-scroll="event_name"`
+        // on any element fires that goal the first time the element enters
+        // the viewport. Use IntersectionObserver (cheap, off the scroll hot
+        // path) and unobserve after the first fire so the same element can't
+        // double-count if the user scrolls back up.
+        const scrollFired = new WeakSet();
+        let scrollObserver = null;
+        let scrollMo = null;
+        if (typeof IntersectionObserver !== 'undefined') {
+            scrollObserver = new IntersectionObserver((entries) => {
+                for (const entry of entries) {
+                    if (!entry.isIntersecting)
+                        continue;
+                    if (scrollFired.has(entry.target))
+                        continue;
+                    scrollFired.add(entry.target);
+                    const goal = entry.target.getAttribute('data-affiliateo-scroll');
+                    if (goal)
+                        track(goal);
+                    scrollObserver?.unobserve(entry.target);
+                }
+            }, { threshold: 0.5 });
+            // Observe everything that exists at mount time.
+            document.querySelectorAll('[data-affiliateo-scroll]').forEach((el) => {
+                scrollObserver?.observe(el);
+            });
+            // SPA-rendered sections that appear later get observed via
+            // MutationObserver. Cheap because we only scan added nodes, not
+            // the whole tree on each mutation.
+            scrollMo = new MutationObserver((mutations) => {
+                for (const m of mutations) {
+                    m.addedNodes.forEach((node) => {
+                        if (!(node instanceof Element))
+                            return;
+                        if (node.hasAttribute('data-affiliateo-scroll'))
+                            scrollObserver?.observe(node);
+                        node.querySelectorAll?.('[data-affiliateo-scroll]').forEach((el) => scrollObserver?.observe(el));
+                    });
+                }
+            });
+            scrollMo.observe(document.body, { childList: true, subtree: true });
+        }
         return () => {
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+            window.removeEventListener('pagehide', sendEnd);
             window.removeEventListener('popstate', onUrlChange);
+            document.removeEventListener('click', onDocClick);
+            scrollMo?.disconnect();
+            scrollObserver?.disconnect();
             history.pushState = origPushState;
             history.replaceState = origReplaceState;
+            providerMountCount = Math.max(0, providerMountCount - 1);
         };
-    }, [campaignId, apiBase]);
+    }, [apiBase, track, identify]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/types.d.ts

@@ -8,4 +8,30 @@ export interface AffiliateoContextValue {
     refCode: string | null;
     /** The visitor ID stored in the cookie */
     visitorId: string | null;
+    /** Fire a custom goal. signup_completed, trial_started, feature_used, etc.
+     *  Best-effort: failures are swallowed so analytics calls never throw in
+     *  the host app. Event name must be lowercase letters / digits / `_-:`
+     *  and ≤ 64 chars. Optional metadata is bounded to 4KB JSON. The funnel
+     *  evaluator's step type 'custom' matches against the event name.
+     *
+     *  Example:
+     *    const { track } = useAffiliateRef()
+     *    track('signup_completed', { plan: 'pro' }) */
+    track: (eventName: string, metadata?: Record<string, unknown>) => Promise<void>;
+    /** Link this anonymous visitor to a merchant user_id. Call after
+     *  sign-in / sign-up so the funnel can stitch the same person across
+     *  devices, subdomains, and sessions.
+     *
+     *  Without identify(), browsing on phone + buying on laptop look like
+     *  two unrelated visitors and the funnel can't connect them. With it,
+     *  both events resolve to the same user_id and the funnel reports a
+     *  single converted person.
+     *
+     *  Idempotent: safe to call on every page load. user_id only —
+     *  the SDK does not accept or transmit email or any other PII.
+     *
+     *  Example:
+     *    const { identify } = useAffiliateRef()
+     *    useEffect(() => { if (user) identify(user.id) }, [user]) */
+    identify: (userId: string) => Promise<void>;
 }

package/package.json

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