@affiliateo/web 2.4.0 → 3.1.0

package/dist/queue.d.ts

@@ -0,0 +1,99 @@
+/**
+ * EventQueue: durable best-effort delivery for analytics events.
+ *
+ * Why this exists:
+ *   Before this module, every track / identify / pageview was fire-and-forget
+ *   via navigator.sendBeacon. If the visitor's network blinked, the server
+ *   was briefly overloaded, or any other transient failure hit, the event
+ *   was lost with no retry, no log, no observability. On flaky mobile
+ *   networks (train wifi, subway transitions, dropping 4G) merchants saw
+ *   ~10-15% fewer events than they should have.
+ *
+ *   This queue mirrors the pattern PostHog / Segment / Amplitude / Datafast
+ *   all converged on: in-memory queue, localStorage persistence so events
+ *   survive page reload, periodic auto-flush, retry on failure up to N
+ *   times, drop after N tries to bound memory.
+ *
+ * Design notes:
+ *   - Persisted state is JSON in localStorage under STORAGE_KEY. The
+ *     persisted shape is intentionally simple (id + payload + retries)
+ *     so a future schema bump doesn't break a visitor who upgraded
+ *     mid-session and has events from the old shape sitting around.
+ *   - Failures are silent. The host app should never see an analytics
+ *     error bubble up. Console-noise during dev is the only signal.
+ *   - sendBeacon is NOT used here. sendBeacon is great for "fire on
+ *     unload" but it doesn't return a response we can branch on for
+ *     retry. fetch + keepalive gives us a status code AND lets the
+ *     browser keep the request alive across navigation. Trade-off: a
+ *     queued event fired right before the visitor closes the tab might
+ *     not land. That's why session_end stays on sendBeacon (see
+ *     provider.tsx, sendEnd helper).
+ *   - The flush timer uses setInterval. Stopped on shutdown(). The
+ *     provider only ever creates one queue per mount, so timer leaks
+ *     aren't a practical concern.
+ *
+ * Caps:
+ *   - MAX_RETRIES = 3   per-event retry ceiling before drop
+ *   - MAX_QUEUE_SIZE   hard cap so a long network outage can't fill
+ *                      localStorage and break the host app. Events
+ *                      beyond the cap are dropped FIFO (oldest first).
+ *   - FLUSH_INTERVAL_MS = 5_000   matches Datafast's web SDK default
+ *   - SIZE_FLUSH_THRESHOLD = 10   triggers a flush when queue grows
+ *                                 past this even before the timer fires
+ */
+export interface QueuedEvent {
+    /** Stable id used to identify the event across retries. UUID v4
+     *  generated client-side; collisions are astronomically unlikely so
+     *  we don't bother with a fallback. */
+    id: string;
+    /** The exact body the server expects. We persist the full payload
+     *  (not a delta) so a visitor who reloads mid-flush can still recover
+     *  every queued event without needing to know the original call site. */
+    payload: Record<string, unknown>;
+    /** Endpoint to POST to. Keyed per-event so a single queue can hold
+     *  both /api/v1/web/event (track + pageview) and /api/v1/web/identify
+     *  events without a separate queue per endpoint. */
+    endpoint: string;
+    /** Retry counter. Incremented on each failed flush. Event is dropped
+     *  when this hits MAX_RETRIES. */
+    retries: number;
+}
+export declare class EventQueue {
+    private queue;
+    private flushTimer;
+    private isFlushing;
+    private shuttingDown;
+    constructor();
+    /** 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. */
+    enqueue(endpoint: string, payload: Record<string, unknown>): void;
+    /** Try to deliver every queued event. Each event gets one attempt
+     *  per flush; failures bump retries and stay in the queue for the
+     *  next flush. Events that hit MAX_RETRIES get dropped.
+     *
+     *  Concurrency: guarded by isFlushing so overlapping calls (the
+     *  burst path + the timer firing simultaneously) only run one
+     *  flush at a time. */
+    flush(): Promise<void>;
+    /** Best-effort sync flush triggered on page unload. Uses sendBeacon
+     *  for each event so it survives the tab closing. No retry — this is
+     *  the last chance.
+     *
+     *  Called from the provider's pagehide / visibilitychange=hidden
+     *  handlers so any events still queued at unload get one last shot.
+     *  After this call, the in-memory queue is cleared (events that
+     *  sendBeacon couldn't queue are lost — that's the cost of the
+     *  guaranteed-fast unload path). */
+    flushOnUnload(): void;
+    /** Wipe the queue. Called by reset() and optOut(). Removes the
+     *  localStorage entry entirely so a reload doesn't re-hydrate the
+     *  wiped events. */
+    clear(): void;
+    /** Stop the flush timer and try one final flush. Idempotent. */
+    shutdown(): void;
+    /** Read-only size getter. Used by tests / debug consoles. */
+    get size(): number;
+    private persist;
+    private startFlushTimer;
+}

