@nurdd/web-sdk 1.0.0

package/dist/nurdd-sdk.umd.js

@@ -0,0 +1,1132 @@
+/*!
+ * @nurdd/web-sdk — UMD bundle
+ * Framework-agnostic attribution & analytics SDK.
+ * Exposes `window.Nurdd` (also CommonJS / AMD compatible).
+ */
+;(function (global, factory) {
+    if (typeof exports === "object" && typeof module !== "undefined") {
+        module.exports = factory();
+    } else if (typeof define === "function" && define.amd) {
+        define(factory);
+    } else {
+        global.Nurdd = factory();
+    }
+})(typeof self !== "undefined" ? self : this, function () {
+"use strict";
+
+// ===== src/env.js =====
+
+// Runtime detection so the same module works in browsers, SSR, web workers,
+// React Native (via metro shimming `window`), and any other JS host.
+    typeof window !== "undefined" &&
+    typeof document !== "undefined" &&
+    typeof navigator !== "undefined";
+    try {
+        if (!isBrowser) return false;
+        const k = "__nurdd_probe__";
+        window.localStorage.setItem(k, "1");
+        window.localStorage.removeItem(k);
+        return true;
+    } catch {
+        return false;
+    }
+})();
+
+
+// ===== src/utils.js =====
+
+// Tiny helpers used across the SDK. No dependencies on env so they're
+// safe to import from SSR contexts.
+    // Prefer the platform impl when available — it's cryptographically random.
+    if (typeof globalThis.crypto?.randomUUID === "function") {
+        return globalThis.crypto.randomUUID();
+    }
+    // RFC 4122 v4-ish fallback. Fine for device IDs / event IDs.
+    const rnd = (n) => Math.floor(Math.random() * n);
+    const seg = (n) => Array.from({ length: n }, () => rnd(16).toString(16)).join("");
+    return `${seg(8)}-${seg(4)}-4${seg(3)}-${(8 + rnd(4)).toString(16)}${seg(3)}-${seg(12)}`;
+}
+    try { return JSON.parse(value); } catch { return fallback; }
+}
+
+// Stable hash, ASCII-friendly. Not cryptographic — used only for client
+// fingerprint hints; the backend computes the canonical fingerprint.
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < str.length; i += 1) {
+        h ^= str.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16).padStart(8, "0");
+}
+    let t = null;
+    return (...args) => {
+        if (t) clearTimeout(t);
+        t = setTimeout(() => fn(...args), wait);
+    };
+}
+
+// Merges options with a defaults object, allowing nested objects but not
+// arrays (consumer arrays always replace defaults — fewer surprises).
+    if (!overrides) return { ...defaults };
+    const out = { ...defaults };
+    for (const [k, v] of Object.entries(overrides)) {
+        if (v === undefined) continue;
+        if (v && typeof v === "object" && !Array.isArray(v) && defaults[k] && typeof defaults[k] === "object") {
+            out[k] = { ...defaults[k], ...v };
+        } else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+
+
+// ===== src/logger.js =====
+
+// Minimal, level-gated logger. `debug` defaults to OFF so the SDK is
+// silent in production unless the host explicitly opts in.
+    const noop = () => {};
+    if (!enabled) return { debug: noop, info: noop, warn: console?.warn?.bind(console) || noop, error: console?.error?.bind(console) || noop };
+    return {
+        debug: console.debug?.bind(console, prefix) || noop,
+        info: console.info?.bind(console, prefix) || noop,
+        warn: console.warn?.bind(console, prefix) || noop,
+        error: console.error?.bind(console, prefix) || noop,
+    };
+}
+
+
+// ===== src/storage.js =====
+
+
+// Tiered storage. localStorage is preferred (persists across tabs and
+// across browser restarts); when unavailable (private mode, embedded
+// webviews, SSR) we fall back to an in-memory map so the SDK keeps
+// functioning without crashing.
+
+class MemoryStorage {
+    constructor() { this.map = new Map(); }
+    get(k) { return this.map.get(k) ?? null; }
+    set(k, v) { this.map.set(k, v); }
+    remove(k) { this.map.delete(k); }
+}
+
+class LocalStorageBacked {
+    constructor(prefix) { this.prefix = prefix; }
+    _key(k) { return `${this.prefix}${k}`; }
+    get(k) {
+        try { return window.localStorage.getItem(this._key(k)); }
+        catch { return null; }
+    }
+    set(k, v) {
+        try { window.localStorage.setItem(this._key(k), v); }
+        catch { /* quota / private mode */ }
+    }
+    remove(k) {
+        try { window.localStorage.removeItem(this._key(k)); }
+        catch { /* noop */ }
+    }
+}
+    const backing = hasLocalStorage ? new LocalStorageBacked(prefix) : new MemoryStorage();
+    return {
+        getString(key) { return backing.get(key); },
+        setString(key, value) { backing.set(key, value); },
+        getJson(key, fallback = null) {
+            const raw = backing.get(key);
+            if (raw == null) return fallback;
+            return safeJsonParse(raw, fallback);
+        },
+        setJson(key, value) { backing.set(key, JSON.stringify(value)); },
+        remove(key) { backing.remove(key); },
+        isPersistent: hasLocalStorage,
+        isBrowser,
+    };
+}
+
+
+// ===== src/device.js =====
+
+
+const DEVICE_ID_KEY = "device_id";
+
+// Builds the device payload the backend expects on every event. The
+// backend re-validates and fills in anything we miss server-side.
+    let deviceId = storage.getString(DEVICE_ID_KEY);
+    if (!deviceId) {
+        deviceId = uuid();
+        storage.setString(DEVICE_ID_KEY, deviceId);
+    }
+
+    if (!isBrowser) {
+        return {
+            device_id: deviceId,
+            platform: "server",
+            sdk_version: SDK_VERSION,
+            app_version: appVersion || null,
+        };
+    }
+
+    const nav = window.navigator || {};
+    const screen = window.screen || {};
+    const locale = nav.language || nav.userLanguage || null;
+    let timezone = null;
+    try { timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || null; } catch { /* ignore */ }
+
+    return {
+        device_id: deviceId,
+        platform: "web",
+        os_name: parseOsName(nav.userAgent || ""),
+        os_version: null,
+        model: null,
+        manufacturer: null,
+        app_version: appVersion || null,
+        sdk_version: SDK_VERSION,
+        locale,
+        timezone,
+        attributes: {
+            user_agent: nav.userAgent || null,
+            screen: `${screen.width || 0}x${screen.height || 0}`,
+            viewport: `${window.innerWidth || 0}x${window.innerHeight || 0}`,
+            color_depth: screen.colorDepth || null,
+            pixel_ratio: window.devicePixelRatio || 1,
+            hardware_concurrency: nav.hardwareConcurrency || null,
+            do_not_track: nav.doNotTrack === "1" || nav.doNotTrack === "yes",
+        },
+    };
+}
+
+function parseOsName(ua) {
+    if (/Windows NT/i.test(ua)) return "Windows";
+    if (/Mac OS X/i.test(ua)) return "macOS";
+    if (/Android/i.test(ua)) return "Android";
+    if (/iPhone|iPad|iPod/i.test(ua)) return "iOS";
+    if (/Linux/i.test(ua)) return "Linux";
+    if (/CrOS/i.test(ua)) return "ChromeOS";
+    return null;
+}
+
+// Local fingerprint hint. The server computes the authoritative
+// fingerprint from IP+UA, but we provide a stable client value so
+// clicks and installs can also match in pure-frontend flows.
+    const a = device.attributes || {};
+    return fnv1a([
+        device.platform,
+        device.os_name,
+        device.locale,
+        device.timezone,
+        a.screen,
+        a.color_depth,
+        a.pixel_ratio,
+        a.hardware_concurrency,
+    ].join("|"));
+}
+
+
+// ===== src/utm.js =====
+
+const UTM_KEYS = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+    "utm_id",
+];
+
+// Reads UTM params and a few common attribution params from `location.search`.
+// Stable across SPA navigations because the SDK re-reads on every page view.
+    if (!isBrowser) return {};
+    try {
+        const params = new URLSearchParams(window.location.search);
+        const out = {};
+        for (const key of UTM_KEYS) {
+            const v = params.get(key);
+            if (v) out[key] = v;
+        }
+        // Auxiliary identifiers we commonly want to attribute on.
+        const short = params.get("sdk_short_code") || params.get("nurdd_shortcode");
+        if (short) out.short_code = short;
+        const click = params.get("click_id") || params.get("gclid") || params.get("fbclid");
+        if (click) out.click_id = click;
+        return out;
+    } catch {
+        return {};
+    }
+}
+
+// Strips UTM params from the current URL so a single visit doesn't get
+// counted on every subsequent page view. Best-effort: requires history API.
+    if (!isBrowser || !window.history?.replaceState) return;
+    try {
+        const url = new URL(window.location.href);
+        let changed = false;
+        for (const k of UTM_KEYS) {
+            if (url.searchParams.has(k)) { url.searchParams.delete(k); changed = true; }
+        }
+        if (changed) window.history.replaceState({}, "", url.toString());
+    } catch { /* ignore */ }
+}
+
+
+// ===== src/transport.js =====
+
+// Network transport. Designed around three constraints:
+//  1. The page may close mid-request (unload) — we use `sendBeacon` /
+//     `keepalive: true` whenever possible so events still ship.
+//  2. The network may be flaky — retries use exponential backoff with
+//     jitter; 5xx and network errors are retried, 4xx are not.
+//  3. We never throw into the host app — every public call resolves with
+//     an { ok, status, data, error } shape.
+
+const RETRY_STATUSES = new Set([0, 408, 425, 429, 500, 502, 503, 504]);
+    constructor({ baseUrl, sdkKey, logger, maxRetries = 4, baseRetryDelayMs = 250, timeoutMs = 15_000 }) {
+        if (!baseUrl) throw new Error("[nurdd] baseUrl is required");
+        if (!sdkKey) throw new Error("[nurdd] sdkKey is required");
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.sdkKey = sdkKey;
+        this.logger = logger;
+        this.maxRetries = maxRetries;
+        this.baseRetryDelayMs = baseRetryDelayMs;
+        this.timeoutMs = timeoutMs;
+    }
+
+    _headers() {
+        return {
+            "Content-Type": "application/json",
+            "X-SDK-Key": this.sdkKey,
+            "X-SDK-Platform": "web",
+        };
+    }
+
+    _backoff(attempt) {
+        const jitter = Math.random() * this.baseRetryDelayMs;
+        return this.baseRetryDelayMs * 2 ** attempt + jitter;
+    }
+
+    async request(path, { method = "GET", body, beacon = false, signal } = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const init = {
+            method,
+            headers: this._headers(),
+            // `keepalive` lets fetch survive page navigation. Capped at 64KB.
+            keepalive: beacon === true || method !== "GET",
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal,
+        };
+
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            try {
+                const ac = new AbortController();
+                const timeoutId = setTimeout(() => ac.abort(), this.timeoutMs);
+                // Combine the consumer-provided signal with our own timeout.
+                if (signal) signal.addEventListener("abort", () => ac.abort(), { once: true });
+
+                const res = await fetch(url, { ...init, signal: ac.signal });
+                clearTimeout(timeoutId);
+
+                if (res.ok) {
+                    const data = await this._parseBody(res);
+                    return { ok: true, status: res.status, data };
+                }
+                if (!RETRY_STATUSES.has(res.status) || attempt === this.maxRetries) {
+                    const data = await this._parseBody(res);
+                    return { ok: false, status: res.status, data, error: data?.error || `HTTP ${res.status}` };
+                }
+                lastError = new Error(`HTTP ${res.status}`);
+            } catch (err) {
+                lastError = err;
+                if (attempt === this.maxRetries) {
+                    return { ok: false, status: 0, error: err?.message || "Network error" };
+                }
+            }
+            await new Promise((r) => setTimeout(r, this._backoff(attempt)));
+        }
+        return { ok: false, status: 0, error: lastError?.message || "Unknown error" };
+    }
+
+    async _parseBody(res) {
+        const text = await res.text();
+        if (!text) return null;
+        try { return JSON.parse(text); } catch { return text; }
+    }
+
+    // Fire-and-forget delivery used during page unload. Falls back to
+    // a keepalive fetch when sendBeacon isn't available.
+    deliverBeacon(path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const payload = body ? JSON.stringify(body) : "{}";
+        try {
+            if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+                // Beacon requires Content-Type via the Blob constructor.
+                const blob = new Blob([payload], { type: "application/json" });
+                // Pass auth as a query string so beacon (which can't set headers) still authenticates.
+                const sep = url.includes("?") ? "&" : "?";
+                return navigator.sendBeacon(`${url}${sep}sdk_key=${encodeURIComponent(this.sdkKey)}`, blob);
+            }
+        } catch { /* fall through to fetch */ }
+        try {
+            fetch(url, {
+                method: "POST", headers: this._headers(), body: payload, keepalive: true,
+            }).catch(() => {});
+            return true;
+        } catch { return false; }
+    }
+}
+
+
+// ===== src/queue.js =====
+
+// Offline-first event queue. Events are persisted to storage as soon as
+// they're tracked so a tab crash or unload doesn't lose them. A flush
+// timer ships them as a batch; on failure the batch is requeued.
+//
+// The queue is intentionally simple: a single sorted list. For very
+// high volumes (>1k events/min) consider sharding by event kind.
+
+const QUEUE_KEY = "event_queue";
+    constructor({ storage, transport, logger, flushIntervalMs = 5_000, maxBatchSize = 50, onFlush }) {
+        this.storage = storage;
+        this.transport = transport;
+        this.logger = logger;
+        this.flushIntervalMs = flushIntervalMs;
+        this.maxBatchSize = maxBatchSize;
+        this.onFlush = onFlush || (() => {});
+        this.timer = null;
+        this.flushing = false;
+    }
+
+    start() {
+        if (this.timer) return;
+        this.timer = setInterval(() => this.flush().catch(() => {}), this.flushIntervalMs);
+        // Don't keep a node test process alive; this is a noop in browsers.
+        if (typeof this.timer.unref === "function") this.timer.unref();
+    }
+
+    stop() {
+        if (this.timer) clearInterval(this.timer);
+        this.timer = null;
+    }
+
+    enqueue(event) {
+        const list = this._read();
+        list.push(event);
+        this._write(list);
+        // Opportunistic flush so tiny apps don't wait for the timer.
+        if (list.length >= this.maxBatchSize) this.flush().catch(() => {});
+    }
+
+    size() { return this._read().length; }
+
+    async flush() {
+        if (this.flushing) return { ok: true, skipped: true };
+        const all = this._read();
+        if (all.length === 0) return { ok: true, count: 0 };
+
+        this.flushing = true;
+        try {
+            const batch = all.slice(0, this.maxBatchSize);
+            const remaining = all.slice(batch.length);
+
+            const res = await this.transport.request("/api/sdk/v1/events/batch", {
+                method: "POST",
+                body: { events: batch },
+            });
+
+            if (!res.ok && res.status !== 207) {
+                // Transport gave up after retries — keep the batch for later.
+                this.logger.warn("flush failed, will retry later", res.error || res.status);
+                return { ok: false, count: 0, error: res.error };
+            }
+
+            // 207 multi-status returns per-event success; we only drop the
+            // events the backend accepted, requeue the rest.
+            const accepted = new Set(
+                (res.data?.results || [])
+                    .filter((r) => r.ok)
+                    .map((r) => r.event_id)
+                    .filter(Boolean),
+            );
+            const rejectedFromBatch = batch.filter(
+                (e) => e.event_id && !accepted.has(e.event_id),
+            );
+
+            // If we have per-event ids, only requeue the rejected ones; if not,
+            // assume all succeeded on a 2xx response.
+            const requeue =
+                accepted.size > 0 || rejectedFromBatch.length > 0
+                    ? [...rejectedFromBatch.filter((e) => !accepted.has(e.event_id)), ...remaining]
+                    : remaining;
+
+            this._write(requeue);
+            this.onFlush({ sent: batch.length - rejectedFromBatch.length, queued: requeue.length });
+            return { ok: true, count: batch.length };
+        } finally {
+            this.flushing = false;
+        }
+    }
+
+    // Ship whatever is queued without retries — used on page unload.
+    flushBeacon() {
+        const all = this._read();
+        if (all.length === 0) return;
+        const ok = this.transport.deliverBeacon("/api/sdk/v1/events/batch", { events: all });
+        if (ok) this._write([]);
+    }
+
+    _read() { return this.storage.getJson(QUEUE_KEY, []) || []; }
+    _write(list) { this.storage.setJson(QUEUE_KEY, list); }
+}
+
+
+// ===== src/session.js =====
+
+
+const SESSION_KEY = "session";
+const DEFAULT_TIMEOUT_MS = 30 * 60_000; // 30 min idle = new session
+
+// Tracks the current logical session. A session ends when the tab has
+// been idle for longer than `timeoutMs` since the last tracked event,
+// or when `end()` is called explicitly. New sessions reuse the device
+// id but get a fresh session id.
+    constructor({ storage, transport, logger, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+        this.storage = storage;
+        this.transport = transport;
+        this.logger = logger;
+        this.timeoutMs = timeoutMs;
+    }
+
+    _read() { return this.storage.getJson(SESSION_KEY, null); }
+    _write(s) { this.storage.setJson(SESSION_KEY, s); }
+    _clear() { this.storage.remove(SESSION_KEY); }
+
+    // Returns the active session, starting a new one if none exists or
+    // the previous one has expired. Updates last-touch on every call.
+    touch({ utm, referrer } = {}) {
+        const now = Date.now();
+        const existing = this._read();
+        if (existing && now - existing.lastTouchedAt < this.timeoutMs) {
+            existing.lastTouchedAt = now;
+            this._write(existing);
+            return existing;
+        }
+        const fresh = {
+            id: uuid(),
+            startedAt: now,
+            lastTouchedAt: now,
+            isFirst: !existing,
+            utm: utm || {},
+            referrer: referrer || (isBrowser ? document.referrer || null : null),
+            serverId: null,
+        };
+        this._write(fresh);
+        return fresh;
+    }
+
+    current() { return this._read(); }
+
+    // Calls /sessions/start on the backend so we get a server-side
+    // session row. The local session id is replaced with the server's
+    // canonical id so subsequent event payloads can reference it.
+    async openServerSession({ device, externalUserId }) {
+        const session = this.touch();
+        if (session.serverId) return session;
+        const res = await this.transport.request("/api/sdk/v1/sessions/start", {
+            method: "POST",
+            body: {
+                device_id: device.device_id,
+                external_user_id: externalUserId || undefined,
+                referrer: session.referrer,
+                utm: session.utm,
+                started_at: nowIso(),
+            },
+        });
+        if (res.ok && res.data?.session?.id) {
+            session.serverId = res.data.session.id;
+            this._write(session);
+        }
+        return session;
+    }
+
+    async end() {
+        const session = this._read();
+        if (!session?.serverId) { this._clear(); return null; }
+        const duration = Date.now() - session.startedAt;
+        await this.transport.request("/api/sdk/v1/sessions/end", {
+            method: "POST",
+            body: { session_id: session.serverId, duration_ms: duration, ended_at: nowIso() },
+        }).catch(() => {});
+        this._clear();
+        return session;
+    }
+}
+
+
+// ===== src/identity.js =====
+
+const IDENTITY_KEY = "identity";
+
+// Identity manager — keeps the latest known user identity for this
+// device and pushes it to the backend on change.
+    constructor({ storage, transport, logger }) {
+        this.storage = storage;
+        this.transport = transport;
+        this.logger = logger;
+    }
+
+    current() { return this.storage.getJson(IDENTITY_KEY, null); }
+
+    // Idempotent identify call. The backend upserts; the client only
+    // POSTs when something has actually changed.
+    async identify({ externalUserId, email, phone, attributes }) {
+        if (!externalUserId) throw new Error("[nurdd] externalUserId is required to identify");
+        const existing = this.current();
+        const next = { externalUserId, email: email || null, phone: phone || null, attributes: attributes || {} };
+        const unchanged =
+            existing &&
+            existing.externalUserId === next.externalUserId &&
+            existing.email === next.email &&
+            existing.phone === next.phone;
+        this.storage.setJson(IDENTITY_KEY, next);
+        if (unchanged) return { ok: true, identity: existing, cached: true };
+
+        const res = await this.transport.request("/api/sdk/v1/identities", {
+            method: "POST",
+            body: {
+                external_user_id: externalUserId,
+                email: email || undefined,
+                phone: phone || undefined,
+                attributes: attributes || {},
+            },
+        });
+        return { ok: res.ok, identity: res.data?.identity || null };
+    }
+
+    // Clears the cached identity. Use on logout. Device id is unchanged
+    // so anonymous activity after logout remains stitched to this device.
+    reset() {
+        this.storage.remove(IDENTITY_KEY);
+    }
+
+    // Server-side merge for "logged-in user was previously this anonymous
+    // user" flows.
+    async merge({ primaryExternalUserId, secondaryExternalUserId }) {
+        return this.transport.request("/api/sdk/v1/identities/merge", {
+            method: "POST",
+            body: {
+                primary_external_user_id: primaryExternalUserId,
+                secondary_external_user_id: secondaryExternalUserId,
+            },
+        });
+    }
+}
+
+
+// ===== src/deeplinks.js =====
+
+
+// Deferred deep link resolver. On first launch / first SDK init, asks
+// the backend "did this device just click a short link that hasn't yet
+// been claimed?" If yes, the listener receives the deep link path and
+// the host app routes to it.
+//
+// Resolution sources, in priority order:
+//   1. UTM params on the current URL (short_code present) → server claim
+//   2. Fingerprint match via /links/deferred
+    constructor({ transport, logger }) {
+        this.transport = transport;
+        this.logger = logger;
+        this.listeners = new Set();
+        this.lastResolved = null;
+    }
+
+    onResolved(listener) {
+        this.listeners.add(listener);
+        // Fire late subscribers with the cached value so framework
+        // adapters don't miss the first resolution.
+        if (this.lastResolved) {
+            try { listener(this.lastResolved); } catch (e) { this.logger.warn("deep link listener threw", e); }
+        }
+        return () => this.listeners.delete(listener);
+    }
+
+    async resolve({ device }) {
+        const params = isBrowser ? readUtmFromLocation() : {};
+        let resolved = null;
+
+        if (params.short_code) {
+            const link = await this.transport.request(`/api/sdk/v1/links/${encodeURIComponent(params.short_code)}`);
+            if (link.ok && link.data?.link) {
+                resolved = {
+                    short_code: link.data.link.short_code,
+                    deep_link_path: link.data.link.deep_link_path || null,
+                    destination_url: link.data.link.destination_url || null,
+                    utm: link.data.link.utm || {},
+                    metadata: link.data.link.metadata || {},
+                    source: "url",
+                };
+            }
+        }
+
+        if (!resolved) {
+            const res = await this.transport.request("/api/sdk/v1/links/deferred", {
+                method: "POST",
+                body: {
+                    short_code: params.short_code || "__resolve__",
+                    platform: "web",
+                    device_id: device?.device_id,
+                },
+            });
+            if (res.ok && res.data?.deferred_deep_link) {
+                const d = res.data.deferred_deep_link;
+                resolved = {
+                    short_code: d.short_code,
+                    deep_link_path: d.deep_link_path,
+                    destination_url: null,
+                    utm: {},
+                    metadata: {},
+                    source: "deferred",
+                };
+            }
+        }
+
+        if (resolved) {
+            this.lastResolved = resolved;
+            for (const l of this.listeners) {
+                try { l(resolved); } catch (e) { this.logger.warn("deep link listener threw", e); }
+            }
+        }
+        return resolved;
+    }
+}
+
+
+// ===== src/autotrack.js =====
+
+
+// Wires up automatic event tracking that every framework benefits from:
+//
+//  - SPA page views: works for React Router, Vue Router, Next.js, Nuxt,
+//    Angular, Remix etc. by monkey-patching `history.pushState` and
+//    `history.replaceState` and listening to `popstate`.
+//  - Outbound clicks: any `<a>` whose href leaves the current origin.
+//  - Page unload: flush queued events via the beacon channel.
+//
+// All of this is opt-in via `config.autotrack`.
+    if (!isBrowser) return () => {};
+    const offFns = [];
+
+    if (config.autotrack.pageViews !== false) {
+        offFns.push(trackPageViews(sdk));
+    }
+    if (config.autotrack.outboundClicks) {
+        offFns.push(trackOutboundClicks(sdk));
+    }
+    if (config.autotrack.flushOnUnload !== false) {
+        offFns.push(flushOnUnload(queue));
+    }
+
+    return () => offFns.forEach((fn) => { try { fn(); } catch (e) { logger.warn(e); } });
+}
+
+function trackPageViews(sdk) {
+    const fire = () => {
+        sdk.track("page_view", {
+            url: window.location.href,
+            path: window.location.pathname,
+            search: window.location.search,
+            title: typeof document !== "undefined" ? document.title : null,
+            referrer: typeof document !== "undefined" ? document.referrer || null : null,
+        });
+    };
+    // Initial view.
+    fire();
+
+    const origPush = history.pushState;
+    const origReplace = history.replaceState;
+    history.pushState = function (...args) {
+        const r = origPush.apply(this, args);
+        queueMicrotask(fire);
+        return r;
+    };
+    history.replaceState = function (...args) {
+        const r = origReplace.apply(this, args);
+        queueMicrotask(fire);
+        return r;
+    };
+    window.addEventListener("popstate", fire);
+    return () => {
+        history.pushState = origPush;
+        history.replaceState = origReplace;
+        window.removeEventListener("popstate", fire);
+    };
+}
+
+function trackOutboundClicks(sdk) {
+    const handler = (e) => {
+        const a = e.target?.closest?.("a[href]");
+        if (!a) return;
+        let host = "";
+        try { host = new URL(a.href, window.location.href).host; } catch { return; }
+        if (!host || host === window.location.host) return;
+        sdk.track("outbound_click", { url: a.href, text: (a.textContent || "").trim().slice(0, 256) });
+    };
+    document.addEventListener("click", handler, { capture: true });
+    return () => document.removeEventListener("click", handler, { capture: true });
+}
+
+function flushOnUnload(queue) {
+    const handler = () => queue.flushBeacon();
+    // `pagehide` is preferred over `unload` (works on bfcache).
+    window.addEventListener("pagehide", handler);
+    window.addEventListener("beforeunload", handler);
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") queue.flushBeacon();
+    });
+    return () => {
+        window.removeEventListener("pagehide", handler);
+        window.removeEventListener("beforeunload", handler);
+    };
+}
+
+
+// ===== src/sdk.js =====
+
+
+const DEFAULTS = {
+    sdkKey: "",
+    baseUrl: "",
+    appVersion: null,
+    debug: false,
+    flushIntervalMs: 5_000,
+    maxBatchSize: 50,
+    sessionTimeoutMs: 30 * 60_000,
+    autotrack: {
+        pageViews: true,
+        outboundClicks: false,
+        flushOnUnload: true,
+    },
+    stripUtmFromUrl: true,
+};
+
+// Persisted campaign code attributed to this browser. Set when a Nurdd
+// link is resolved (from the URL or a deferred match) and stamped onto
+// later conversions so signups/purchases credit the original campaign.
+const ATTRIBUTED_SHORT_CODE_KEY = "attributed_short_code";
+
+// Framework-agnostic SDK. A single instance is enough for an entire
+// page / app — `getDefaultSdk()` is provided for the common case but
+// you can also keep multiple instances side by side (multi-tenant).
+    constructor(options = {}) {
+        this.config = mergeOptions(DEFAULTS, options);
+        if (!this.config.sdkKey) throw new Error("[nurdd] sdkKey is required");
+        if (!this.config.baseUrl) throw new Error("[nurdd] baseUrl is required");
+
+        this.logger = createLogger({ enabled: this.config.debug });
+        this.storage = createStorage({ prefix: `nurdd:${this.config.sdkKey}:` });
+        this.transport = new Transport({
+            baseUrl: this.config.baseUrl,
+            sdkKey: this.config.sdkKey,
+            logger: this.logger,
+        });
+
+        this.device = collectDevice({ storage: this.storage, appVersion: this.config.appVersion });
+        this.fingerprint = clientFingerprint(this.device);
+
+        this.queue = new EventQueue({
+            storage: this.storage,
+            transport: this.transport,
+            logger: this.logger,
+            flushIntervalMs: this.config.flushIntervalMs,
+            maxBatchSize: this.config.maxBatchSize,
+        });
+        this.session = new SessionManager({
+            storage: this.storage, transport: this.transport, logger: this.logger,
+            timeoutMs: this.config.sessionTimeoutMs,
+        });
+        this.identity = new IdentityManager({
+            storage: this.storage, transport: this.transport, logger: this.logger,
+        });
+        this.deepLinks = new DeepLinkResolver({ transport: this.transport, logger: this.logger });
+
+        this._initPromise = null;
+        this._teardownAutotrack = null;
+    }
+
+    // Idempotent. Safe to call multiple times — only does work once.
+    async init() {
+        if (this._initPromise) return this._initPromise;
+        this._initPromise = (async () => {
+            // The /init handshake gives the SDK clock-skew, supported
+            // platforms and feature flags. It's also a fast way to
+            // validate the SDK key before the first event flies.
+            const init = await this.transport.request("/api/sdk/v1/init", { method: "GET" });
+            if (!init.ok) {
+                this.logger.error("init failed", init.error || init.status);
+            }
+
+            // Capture session, UTM, referrer.
+            const utm = isBrowser ? readUtmFromLocation() : {};
+            const session = this.session.touch({ utm });
+            await this.session.openServerSession({
+                device: this.device,
+                externalUserId: this.identity.current()?.externalUserId,
+            }).catch(() => {});
+
+            // Persist the campaign code as soon as it's known — from the
+            // landing URL immediately, and again if a deferred match resolves
+            // — so conversions can attribute even after the URL is stripped.
+            if (utm.short_code) this.storage.setString(ATTRIBUTED_SHORT_CODE_KEY, utm.short_code);
+            this.deepLinks.onResolved((link) => {
+                if (link?.short_code) this.storage.setString(ATTRIBUTED_SHORT_CODE_KEY, link.short_code);
+            });
+
+            // Resolve deferred deep link in the background — listeners
+            // will be notified if anything matches.
+            this.deepLinks.resolve({ device: this.device }).catch(() => {});
+
+            // Strip UTM so a refresh doesn't double-count.
+            if (this.config.stripUtmFromUrl && isBrowser) stripUtmFromUrl();
+
+            this.queue.start();
+            this._teardownAutotrack = setupAutotrack({
+                sdk: this, config: this.config, queue: this.queue, logger: this.logger,
+            });
+
+            return { server: init.data, session };
+        })();
+        return this._initPromise;
+    }
+
+    // --- Public surface ----------------------------------------------------
+    // Every method is safe to call before `init()` resolves; events are
+    // queued locally and shipped once the queue's first flush ticks.
+
+    track(eventName, properties = {}, options = {}) {
+        if (!eventName) {
+            this.logger.warn("track() called without an event name");
+            return;
+        }
+        const session = this.session.touch();
+        const identity = this.identity.current();
+        const event = {
+            event_name: eventName,
+            event_id: options.eventId || uuid(),
+            occurred_at: options.occurredAt || nowIso(),
+            platform: "web",
+            sdk_version: SDK_VERSION,
+            app_version: this.config.appVersion,
+            session_id: session?.serverId || null,
+            properties,
+            device: this.device,
+            user: identity ? {
+                external_user_id: identity.externalUserId,
+                email: identity.email || undefined,
+                phone: identity.phone || undefined,
+                attributes: identity.attributes || {},
+            } : undefined,
+            revenue: typeof options.revenue === "number" ? options.revenue : undefined,
+            currency: options.currency || undefined,
+            attribution_lookup: options.attributionLookup || undefined,
+        };
+        this.queue.enqueue(event);
+        return event;
+    }
+
+    page(name, properties = {}) {
+        return this.track("page_view", { name: name || null, ...properties });
+    }
+
+    async identify(externalUserId, traits = {}) {
+        const result = await this.identity.identify({
+            externalUserId,
+            email: traits.email,
+            phone: traits.phone,
+            attributes: traits.attributes || {},
+        });
+        // Also push a server-side session row if we don't have one yet
+        // so the new identity is linked to today's session.
+        this.session.openServerSession({
+            device: this.device, externalUserId,
+        }).catch(() => {});
+        return result;
+    }
+
+    reset() { this.identity.reset(); }
+
+    async conversion(conversionType, payload = {}) {
+        // Auto-attribute to the campaign this browser came from unless the
+        // caller passed an explicit shortCode.
+        const shortCode = payload.shortCode || this.attributedShortCode() || undefined;
+        const res = await this.transport.request("/api/sdk/v1/conversions", {
+            method: "POST",
+            body: {
+                conversion_type: conversionType,
+                value: payload.value,
+                currency: payload.currency,
+                short_code: shortCode,
+                campaign_id: payload.campaignId,
+                attribution: payload.attribution,
+                fingerprint: this.fingerprint,
+            },
+        });
+        return res.data?.conversion || null;
+    }
+
+    // The campaign code attributed to this browser, if any.
+    attributedShortCode() {
+        return this.storage.getString(ATTRIBUTED_SHORT_CODE_KEY);
+    }
+
+    // Shopify helper. Writes the attributed campaign code into the cart as a
+    // cart attribute, so it travels with the order through checkout (where
+    // the SDK can't run) and can be read by your `orders/create` webhook to
+    // attribute the purchase. Storefront-only — call it on the cart/product
+    // page, e.g. right before "Add to cart" or on the cart page.
+    //
+    // A shopper can arrive via several campaigns before buying, so codes
+    // ACCUMULATE: the attribute holds a comma-separated, de-duplicated list
+    // in first-touch → last-touch order. The checkout pixel / webhook then
+    // decide which to credit.
+    async attachToShopifyCart({ attributeName = "nurdd_short_code" } = {}) {
+        if (!isBrowser) return false;
+        const shortCode = this.attributedShortCode();
+        if (!shortCode) return false;
+        try {
+            // Read any codes already on the cart so we append rather than
+            // overwrite previous campaigns.
+            let codes = [];
+            try {
+                const cartRes = await fetch("/cart.js", { headers: { Accept: "application/json" } });
+                if (cartRes.ok) {
+                    const cart = await cartRes.json();
+                    const raw = cart.attributes && cart.attributes[attributeName];
+                    if (raw) codes = String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+                }
+            } catch {
+                // No cart yet / read failed — start a fresh list.
+            }
+
+            if (codes.includes(shortCode)) return true; // already recorded
+            codes.push(shortCode);
+
+            const res = await fetch("/cart/update.js", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ attributes: { [attributeName]: codes.join(",") } }),
+            });
+            if (!res.ok) this.logger.warn("attachToShopifyCart: cart update failed", res.status);
+            return res.ok;
+        } catch (e) {
+            this.logger.warn("attachToShopifyCart failed", e);
+            return false;
+        }
+    }
+
+    async click({ shortCode, campaignId, kind = "click", metadata } = {}) {
+        const res = await this.transport.request("/api/sdk/v1/clicks", {
+            method: "POST",
+            body: {
+                short_code: shortCode,
+                campaign_id: campaignId,
+                kind, metadata,
+                platform: "web",
+            },
+        });
+        return res.data?.click || null;
+    }
+
+    // Short-link helpers
+    async createShortLink(payload) {
+        const res = await this.transport.request("/api/sdk/v1/links", {
+            method: "POST",
+            body: payload,
+        });
+        return res.data?.link || null;
+    }
+
+    async resolveShortLink(code) {
+        const res = await this.transport.request(`/api/sdk/v1/links/${encodeURIComponent(code)}`);
+        return res.data?.link || null;
+    }
+
+    // Deferred deep link API — listen for resolutions from anywhere
+    // in the app. Returns an unsubscribe function.
+    onDeepLink(listener) { return this.deepLinks.onResolved(listener); }
+
+    // Referrals
+    async issueReferralCode(payload) {
+        const res = await this.transport.request("/api/sdk/v1/referrals/codes", {
+            method: "POST", body: payload,
+        });
+        return res.data?.referral_code || null;
+    }
+
+    async recordReferral(payload) {
+        const res = await this.transport.request("/api/sdk/v1/referrals", {
+            method: "POST", body: payload,
+        });
+        return res.data?.referral || null;
+    }
+
+    // Lifecycle
+    async flush() { return this.queue.flush(); }
+
+    async endSession() { return this.session.end(); }
+
+    destroy() {
+        this.queue.stop();
+        if (typeof this._teardownAutotrack === "function") this._teardownAutotrack();
+        this._teardownAutotrack = null;
+        this._initPromise = null;
+    }
+
+    // Diagnostics
+    info() {
+        return {
+            sdkVersion: SDK_VERSION,
+            device: this.device,
+            fingerprint: this.fingerprint,
+            session: this.session.current(),
+            identity: this.identity.current(),
+            queueSize: this.queue.size(),
+        };
+    }
+}
+
+// Singleton convenience for the most common case — one SDK per page.
+let defaultInstance = null;
+    return new NurddSdk(options);
+}
+    if (defaultInstance) return defaultInstance;
+    defaultInstance = new NurddSdk(options);
+    defaultInstance.init().catch((e) => defaultInstance.logger.error("init failed", e));
+    return defaultInstance;
+}
+    if (!defaultInstance) {
+        throw new Error("[nurdd] SDK has not been initialised. Call initSdk({ sdkKey, baseUrl }) first.");
+    }
+    return defaultInstance;
+}
+    defaultInstance = instance;
+    return defaultInstance;
+}
+
+
+// ===== src/index.js =====
+
+// Public entry point — what consumers see by default.
+
+return {
+    NurddSdk: NurddSdk,
+    createSdk: createSdk,
+    initSdk: initSdk,
+    getSdk: getSdk,
+    hasDefaultSdk: hasDefaultSdk,
+    setDefaultSdk: setDefaultSdk,
+    SDK_VERSION: SDK_VERSION,
+    SDK_NAME: SDK_NAME,
+    isBrowser: isBrowser,
+    UTM_KEYS: UTM_KEYS,
+};
+});