@nurdd/web-sdk 1.0.0

package/src/transport.js

@@ -0,0 +1,105 @@
+// 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]);
+
+export class Transport {
+    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; }
+    }
+}

package/src/utils.js

@@ -0,0 +1,56 @@
+// Tiny helpers used across the SDK. No dependencies on env so they're
+// safe to import from SSR contexts.
+
+export function uuid() {
+    // 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)}`;
+}
+
+export function nowIso() { return new Date().toISOString(); }
+
+export function safeJsonParse(value, fallback = null) {
+    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.
+export function fnv1a(str) {
+    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");
+}
+
+export function clamp(n, min, max) { return Math.max(min, Math.min(max, n)); }
+
+export function debounce(fn, wait) {
+    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).
+export function mergeOptions(defaults, overrides) {
+    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;
+}

package/src/utm.js

@@ -0,0 +1,46 @@
+import { isBrowser } from "./env.js";
+
+export 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.
+export function readUtmFromLocation() {
+    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.
+export function stripUtmFromUrl() {
+    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 */ }
+}

package/types/angular.d.ts

@@ -0,0 +1,30 @@
+import type { InjectionToken } from "@angular/core";
+import type {
+    NurddSdk,
+    SdkConfig,
+    IdentityTraits,
+    TrackOptions,
+    ConversionPayload,
+    ClickPayload,
+    DeepLinkResolution,
+} from "./index";
+
+export const NURDD_SDK: InjectionToken<NurddSdk>;
+
+export class NurddService {
+    sdk: NurddSdk;
+    constructor(sdk: NurddSdk);
+    track(event: string, properties?: Record<string, unknown>, options?: TrackOptions): unknown;
+    page(name?: string, properties?: Record<string, unknown>): unknown;
+    identify(externalUserId: string, traits?: IdentityTraits): Promise<unknown>;
+    reset(): void;
+    conversion(type: string, payload?: ConversionPayload): Promise<unknown>;
+    click(payload?: ClickPayload): Promise<unknown>;
+    onDeepLink(listener: (payload: DeepLinkResolution) => void): () => void;
+    flush(): Promise<unknown>;
+    raw(): NurddSdk;
+}
+
+export function provideNurdd(config: SdkConfig): unknown[];
+
+export { createSdk, initSdk, getSdk, setDefaultSdk } from "./index";

package/types/index.d.ts

@@ -0,0 +1,172 @@
+// TypeScript declarations for @nurdd/web-sdk.
+
+export const SDK_VERSION: string;
+export const SDK_NAME: string;
+export const isBrowser: boolean;
+export const UTM_KEYS: readonly string[];
+
+export type Platform = "web" | "android" | "ios" | "flutter" | "react_native" | "server" | "unknown";
+
+export interface SdkConfig {
+    /** Public SDK key issued by your backend (POST /api/sdk/v1/apps). */
+    sdkKey: string;
+    /** Origin of your attribution backend, e.g. https://api.example.com */
+    baseUrl: string;
+    /** Optional app version forwarded with every event. */
+    appVersion?: string | null;
+    /** Enables verbose console logging. */
+    debug?: boolean;
+    /** Background flush interval for the offline event queue. */
+    flushIntervalMs?: number;
+    /** Max events per batched POST. */
+    maxBatchSize?: number;
+    /** Idle session timeout in ms (default: 30min). */
+    sessionTimeoutMs?: number;
+    /** Auto-tracking toggles. */
+    autotrack?: {
+        pageViews?: boolean;
+        outboundClicks?: boolean;
+        flushOnUnload?: boolean;
+    };
+    /** Strip UTM params from the URL after the first read (default: true). */
+    stripUtmFromUrl?: boolean;
+}
+
+export interface DeviceInfo {
+    device_id: string;
+    platform: Platform;
+    os_name?: string | null;
+    os_version?: string | null;
+    model?: string | null;
+    manufacturer?: string | null;
+    app_version?: string | null;
+    sdk_version?: string;
+    locale?: string | null;
+    timezone?: string | null;
+    attributes?: Record<string, unknown>;
+}
+
+export interface IdentityTraits {
+    email?: string;
+    phone?: string;
+    attributes?: Record<string, unknown>;
+}
+
+export interface Identity {
+    externalUserId: string;
+    email?: string | null;
+    phone?: string | null;
+    attributes?: Record<string, unknown>;
+}
+
+export interface TrackOptions {
+    eventId?: string;
+    occurredAt?: string;
+    revenue?: number;
+    currency?: string;
+    attributionLookup?: boolean;
+}
+
+export interface Session {
+    id: string;
+    startedAt: number;
+    lastTouchedAt: number;
+    isFirst: boolean;
+    utm: Record<string, string>;
+    referrer: string | null;
+    serverId: string | null;
+}
+
+export interface ConversionPayload {
+    value?: number;
+    currency?: string;
+    shortCode?: string;
+    campaignId?: string;
+    attribution?: Record<string, unknown>;
+}
+
+export interface ClickPayload {
+    shortCode?: string;
+    campaignId?: string;
+    kind?: "click" | "impression";
+    metadata?: Record<string, unknown>;
+}
+
+export interface DeepLinkResolution {
+    short_code: string;
+    deep_link_path: string | null;
+    destination_url: string | null;
+    utm: Record<string, string>;
+    metadata: Record<string, unknown>;
+    source: "url" | "deferred";
+}
+
+export interface ShortLinkPayload {
+    destination_url: string;
+    short_code?: string;
+    campaign_id?: string;
+    ios_url?: string;
+    android_url?: string;
+    web_url?: string;
+    fallback_url?: string;
+    deep_link_path?: string;
+    utm?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+    expires_at?: string;
+}
+
+export interface ReferralCodePayload {
+    owner_identity_id: string;
+    destination_url?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface ReferralRecordPayload {
+    code: string;
+    referred_device_uuid?: string;
+    referred_identity_id?: string;
+}
+
+export interface FlushResult {
+    ok: boolean;
+    count?: number;
+    error?: string;
+    skipped?: boolean;
+}
+
+export interface SdkInfo {
+    sdkVersion: string;
+    device: DeviceInfo;
+    fingerprint: string;
+    session: Session | null;
+    identity: Identity | null;
+    queueSize: number;
+}
+
+export class NurddSdk {
+    constructor(options: SdkConfig);
+    readonly device: DeviceInfo;
+    readonly fingerprint: string;
+    init(): Promise<{ server: unknown; session: Session }>;
+    track(eventName: string, properties?: Record<string, unknown>, options?: TrackOptions): unknown;
+    page(name?: string, properties?: Record<string, unknown>): unknown;
+    identify(externalUserId: string, traits?: IdentityTraits): Promise<{ ok: boolean; identity: Identity | null; cached?: boolean }>;
+    reset(): void;
+    conversion(conversionType: string, payload?: ConversionPayload): Promise<unknown>;
+    click(payload?: ClickPayload): Promise<unknown>;
+    createShortLink(payload: ShortLinkPayload): Promise<unknown>;
+    resolveShortLink(code: string): Promise<unknown>;
+    onDeepLink(listener: (payload: DeepLinkResolution) => void): () => void;
+    issueReferralCode(payload: ReferralCodePayload): Promise<unknown>;
+    recordReferral(payload: ReferralRecordPayload): Promise<unknown>;
+    flush(): Promise<FlushResult>;
+    endSession(): Promise<Session | null>;
+    destroy(): void;
+    info(): SdkInfo;
+}
+
+export function createSdk(options: SdkConfig): NurddSdk;
+export function initSdk(options: SdkConfig): NurddSdk;
+export function getSdk(): NurddSdk;
+export function hasDefaultSdk(): boolean;
+export function setDefaultSdk(instance: NurddSdk): NurddSdk;

package/types/next.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+
+export interface NurddPageViewProps {
+    pathname: string;
+    searchParams?: { toString(): string } | null;
+    properties?: Record<string, unknown>;
+}
+
+export function NurddPageView(props: NurddPageViewProps): JSX.Element | null;
+export * from "./react";

package/types/nuxt.d.ts

@@ -0,0 +1,5 @@
+// Nuxt plugin default export. Nuxt expects a function returned by
+// `defineNuxtPlugin`; the runtime accepts any signature.
+declare const plugin: unknown;
+export default plugin;
+export * from "./vue";

package/types/react.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type {
+    NurddSdk,
+    SdkConfig,
+    Identity,
+    IdentityTraits,
+    TrackOptions,
+    DeepLinkResolution,
+} from "./index";
+
+export interface NurddProviderProps {
+    config?: SdkConfig;
+    sdk?: NurddSdk;
+    children?: ReactNode;
+}
+
+export function NurddProvider(props: NurddProviderProps): JSX.Element;
+export function useNurdd(): NurddSdk;
+export function useTrack(): (event: string, properties?: Record<string, unknown>, options?: TrackOptions) => unknown;
+export function usePageView(path: string | null | undefined, properties?: Record<string, unknown>): void;
+export function useDeepLink(callback: (payload: DeepLinkResolution) => void): void;
+export function useIdentity(): {
+    identity: Identity | null;
+    identify: (externalUserId: string, traits?: IdentityTraits) => Promise<unknown>;
+    reset: () => void;
+};
+
+export { createSdk, initSdk, getSdk, setDefaultSdk } from "./index";

package/types/vue.d.ts

@@ -0,0 +1,21 @@
+import type { App, Ref } from "vue";
+import type { NurddSdk, SdkConfig, Identity, IdentityTraits, DeepLinkResolution } from "./index";
+
+export interface NurddPluginOptions extends Partial<SdkConfig> {
+    config?: SdkConfig;
+    sdk?: NurddSdk;
+    sdkKey?: string;
+    baseUrl?: string;
+}
+
+export const NurddPlugin: { install(app: App, options: NurddPluginOptions): void };
+export function useNurdd(): NurddSdk;
+export function trackPageViews(routeRef: Ref<{ fullPath?: string; path?: string; name?: unknown; params?: unknown; query?: unknown }>): void;
+export function useDeepLink(callback: (payload: DeepLinkResolution) => void): void;
+export function useIdentity(): {
+    identity: Ref<Identity | null>;
+    identify: (externalUserId: string, traits?: IdentityTraits) => Promise<unknown>;
+    reset: () => void;
+};
+
+export { createSdk, initSdk, getSdk, setDefaultSdk } from "./index";