@nurdd/web-sdk 1.0.0

package/src/identity.js

@@ -0,0 +1,57 @@
+const IDENTITY_KEY = "identity";
+
+// Identity manager — keeps the latest known user identity for this
+// device and pushes it to the backend on change.
+export class IdentityManager {
+    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,
+            },
+        });
+    }
+}

package/src/index.js

@@ -0,0 +1,12 @@
+// Public entry point — what consumers see by default.
+export {
+    NurddSdk,
+    createSdk,
+    initSdk,
+    getSdk,
+    hasDefaultSdk,
+    setDefaultSdk,
+} from "./sdk.js";
+
+export { SDK_VERSION, SDK_NAME, isBrowser } from "./env.js";
+export { UTM_KEYS } from "./utm.js";

package/src/logger.js

@@ -0,0 +1,12 @@
+// Minimal, level-gated logger. `debug` defaults to OFF so the SDK is
+// silent in production unless the host explicitly opts in.
+export function createLogger({ enabled = false, prefix = "[nurdd]" } = {}) {
+    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,
+    };
+}

package/src/queue.js

@@ -0,0 +1,102 @@
+// 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";
+
+export class EventQueue {
+    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); }
+}

package/src/sdk.js

@@ -0,0 +1,342 @@
+import { createLogger } from "./logger.js";
+import { createStorage } from "./storage.js";
+import { Transport } from "./transport.js";
+import { EventQueue } from "./queue.js";
+import { SessionManager } from "./session.js";
+import { IdentityManager } from "./identity.js";
+import { DeepLinkResolver } from "./deeplinks.js";
+import { setupAutotrack } from "./autotrack.js";
+import { collectDevice, clientFingerprint } from "./device.js";
+import { readUtmFromLocation, stripUtmFromUrl } from "./utm.js";
+import { isBrowser, SDK_VERSION } from "./env.js";
+import { uuid, nowIso, mergeOptions } from "./utils.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).
+export class NurddSdk {
+    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;
+
+export function createSdk(options) {
+    return new NurddSdk(options);
+}
+
+export function initSdk(options) {
+    if (defaultInstance) return defaultInstance;
+    defaultInstance = new NurddSdk(options);
+    defaultInstance.init().catch((e) => defaultInstance.logger.error("init failed", e));
+    return defaultInstance;
+}
+
+export function getSdk() {
+    if (!defaultInstance) {
+        throw new Error("[nurdd] SDK has not been initialised. Call initSdk({ sdkKey, baseUrl }) first.");
+    }
+    return defaultInstance;
+}
+
+export function hasDefaultSdk() { return Boolean(defaultInstance); }
+
+export function setDefaultSdk(instance) {
+    defaultInstance = instance;
+    return defaultInstance;
+}

package/src/session.js

@@ -0,0 +1,83 @@
+import { nowIso, uuid } from "./utils.js";
+import { isBrowser } from "./env.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.
+
+export class SessionManager {
+    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;
+    }
+}

package/src/storage.js

@@ -0,0 +1,48 @@
+import { hasLocalStorage, isBrowser } from "./env.js";
+import { safeJsonParse } from "./utils.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 */ }
+    }
+}
+
+export function createStorage({ prefix = "nurdd:" } = {}) {
+    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,
+    };
+}