package/dist/queue.js

@@ -0,0 +1,266 @@
+/**
+ * EventQueue: durable best-effort delivery for analytics events.
+ *
+ * Why this exists:
+ *   Before this module, every track / identify / pageview was fire-and-forget
+ *   via navigator.sendBeacon. If the visitor's network blinked, the server
+ *   was briefly overloaded, or any other transient failure hit, the event
+ *   was lost with no retry, no log, no observability. On flaky mobile
+ *   networks (train wifi, subway transitions, dropping 4G) merchants saw
+ *   ~10-15% fewer events than they should have.
+ *
+ *   This queue mirrors the pattern PostHog / Segment / Amplitude / Datafast
+ *   all converged on: in-memory queue, localStorage persistence so events
+ *   survive page reload, periodic auto-flush, retry on failure up to N
+ *   times, drop after N tries to bound memory.
+ *
+ * Design notes:
+ *   - Persisted state is JSON in localStorage under STORAGE_KEY. The
+ *     persisted shape is intentionally simple (id + payload + retries)
+ *     so a future schema bump doesn't break a visitor who upgraded
+ *     mid-session and has events from the old shape sitting around.
+ *   - Failures are silent. The host app should never see an analytics
+ *     error bubble up. Console-noise during dev is the only signal.
+ *   - sendBeacon is NOT used here. sendBeacon is great for "fire on
+ *     unload" but it doesn't return a response we can branch on for
+ *     retry. fetch + keepalive gives us a status code AND lets the
+ *     browser keep the request alive across navigation. Trade-off: a
+ *     queued event fired right before the visitor closes the tab might
+ *     not land. That's why session_end stays on sendBeacon (see
+ *     provider.tsx, sendEnd helper).
+ *   - The flush timer uses setInterval. Stopped on shutdown(). The
+ *     provider only ever creates one queue per mount, so timer leaks
+ *     aren't a practical concern.
+ *
+ * Caps:
+ *   - MAX_RETRIES = 3   per-event retry ceiling before drop
+ *   - MAX_QUEUE_SIZE   hard cap so a long network outage can't fill
+ *                      localStorage and break the host app. Events
+ *                      beyond the cap are dropped FIFO (oldest first).
+ *   - FLUSH_INTERVAL_MS = 5_000   matches Datafast's web SDK default
+ *   - SIZE_FLUSH_THRESHOLD = 10   triggers a flush when queue grows
+ *                                 past this even before the timer fires
+ */
+const STORAGE_KEY = 'affiliateo_event_queue';
+const MAX_RETRIES = 3;
+const MAX_QUEUE_SIZE = 100;
+const FLUSH_INTERVAL_MS = 5000;
+const SIZE_FLUSH_THRESHOLD = 10;
+function lsGet(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function lsSet(key, value) {
+    try {
+        localStorage.setItem(key, value);
+    }
+    catch { /* quota / private mode */ }
+}
+function lsRemove(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch { /* swallow */ }
+}
+function uuid() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID)
+        return crypto.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export class EventQueue {
+    constructor() {
+        this.queue = [];
+        this.flushTimer = null;
+        this.isFlushing = false;
+        this.shuttingDown = false;
+        // 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
+        // lose a few stuck events than crash the host app on init.
+        try {
+            const raw = lsGet(STORAGE_KEY);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed)) {
+                    this.queue = parsed.filter((e) => !!e && typeof e === 'object'
+                        && typeof e.id === 'string'
+                        && typeof e.endpoint === 'string'
+                        && typeof e.payload === 'object'
+                        && typeof e.retries === 'number');
+                }
+            }
+        }
+        catch {
+            this.queue = [];
+        }
+        this.startFlushTimer();
+        // Try an immediate flush on construction so events left over from
+        // a previous session get a head start (especially useful on the
+        // page-load-after-an-outage scenario).
+        if (this.queue.length > 0) {
+            void this.flush();
+        }
+    }
+    /** 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. */
+    enqueue(endpoint, payload) {
+        if (this.shuttingDown)
+            return;
+        this.queue.push({
+            id: uuid(),
+            endpoint,
+            payload,
+            retries: 0,
+        });
+        // FIFO drop when over cap. Network outage edge case: if we're way
+        // 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);
+        }
+        this.persist();
+        // Burst protection: when many events fire in quick succession
+        // (auto-pageview + immediate track + identify on app boot), don't
+        // wait for the 5s timer — flush right away. The isFlushing guard
+        // inside flush() makes overlapping calls safe.
+        if (this.queue.length >= SIZE_FLUSH_THRESHOLD) {
+            void this.flush();
+        }
+    }
+    /** Try to deliver every queued event. Each event gets one attempt
+     *  per flush; failures bump retries and stay in the queue for the
+     *  next flush. Events that hit MAX_RETRIES get dropped.
+     *
+     *  Concurrency: guarded by isFlushing so overlapping calls (the
+     *  burst path + the timer firing simultaneously) only run one
+     *  flush at a time. */
+    async flush() {
+        if (this.isFlushing || this.queue.length === 0)
+            return;
+        this.isFlushing = true;
+        // Snapshot the queue so we iterate a stable list — new enqueue()
+        // calls during the flush land in the live queue and get picked up
+        // by the next flush rather than this one (avoids infinite loops
+        // and reasoning headaches).
+        const batch = this.queue.slice();
+        for (const event of batch) {
+            let ok = false;
+            try {
+                const res = await fetch(event.endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(event.payload),
+                    // keepalive lets the request survive a navigation. paired
+                    // with the queue so even if this fetch errors, we'll retry.
+                    keepalive: true,
+                });
+                // 2xx = success. Anything else (4xx, 5xx) counts as a failure
+                // and bumps retries. A 4xx is usually a permanent error
+                // (bad payload, dead campaign) so retrying 3 times then
+                // dropping is the right move — keeps the queue clean.
+                ok = res.ok;
+            }
+            catch {
+                ok = false;
+            }
+            if (ok) {
+                // Remove from live queue (not the snapshot) by id
+                this.queue = this.queue.filter((e) => e.id !== event.id);
+            }
+            else {
+                // Find the live entry and bump its retry counter. Use id
+                // because the index may have shifted if other events were
+                // already removed on this pass.
+                const live = this.queue.find((e) => e.id === event.id);
+                if (live) {
+                    live.retries++;
+                    if (live.retries >= MAX_RETRIES) {
+                        this.queue = this.queue.filter((e) => e.id !== event.id);
+                    }
+                }
+            }
+        }
+        this.persist();
+        this.isFlushing = false;
+    }
+    /** Best-effort sync flush triggered on page unload. Uses sendBeacon
+     *  for each event so it survives the tab closing. No retry — this is
+     *  the last chance.
+     *
+     *  Called from the provider's pagehide / visibilitychange=hidden
+     *  handlers so any events still queued at unload get one last shot.
+     *  After this call, the in-memory queue is cleared (events that
+     *  sendBeacon couldn't queue are lost — that's the cost of the
+     *  guaranteed-fast unload path). */
+    flushOnUnload() {
+        if (this.queue.length === 0)
+            return;
+        if (typeof navigator === 'undefined' || !navigator.sendBeacon) {
+            // No sendBeacon (very old browser) — try a sync fetch with
+            // keepalive as a fallback. Won't actually finish, but it's our
+            // last shot.
+            for (const event of this.queue) {
+                try {
+                    fetch(event.endpoint, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify(event.payload),
+                        keepalive: true,
+                    }).catch(() => { });
+                }
+                catch { /* swallow */ }
+            }
+            this.queue = [];
+            this.persist();
+            return;
+        }
+        for (const event of this.queue) {
+            try {
+                navigator.sendBeacon(event.endpoint, new Blob([JSON.stringify(event.payload)], { type: 'application/json' }));
+            }
+            catch { /* swallow */ }
+        }
+        this.queue = [];
+        this.persist();
+    }
+    /** Wipe the queue. Called by reset() and optOut(). Removes the
+     *  localStorage entry entirely so a reload doesn't re-hydrate the
+     *  wiped events. */
+    clear() {
+        this.queue = [];
+        lsRemove(STORAGE_KEY);
+    }
+    /** Stop the flush timer and try one final flush. Idempotent. */
+    shutdown() {
+        this.shuttingDown = true;
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        void this.flush();
+    }
+    /** Read-only size getter. Used by tests / debug consoles. */
+    get size() {
+        return this.queue.length;
+    }
+    persist() {
+        lsSet(STORAGE_KEY, JSON.stringify(this.queue));
+    }
+    startFlushTimer() {
+        if (this.flushTimer !== null)
+            return;
+        this.flushTimer = setInterval(() => {
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+    }
+}

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) */
@@ -34,4 +58,54 @@ export interface AffiliateoContextValue {
      *    const { identify } = useAffiliateRef()
      *    useEffect(() => { if (user) identify(user.id) }, [user]) */
     identify: (userId: string) => Promise<void>;
+    /** Manually fire a pageview. The SDK already auto-fires on mount and on
+     *  SPA route changes; use this only when you want extra control (e.g.
+     *  tracking modal opens as virtual pageviews, or merchants who disabled
+     *  auto-pageviews for custom routing).
+     *
+     *  - With no args: tracks the CURRENT page (same as the auto-fired one).
+     *  - With a path: tracks that path. Useful for virtual pages.
+     *
+     *  Example:
+     *    const { trackPageview } = useAffiliateRef()
+     *    function PricingModal({ open }: { open: boolean }) {
+     *      useEffect(() => { if (open) trackPageview('/pricing-modal') }, [open])
+     *    } */
+    trackPageview: (path?: string) => Promise<void>;
+    /** Wipe the visitor identity. Mints a fresh visitor_id and clears the
+     *  affiliate ref + campaign_id from localStorage so the next pageview
+     *  is treated as a brand-new anonymous visitor.
+     *
+     *  Use case: call on user logout so a different person sitting down at
+     *  the same browser doesn't get their actions merged into the previous
+     *  user's funnel. Without this, shared family computers / kiosks /
+     *  hot-desks silently pollute attribution.
+     *
+     *  Example:
+     *    const { reset } = useAffiliateRef()
+     *    async function handleLogout() {
+     *      await supabase.auth.signOut()
+     *      await reset()
+     *      router.push('/')
+     *    } */
+    reset: () => Promise<void>;
+    /** Stop tracking this visitor. Sets a persistent opt-out flag in
+     *  localStorage and silences all subsequent track / identify / pageview
+     *  calls until optIn() is called. Survives reloads, doesn't survive a
+     *  hard browser reset.
+     *
+     *  Use case: GDPR / CCPA cookie banner where the visitor picked
+     *  "Don't track me." Call optOut() once and the SDK noops everything
+     *  for that visitor.
+     *
+     *  Example:
+     *    const { optOut } = useAffiliateRef()
+     *    <button onClick={() => optOut()}>Don't track me</button> */
+    optOut: () => void;
+    /** Re-enable tracking after a previous optOut(). Removes the persistent
+     *  flag. Note: tracking only resumes for events fired AFTER this call,
+     *  the current pageview won't retroactively send. A full page reload is
+     *  the cleanest way to bring the SDK back to its normal "auto-fire on
+     *  mount" state. */
+    optIn: () => void;
 }

package/package.json

@@ -1,34 +1,34 @@
-{
-  "name": "@affiliateo/web",
-  "version": "2.4.0",
-  "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/react": "^19.0.0",
-    "typescript": "^5.0.0"
-  },
-  "keywords": ["affiliateo", "affiliate", "attribution", "stripe", "web", "session", "tracking"],
-  "license": "MIT",
-  "files": ["dist"]
-}
+{
+  "name": "@affiliateo/web",
+  "version": "3.1.0",
+  "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": ["affiliateo", "affiliate", "attribution", "stripe", "web", "session", "tracking"],
+  "license": "MIT",
+  "files": ["dist"]
+}