@cross-deck/web 0.6.0 → 0.10.0

package/dist/index.mjs

@@ -7,11 +7,13 @@ var CrossdeckError = class _CrossdeckError extends Error {
     this.code = payload.code;
     this.requestId = payload.requestId;
     this.status = payload.status;
+    this.retryAfterMs = payload.retryAfterMs;
     Object.setPrototypeOf(this, _CrossdeckError.prototype);
   }
 };
 async function crossdeckErrorFromResponse(res) {
   const requestId = res.headers.get("x-request-id") ?? void 0;
+  const retryAfterMs = parseRetryAfterHeader(res.headers.get("retry-after"));
   let body;
   try {
     body = await res.json();
@@ -25,7 +27,8 @@ async function crossdeckErrorFromResponse(res) {
       code: envelope.code,
       message: envelope.message ?? `HTTP ${res.status}`,
       requestId: envelope.request_id ?? requestId,
-      status: res.status
+      status: res.status,
+      retryAfterMs
     });
   }
   return new CrossdeckError({
@@ -33,9 +36,25 @@ async function crossdeckErrorFromResponse(res) {
     code: `http_${res.status}`,
     message: `HTTP ${res.status} ${res.statusText || ""}`.trim(),
     requestId,
-    status: res.status
+    status: res.status,
+    retryAfterMs
   });
 }
+function parseRetryAfterHeader(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const secs = Number(trimmed);
+    if (!Number.isFinite(secs) || secs < 0) return void 0;
+    return Math.round(secs * 1e3);
+  }
+  if (!/[a-zA-Z,/:]/.test(trimmed)) return void 0;
+  const target = Date.parse(trimmed);
+  if (!Number.isFinite(target)) return void 0;
+  const delta = target - Date.now();
+  return delta > 0 ? delta : 0;
+}
 function typeMapForStatus(status) {
   if (status === 401) return "authentication_error";
   if (status === 403) return "permission_error";
@@ -46,8 +65,9 @@ function typeMapForStatus(status) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/web";
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.10.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+var DEFAULT_TIMEOUT_MS = 15e3;
 var HttpClient = class {
   constructor(config) {
     this.config = config;
@@ -62,31 +82,47 @@ var HttpClient = class {
    *   - JSON parse failure on a 2xx (treated as `internal_error`)
    */
   async request(method, path, options = {}) {
+    if (this.config.localDevMode) {
+      return synthesizeLocalDevResponse(path);
+    }
     const url = this.buildUrl(path, options.query);
     const headers = {
       Authorization: `Bearer ${this.config.publicKey}`,
       "Crossdeck-Sdk-Version": `${SDK_NAME}@${this.config.sdkVersion}`,
       Accept: "application/json"
     };
+    if (options.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
     let bodyInit;
     if (options.body !== void 0) {
       headers["Content-Type"] = "application/json";
       bodyInit = JSON.stringify(options.body);
     }
+    const effectiveTimeout = options.timeoutMs ?? this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = typeof AbortController !== "undefined" && effectiveTimeout > 0 ? new AbortController() : null;
+    let timeoutHandle = null;
+    if (controller && effectiveTimeout > 0) {
+      timeoutHandle = setTimeout(() => controller.abort(), effectiveTimeout);
+    }
     let response;
     try {
       response = await fetch(url, {
         method,
         headers,
         body: bodyInit,
-        keepalive: options.keepalive === true
+        keepalive: options.keepalive === true,
+        signal: controller?.signal
       });
     } catch (err) {
+      const aborted = controller?.signal?.aborted === true;
       throw new CrossdeckError({
         type: "network_error",
-        code: "fetch_failed",
-        message: err instanceof Error ? err.message : "fetch failed"
+        code: aborted ? "request_timeout" : "fetch_failed",
+        message: aborted ? `Request to ${path} aborted after ${effectiveTimeout}ms` : err instanceof Error ? err.message : "fetch failed"
       });
+    } finally {
+      if (timeoutHandle !== null) clearTimeout(timeoutHandle);
     }
     if (!response.ok) {
       throw await crossdeckErrorFromResponse(response);
@@ -104,6 +140,14 @@ var HttpClient = class {
       });
     }
   }
+  /**
+   * Whether this client is in localhost dev-mode short-circuit. Used
+   * by other SDK pieces (event-queue) to skip network-bound work
+   * entirely rather than going through synthesizeLocalDevResponse.
+   */
+  get isLocalDevMode() {
+    return this.config.localDevMode === true;
+  }
   buildUrl(path, query) {
     const base = this.config.baseUrl.replace(/\/+$/, "");
     const cleanPath = path.startsWith("/") ? path : `/${path}`;
@@ -119,6 +163,49 @@ var HttpClient = class {
     return url;
   }
 };
+var cachedLocalCdcust = null;
+function synthesizeLocalDevResponse(path) {
+  if (path.startsWith("/sdk/heartbeat")) {
+    return {
+      object: "heartbeat",
+      ok: true,
+      projectId: "proj_local_dev",
+      appId: "app_local_dev",
+      platform: "web",
+      env: "sandbox",
+      serverTime: Date.now()
+    };
+  }
+  if (path.startsWith("/identity/alias")) {
+    if (!cachedLocalCdcust) {
+      const tail = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID().replace(/-/g, "").slice(0, 16) : Math.random().toString(36).slice(2, 18);
+      cachedLocalCdcust = `cdcust_local_${tail}`;
+    }
+    return {
+      object: "alias_result",
+      crossdeckCustomerId: cachedLocalCdcust,
+      linked: [],
+      mergePending: false,
+      env: "sandbox"
+    };
+  }
+  if (path.startsWith("/entitlements")) {
+    return {
+      object: "list",
+      data: [],
+      crossdeckCustomerId: cachedLocalCdcust ?? "",
+      env: "sandbox"
+    };
+  }
+  if (path.startsWith("/events")) {
+    return {
+      object: "list",
+      received: 0,
+      env: "sandbox"
+    };
+  }
+  return {};
+}
 
 // src/identity.ts
 var KEY_ANON = "anon_id";
@@ -232,6 +319,7 @@ var EntitlementCache = class {
     this.all = [];
     this.lastUpdated = 0;
     this.listeners = /* @__PURE__ */ new Set();
+    this.listenerErrorCount = 0;
   }
   /** Sync read — true iff the entitlement key is currently active. */
   isEntitled(key) {
@@ -245,6 +333,15 @@ var EntitlementCache = class {
   get freshness() {
     return this.lastUpdated;
   }
+  /**
+   * Cumulative count of listener invocations that threw. Listener errors
+   * are swallowed (a buggy consumer must not crash the SDK) but the
+   * counter lets diagnostics() surface "you have a broken subscriber"
+   * without putting the developer in a debug session.
+   */
+  get listenerErrors() {
+    return this.listenerErrorCount;
+  }
   /**
    * Replace the cache with a fresh server response. The backend already
    * filters to active + env-matching, so we don't re-filter — just trust
@@ -298,11 +395,54 @@ var EntitlementCache = class {
       try {
         listener(snapshot);
       } catch {
+        this.listenerErrorCount += 1;
       }
     }
   }
 };
 
+// src/retry-policy.ts
+var DEFAULT_BASE = 1e3;
+var DEFAULT_MAX = 6e4;
+var DEFAULT_FACTOR = 2;
+var DEFAULT_WARN = 8;
+function computeNextDelay(attempts, retryAfterMs, options = {}, random = Math.random) {
+  const base = options.baseMs ?? DEFAULT_BASE;
+  const max = options.maxMs ?? DEFAULT_MAX;
+  const factor = options.factor ?? DEFAULT_FACTOR;
+  const safeAttempts = Math.min(attempts, 30);
+  const ceiling = Math.min(max, base * Math.pow(factor, safeAttempts));
+  const jittered = ceiling * random();
+  if (retryAfterMs !== void 0 && retryAfterMs > jittered) {
+    return Math.min(max, retryAfterMs);
+  }
+  return Math.max(0, Math.round(jittered));
+}
+var RetryPolicy = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.attempts = 0;
+  }
+  /** How many consecutive failures since the last success. */
+  get consecutiveFailures() {
+    return this.attempts;
+  }
+  /** Whether we've crossed the failuresBeforeWarn threshold. */
+  get isWarning() {
+    return this.attempts >= (this.options.failuresBeforeWarn ?? DEFAULT_WARN);
+  }
+  /** Schedule-time delay for the NEXT retry. Increments the counter. */
+  nextDelay(retryAfterMs, random = Math.random) {
+    const delay = computeNextDelay(this.attempts, retryAfterMs, this.options, random);
+    this.attempts += 1;
+    return delay;
+  }
+  /** Mark a successful flush — reset the counter. */
+  recordSuccess() {
+    this.attempts = 0;
+  }
+};
+
 // src/event-queue.ts
 var HARD_BUFFER_CAP = 1e3;
 var EventQueue = class {
@@ -315,6 +455,22 @@ var EventQueue = class {
     this.lastError = null;
     this.cancelTimer = null;
     this.firstFlushFired = false;
+    this.nextRetryAt = null;
+    this.retry = new RetryPolicy(cfg.retry ?? {});
+    this.persistent = cfg.persistentStore ?? null;
+    if (this.persistent) {
+      const restored = this.persistent.load();
+      if (restored.length > 0) {
+        if (restored.length > HARD_BUFFER_CAP) {
+          this.dropped += restored.length - HARD_BUFFER_CAP;
+          this.buffer = restored.slice(restored.length - HARD_BUFFER_CAP);
+        } else {
+          this.buffer = restored;
+        }
+        this.cfg.onBufferChange?.(this.buffer.length);
+        this.scheduleIdleFlush();
+      }
+    }
   }
   enqueue(event) {
     this.buffer.push(event);
@@ -324,6 +480,8 @@ var EventQueue = class {
       this.dropped += overflow;
       this.cfg.onDrop?.(overflow);
     }
+    this.cfg.onBufferChange?.(this.buffer.length);
+    this.persistent?.save(this.buffer);
     if (this.buffer.length >= this.cfg.batchSize) {
       void this.flush();
     } else {
@@ -333,7 +491,7 @@ var EventQueue = class {
   /**
    * Flush the buffer to /v1/events. Resolves when the network call
    * completes (success or failure). On failure, events stay in the
-   * buffer for the next flush attempt.
+   * buffer for the next scheduled retry.
    *
    * `options.keepalive` marks the underlying fetch as keepalive so the
    * browser keeps the request alive past page unload. Use this for
@@ -342,25 +500,32 @@ var EventQueue = class {
   async flush(options = {}) {
     if (this.buffer.length === 0) return null;
     this.cancelTimerIfSet();
+    this.nextRetryAt = null;
     const batch = this.buffer.splice(0);
+    const batchId = this.mintBatchId();
     this.inFlight += batch.length;
+    this.persistent?.save(this.buffer);
+    this.cfg.onBufferChange?.(this.buffer.length);
     try {
       const env = this.cfg.envelope();
       const result = await this.cfg.http.request("POST", "/events", {
         body: {
           // NorthStar §13.1 batch envelope. The backend validates these
-          // against the API-key-resolved app and rejects mismatches loudly
-          // (env_mismatch).
+          // against the API-key-resolved app and rejects mismatches
+          // loudly (env_mismatch).
           appId: env.appId,
           environment: env.environment,
           sdk: env.sdk,
           events: batch
         },
-        keepalive: options.keepalive === true
+        keepalive: options.keepalive === true,
+        idempotencyKey: batchId
       });
       this.lastFlushAt = Date.now();
       this.lastError = null;
       this.inFlight -= batch.length;
+      this.retry.recordSuccess();
+      this.persistent?.save(this.buffer);
       if (!this.firstFlushFired) {
         this.firstFlushFired = true;
         this.cfg.onFirstFlushSuccess?.();
@@ -369,18 +534,33 @@ var EventQueue = class {
     } catch (err) {
       this.buffer.unshift(...batch);
       this.inFlight -= batch.length;
-      this.lastError = err instanceof Error ? err.message : String(err);
-      this.scheduleIdleFlush();
+      const message = err instanceof Error ? err.message : String(err);
+      this.lastError = message;
+      this.persistent?.save(this.buffer);
+      this.cfg.onBufferChange?.(this.buffer.length);
+      const retryAfterMs = extractRetryAfterMs(err);
+      const delay = this.retry.nextDelay(retryAfterMs);
+      this.scheduleRetry(delay);
+      this.cfg.onRetryScheduled?.({
+        delayMs: delay,
+        consecutiveFailures: this.retry.consecutiveFailures,
+        retryAfterMs,
+        lastError: message
+      });
       return null;
     }
   }
-  /** Cancel any pending timer and clear in-memory state. */
+  /** Cancel any pending timer and clear in-memory state. Wipes durable store too. */
   reset() {
     this.cancelTimerIfSet();
+    this.nextRetryAt = null;
     this.buffer = [];
     this.dropped = 0;
     this.inFlight = 0;
     this.lastError = null;
+    this.retry.recordSuccess();
+    this.persistent?.clear();
+    this.cfg.onBufferChange?.(0);
   }
   getStats() {
     return {
@@ -388,9 +568,12 @@ var EventQueue = class {
       dropped: this.dropped,
       inFlight: this.inFlight,
       lastFlushAt: this.lastFlushAt,
-      lastError: this.lastError
+      lastError: this.lastError,
+      consecutiveFailures: this.retry.consecutiveFailures,
+      nextRetryAt: this.nextRetryAt
     };
   }
+  // ---------- internal scheduling ----------
   scheduleIdleFlush() {
     this.cancelTimerIfSet();
     const sched = this.cfg.scheduler ?? defaultScheduler;
@@ -398,13 +581,31 @@ var EventQueue = class {
       void this.flush();
     }, this.cfg.intervalMs);
   }
+  scheduleRetry(delayMs) {
+    this.cancelTimerIfSet();
+    this.nextRetryAt = Date.now() + delayMs;
+    const sched = this.cfg.scheduler ?? defaultScheduler;
+    this.cancelTimer = sched(() => {
+      void this.flush();
+    }, delayMs);
+  }
   cancelTimerIfSet() {
     if (this.cancelTimer) {
       this.cancelTimer();
       this.cancelTimer = null;
     }
   }
+  mintBatchId() {
+    return `batch_${Date.now().toString(36)}${randomChars(10)}`;
+  }
 };
+function extractRetryAfterMs(err) {
+  if (err && typeof err === "object" && "retryAfterMs" in err) {
+    const v = err.retryAfterMs;
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : void 0;
+  }
+  return void 0;
+}
 function defaultScheduler(fn, ms) {
   const id = setTimeout(fn, ms);
   if (typeof id.unref === "function") {
@@ -416,6 +617,87 @@ function defaultScheduler(fn, ms) {
   return () => clearTimeout(id);
 }
 
+// src/event-storage.ts
+var PersistentEventStore = class {
+  constructor(options) {
+    this.options = options;
+    this.writeScheduled = false;
+    // Pending events captured on the most recent write request. We keep
+    // the latest snapshot ref so a debounced write always picks up the
+    // freshest buffer state.
+    this.pendingSnapshot = null;
+    this.key = `${options.prefix}queue.v1`;
+  }
+  /**
+   * Read the persisted queue on boot. Returns an empty array (with no
+   * warning) when nothing is stored, the blob is malformed, or storage
+   * is unavailable. Caller is responsible for treating duplicates from
+   * the persisted queue as the SAME events (eventId-based dedup).
+   */
+  load() {
+    let raw;
+    try {
+      raw = this.options.storage.getItem(this.key);
+    } catch {
+      return [];
+    }
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.events)) {
+        return [];
+      }
+      return parsed.events;
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Schedule a write of the current buffer. Debounced via microtask so
+   * a burst of enqueue() calls coalesces into one persistence write.
+   * Writes are best-effort: if storage throws (quota, private mode),
+   * we swallow and rely on the in-memory buffer.
+   */
+  save(snapshot) {
+    this.pendingSnapshot = snapshot.slice();
+    if (this.writeScheduled) return;
+    this.writeScheduled = true;
+    queueMicrotask(() => this.flushWrite());
+  }
+  /** Synchronous variant for terminal flushes (pagehide / beforeunload). */
+  saveSync(snapshot) {
+    this.pendingSnapshot = snapshot.slice();
+    this.flushWrite();
+  }
+  /** Wipe the persisted blob. Used by reset() (logout). */
+  clear() {
+    this.pendingSnapshot = null;
+    this.writeScheduled = false;
+    try {
+      this.options.storage.removeItem(this.key);
+    } catch {
+    }
+  }
+  flushWrite() {
+    this.writeScheduled = false;
+    const snapshot = this.pendingSnapshot;
+    this.pendingSnapshot = null;
+    if (snapshot === null) return;
+    if (snapshot.length === 0) {
+      try {
+        this.options.storage.removeItem(this.key);
+      } catch {
+      }
+      return;
+    }
+    const blob = { version: 1, events: snapshot };
+    try {
+      this.options.storage.setItem(this.key, JSON.stringify(blob));
+    } catch {
+    }
+  }
+};
+
 // src/storage.ts
 var MemoryStorage = class {
   constructor() {
@@ -605,7 +887,9 @@ function parseUserAgent(ua) {
 var DEFAULT_AUTO_TRACK = {
   sessions: true,
   pageViews: true,
-  deviceInfo: true
+  deviceInfo: true,
+  clicks: true,
+  webVitals: true
 };
 var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
 var EMPTY_ACQUISITION = {
@@ -614,7 +898,13 @@ var EMPTY_ACQUISITION = {
   utm_campaign: "",
   utm_content: "",
   utm_term: "",
-  referrer: ""
+  referrer: "",
+  gclid: "",
+  fbclid: "",
+  msclkid: "",
+  ttclid: "",
+  li_fat_id: "",
+  twclid: ""
 };
 var AutoTracker = class {
   constructor(cfg, track) {
@@ -622,11 +912,23 @@ var AutoTracker = class {
     this.track = track;
     this.session = null;
     this.cleanups = [];
+    /**
+     * Stable per-page-view identifier. Minted at every `page.viewed`
+     * emission and attached to every subsequent event until the next
+     * `page.viewed`. Lets dashboards correlate "user clicked X" to
+     * "user viewed page Y" without timestamp arithmetic — the canonical
+     * Mixpanel `$current_url` / Segment `pageId` pattern.
+     *
+     * Null until the first `page.viewed` fires (which happens at SDK
+     * install if `autoTrack.pageViews !== false`).
+     */
+    this.pageviewId = null;
   }
   install() {
     if (!isBrowserSafe()) return;
     if (this.cfg.sessions) this.installSessionTracking();
     if (this.cfg.pageViews) this.installPageViewTracking();
+    if (this.cfg.clicks) this.installClickTracking();
   }
   uninstall() {
     while (this.cleanups.length) {
@@ -651,6 +953,10 @@ var AutoTracker = class {
   get currentSessionId() {
     return this.session?.sessionId ?? null;
   }
+  /** Stable per-page-view ID. Null before the first page.viewed has fired. */
+  get currentPageviewId() {
+    return this.pageviewId;
+  }
   /**
    * Per-session acquisition context — utm_* + referrer, captured once
    * at session start. Returns empty strings when there's no session
@@ -721,11 +1027,21 @@ var AutoTracker = class {
   installPageViewTracking() {
     const w = globalThis.window;
     const doc = globalThis.document;
-    const fire = () => {
+    let lastFiredAt = 0;
+    let lastFiredUrl = "";
+    const DEDUP_WINDOW_MS = 250;
+    const fire = (force = false) => {
       const loc = w.location;
+      const url = loc.href;
+      const now = Date.now();
+      if (!force && url === lastFiredUrl && now - lastFiredAt < DEDUP_WINDOW_MS) return;
+      lastFiredAt = now;
+      lastFiredUrl = url;
+      this.pageviewId = `pv_${Date.now().toString(36)}${randomChars(10)}`;
       this.track("page.viewed", {
+        pageviewId: this.pageviewId,
         path: loc.pathname,
-        url: loc.href,
+        url,
         search: loc.search || void 0,
         hash: loc.hash || void 0,
         title: doc.title,
@@ -747,7 +1063,7 @@ var AutoTracker = class {
     }
     w.history.pushState = patchedPush;
     w.history.replaceState = patchedReplace;
-    const onPopState = () => fire();
+    const onPopState = () => fire(true);
     w.addEventListener("popstate", onPopState);
     this.cleanups.push(() => {
       if (w.history.pushState === patchedPush) {
@@ -759,7 +1075,156 @@ var AutoTracker = class {
       w.removeEventListener("popstate", onPopState);
     });
   }
+  // ---------- click autocapture ----------
+  /**
+   * Global click tracking — Mixpanel / Amplitude style autocapture.
+   * Fires `element.clicked` for every interactive click with the
+   * target element's selector path, text content, tag, href, data-*
+   * attributes, and viewport coordinates. Powers the funnel /
+   * attribution USP: "users who clicked X then converted within
+   * 7 days." Default ON because behavioural attribution is the
+   * core product promise.
+   *
+   * Privacy guardrails:
+   *   - Skip clicks ON inputs / textareas / selects (form interaction
+   *     isn't button telemetry; the dev should track form submits
+   *     deliberately via track('form_submitted'))
+   *   - Skip clicks INSIDE [type="password"] and password-class
+   *     elements
+   *   - Skip clicks inside elements opted out via class="cd-noTrack"
+   *     or data-cd-noTrack attribute (Mixpanel's exact opt-out
+   *     idiom — most devs already know it)
+   *   - Capture text content but cap at 64 chars and trim — never
+   *     more than what you'd see on a button label
+   *
+   * Volume guardrails:
+   *   - Coalesce double-clicks within 100ms (React's synthetic click
+   *     pattern + browser's native dblclick can fire twice)
+   *   - Listen on document at capture phase so we see the click
+   *     before any framework's own handlers stop propagation
+   */
+  installClickTracking() {
+    const w = globalThis.window;
+    const doc = globalThis.document;
+    let lastFiredAt = 0;
+    let lastFiredTarget = null;
+    const COALESCE_MS = 100;
+    const TEXT_CAP = 64;
+    const onClick = (ev) => {
+      const target = ev.target;
+      if (!target || !(target instanceof Element)) return;
+      const now = Date.now();
+      if (target === lastFiredTarget && now - lastFiredAt < COALESCE_MS) return;
+      lastFiredAt = now;
+      lastFiredTarget = target;
+      const actionable = closestActionable(target);
+      const clicked = actionable || target;
+      if (isFormInput(clicked)) return;
+      if (isInOptedOut(clicked)) return;
+      if (isInsidePasswordField(clicked)) return;
+      const tag = clicked.tagName.toLowerCase();
+      const text = trimText(extractText(clicked), TEXT_CAP);
+      const href = clicked.href || void 0;
+      const linkTarget = clicked.target || void 0;
+      const elementId = clicked.id || void 0;
+      const role = clicked.getAttribute("role") || void 0;
+      const ariaLabel = clicked.getAttribute("aria-label") || void 0;
+      const selector = buildSelector(clicked);
+      const dataAttrs = collectDataAttrs(clicked);
+      const isLink = tag === "a" && !!href;
+      const explicitName = clicked.getAttribute("data-cd-event");
+      const props = {
+        selector,
+        tag,
+        text,
+        elementId,
+        role,
+        ariaLabel,
+        href,
+        isLink,
+        linkTarget,
+        viewportX: ev.clientX,
+        viewportY: ev.clientY,
+        pageX: ev.pageX,
+        pageY: ev.pageY,
+        ...dataAttrs
+      };
+      for (const k of Object.keys(props)) {
+        if (props[k] === void 0 || props[k] === null || props[k] === "") delete props[k];
+      }
+      this.track(explicitName || "element.clicked", props);
+    };
+    doc.addEventListener("click", onClick, { capture: true, passive: true });
+    this.cleanups.push(() => {
+      doc.removeEventListener("click", onClick, { capture: true });
+    });
+  }
 };
+function closestActionable(el) {
+  return el.closest("[data-cd-event]") || el.closest("[data-cd-noTrack]") || el.closest("button, a, [role='button'], [role='link'], input[type='button'], input[type='submit']") || null;
+}
+function isFormInput(el) {
+  if (!(el instanceof HTMLElement)) return false;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "textarea" || tag === "select") return true;
+  if (tag === "input") {
+    const type = (el.type || "").toLowerCase();
+    return type !== "button" && type !== "submit" && type !== "image" && type !== "reset";
+  }
+  return false;
+}
+function isInOptedOut(el) {
+  if (el.closest("[data-cd-noTrack], [data-cd-no-track], .cd-noTrack, .cd-no-track")) return true;
+  return false;
+}
+function isInsidePasswordField(el) {
+  if (el.closest('input[type="password"]')) return true;
+  return false;
+}
+function extractText(el) {
+  const aria = el.getAttribute("aria-label");
+  if (aria) return aria.replace(/\s+/g, " ").trim();
+  if (el instanceof HTMLInputElement && el.value) return el.value;
+  const text = (el.textContent || "").replace(/\s+/g, " ").trim();
+  return text;
+}
+function trimText(s, cap) {
+  if (s.length <= cap) return s;
+  return s.slice(0, cap - 1) + "\u2026";
+}
+function buildSelector(el) {
+  const parts = [];
+  let cur = el;
+  let depth = 0;
+  while (cur && cur.nodeName.toLowerCase() !== "body" && depth < 5) {
+    let part = cur.nodeName.toLowerCase();
+    if (cur.id) {
+      parts.unshift(`${part}#${cur.id}`);
+      break;
+    }
+    if (cur.classList.length > 0) {
+      const cls = Array.from(cur.classList).filter((c) => !c.startsWith("cd-")).slice(0, 2).join(".");
+      if (cls) part += `.${cls}`;
+    }
+    parts.unshift(part);
+    cur = cur.parentElement;
+    depth++;
+  }
+  return parts.join(" > ");
+}
+function collectDataAttrs(el) {
+  const out = {};
+  if (!(el instanceof HTMLElement)) return out;
+  for (const name of el.getAttributeNames()) {
+    if (!name.startsWith("data-")) continue;
+    if (name === "data-cd-noTrack" || name === "data-cd-no-track") continue;
+    if (name === "data-cd-event") continue;
+    const value = el.getAttribute(name) || "";
+    const key = name.replace(/^data-cd-prop-/, "").replace(/^data-/, "");
+    out[key] = value;
+  }
+  return out;
+}
 function isBrowserSafe() {
   return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
 }
@@ -778,6 +1243,12 @@ function captureAcquisition() {
     result.utm_campaign = params.get("utm_campaign") ?? "";
     result.utm_content = params.get("utm_content") ?? "";
     result.utm_term = params.get("utm_term") ?? "";
+    result.gclid = params.get("gclid") ?? "";
+    result.fbclid = params.get("fbclid") ?? "";
+    result.msclkid = params.get("msclkid") ?? "";
+    result.ttclid = params.get("ttclid") ?? "";
+    result.li_fat_id = params.get("li_fat_id") ?? "";
+    result.twclid = params.get("twclid") ?? "";
   } catch {
   }
   try {
@@ -835,6 +1306,490 @@ function safeJson(obj) {
   }
 }
 
+// src/event-validation.ts
+var DEFAULT_MAX_STRING = 1024;
+var DEFAULT_MAX_BYTES = 8 * 1024;
+var DEFAULT_MAX_DEPTH = 5;
+function validateEventProperties(input, options = {}) {
+  const warnings = [];
+  if (!input) return { properties: {}, warnings };
+  const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING;
+  const maxBatchPropertyBytes = options.maxBatchPropertyBytes ?? DEFAULT_MAX_BYTES;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const seen = /* @__PURE__ */ new WeakSet();
+  const visit = (value, key, depth) => {
+    if (depth > maxDepth) {
+      warnings.push({ kind: "depth_exceeded", key });
+      return { keep: true, value: "[depth-exceeded]" };
+    }
+    if (value === null) return { keep: true, value: null };
+    const t = typeof value;
+    if (t === "string") {
+      const s = value;
+      if (s.length > maxStringLength) {
+        warnings.push({ kind: "truncated_string", key });
+        return { keep: true, value: s.slice(0, maxStringLength - 1) + "\u2026" };
+      }
+      return { keep: true, value: s };
+    }
+    if (t === "number") {
+      if (!Number.isFinite(value)) {
+        warnings.push({ kind: "non_serialisable", key });
+        return { keep: true, value: null };
+      }
+      return { keep: true, value };
+    }
+    if (t === "boolean") return { keep: true, value };
+    if (t === "bigint") {
+      warnings.push({ kind: "coerced_bigint", key });
+      return { keep: true, value: value.toString() };
+    }
+    if (t === "function") {
+      warnings.push({ kind: "dropped_function", key });
+      return { keep: false, value: void 0 };
+    }
+    if (t === "symbol") {
+      warnings.push({ kind: "dropped_symbol", key });
+      return { keep: false, value: void 0 };
+    }
+    if (t === "undefined") {
+      warnings.push({ kind: "dropped_undefined", key });
+      return { keep: false, value: void 0 };
+    }
+    if (value instanceof Date) {
+      warnings.push({ kind: "coerced_date", key });
+      const iso = Number.isFinite(value.getTime()) ? value.toISOString() : null;
+      return { keep: true, value: iso };
+    }
+    if (value instanceof Error) {
+      warnings.push({ kind: "coerced_error", key });
+      return {
+        keep: true,
+        value: {
+          name: value.name,
+          message: value.message,
+          stack: typeof value.stack === "string" ? value.stack.slice(0, maxStringLength) : void 0
+        }
+      };
+    }
+    if (value instanceof Map) {
+      warnings.push({ kind: "coerced_map", key });
+      const obj = {};
+      for (const [k, v] of value.entries()) {
+        const subKey = typeof k === "string" ? k : String(k);
+        const result = visit(v, `${key}.${subKey}`, depth + 1);
+        if (result.keep) obj[subKey] = result.value;
+      }
+      return { keep: true, value: obj };
+    }
+    if (value instanceof Set) {
+      warnings.push({ kind: "coerced_set", key });
+      const arr = [];
+      let i = 0;
+      for (const v of value.values()) {
+        const result = visit(v, `${key}[${i}]`, depth + 1);
+        if (result.keep) arr.push(result.value);
+        i++;
+      }
+      return { keep: true, value: arr };
+    }
+    if (Array.isArray(value)) {
+      if (seen.has(value)) {
+        warnings.push({ kind: "circular_reference", key });
+        return { keep: true, value: "[circular]" };
+      }
+      seen.add(value);
+      const out = [];
+      for (let i = 0; i < value.length; i++) {
+        const result = visit(value[i], `${key}[${i}]`, depth + 1);
+        if (result.keep) out.push(result.value);
+      }
+      return { keep: true, value: out };
+    }
+    if (t === "object") {
+      const obj = value;
+      if (seen.has(obj)) {
+        warnings.push({ kind: "circular_reference", key });
+        return { keep: true, value: "[circular]" };
+      }
+      seen.add(obj);
+      const out = {};
+      for (const k of Object.keys(obj)) {
+        const result = visit(obj[k], `${key}.${k}`, depth + 1);
+        if (result.keep) out[k] = result.value;
+      }
+      return { keep: true, value: out };
+    }
+    warnings.push({ kind: "non_serialisable", key });
+    try {
+      return { keep: true, value: String(value) };
+    } catch {
+      return { keep: false, value: void 0 };
+    }
+  };
+  const cleaned = {};
+  for (const k of Object.keys(input)) {
+    const result = visit(input[k], k, 0);
+    if (result.keep) cleaned[k] = result.value;
+  }
+  const serialised = safeStringify(cleaned);
+  if (serialised && byteLength(serialised) > maxBatchPropertyBytes) {
+    warnings.push({ kind: "size_cap_exceeded", key: "*" });
+    const sizes = Object.keys(cleaned).map((k) => ({ k, size: byteLength(safeStringify(cleaned[k]) ?? "") })).sort((a, b) => b.size - a.size);
+    let currentSize = byteLength(serialised);
+    for (const { k } of sizes) {
+      if (currentSize <= maxBatchPropertyBytes) break;
+      currentSize -= sizes.find((s) => s.k === k).size;
+      delete cleaned[k];
+    }
+    cleaned.__truncated = true;
+  }
+  return { properties: cleaned, warnings };
+}
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v) ?? null;
+  } catch {
+    return null;
+  }
+}
+function byteLength(s) {
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(s).length;
+  }
+  return s.length * 4;
+}
+
+// src/super-properties.ts
+var KEY_SUPER = "super_props";
+var KEY_GROUPS = "groups";
+var SuperPropertyStore = class {
+  constructor(storage, prefix) {
+    this.storage = storage;
+    this.prefix = prefix;
+    this.superProps = {};
+    this.groups = {};
+    this.superProps = readJson(storage, prefix + KEY_SUPER) ?? {};
+    this.groups = readJson(storage, prefix + KEY_GROUPS) ?? {};
+  }
+  // ---------- super properties ----------
+  /**
+   * Merge new keys into the super-property bag. Returns a snapshot of
+   * the resulting bag. Values that are `null` are deleted (Mixpanel
+   * semantics — explicit null = "stop tracking this key").
+   */
+  register(props) {
+    for (const [k, v] of Object.entries(props)) {
+      if (v === null) {
+        delete this.superProps[k];
+      } else if (v !== void 0) {
+        this.superProps[k] = v;
+      }
+    }
+    writeJson(this.storage, this.prefix + KEY_SUPER, this.superProps);
+    return { ...this.superProps };
+  }
+  /** Remove a single super-property key. Idempotent. */
+  unregister(key) {
+    if (key in this.superProps) {
+      delete this.superProps[key];
+      writeJson(this.storage, this.prefix + KEY_SUPER, this.superProps);
+    }
+  }
+  /** Snapshot of the current super-property bag. */
+  getSuperProperties() {
+    return { ...this.superProps };
+  }
+  // ---------- groups ----------
+  /**
+   * Set a group membership. Passing `id: null` clears the membership
+   * for that group type — the SDK stops attaching it to events.
+   */
+  setGroup(type, id, traits) {
+    if (id === null) {
+      delete this.groups[type];
+    } else {
+      this.groups[type] = traits !== void 0 ? { id, traits } : { id };
+    }
+    writeJson(this.storage, this.prefix + KEY_GROUPS, this.groups);
+  }
+  /**
+   * Snapshot of the current groups map, keyed by group type. Returned
+   * shape mirrors what the SDK attaches to every event as
+   * `$groups.{type}`. The `traits` sub-object is the most-recent
+   * traits payload passed to `setGroup` for that type; null when none.
+   */
+  getGroups() {
+    return JSON.parse(JSON.stringify(this.groups));
+  }
+  /**
+   * The flat `{ type: id }` projection used for event-attachment. Stable
+   * for fast every-event merge — we don't want to JSON-clone on each
+   * track() call.
+   */
+  getGroupIds() {
+    const out = {};
+    for (const [type, info] of Object.entries(this.groups)) {
+      out[type] = info.id;
+    }
+    return out;
+  }
+  /** Wipe both bags. Called by Crossdeck.reset() (logout). */
+  clear() {
+    this.superProps = {};
+    this.groups = {};
+    try {
+      this.storage.removeItem(this.prefix + KEY_SUPER);
+    } catch {
+    }
+    try {
+      this.storage.removeItem(this.prefix + KEY_GROUPS);
+    } catch {
+    }
+  }
+};
+function readJson(storage, key) {
+  let raw;
+  try {
+    raw = storage.getItem(key);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function writeJson(storage, key, value) {
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+
+// src/web-vitals.ts
+var WebVitalsTracker = class {
+  constructor(cfg, report) {
+    this.cfg = cfg;
+    this.report = report;
+    this.observers = [];
+    this.flushed = /* @__PURE__ */ new Set();
+    this.cls = 0;
+    this.clsEntries = [];
+    this.inp = 0;
+    this.cleanups = [];
+  }
+  install() {
+    if (!this.cfg.enabled) return;
+    if (typeof PerformanceObserver === "undefined") return;
+    if (typeof globalThis === "undefined" || !("document" in globalThis)) return;
+    const doc = globalThis.document;
+    try {
+      const navObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          const e = entry;
+          if (e.responseStart > 0 && !this.flushed.has("ttfb")) {
+            this.flushed.add("ttfb");
+            this.report("webvitals.ttfb", { valueMs: Math.round(e.responseStart - e.startTime) });
+          }
+        }
+      });
+      navObserver.observe({ type: "navigation", buffered: true });
+      this.observers.push(navObserver);
+    } catch {
+    }
+    try {
+      const paintObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (entry.name === "first-contentful-paint" && !this.flushed.has("fcp")) {
+            this.flushed.add("fcp");
+            this.report("webvitals.fcp", { valueMs: Math.round(entry.startTime) });
+          }
+        }
+      });
+      paintObserver.observe({ type: "paint", buffered: true });
+      this.observers.push(paintObserver);
+    } catch {
+    }
+    let lcpValue = 0;
+    try {
+      const lcpObserver = new PerformanceObserver((list) => {
+        const entries = list.getEntries();
+        const last = entries[entries.length - 1];
+        if (last) lcpValue = last.startTime;
+      });
+      lcpObserver.observe({ type: "largest-contentful-paint", buffered: true });
+      this.observers.push(lcpObserver);
+    } catch {
+    }
+    try {
+      const clsObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          const e = entry;
+          if (typeof e.value === "number" && !e.hadRecentInput) {
+            this.cls += e.value;
+            this.clsEntries.push(entry);
+          }
+        }
+      });
+      clsObserver.observe({ type: "layout-shift", buffered: true });
+      this.observers.push(clsObserver);
+    } catch {
+    }
+    try {
+      const eventObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          const e = entry;
+          if (e.interactionId && e.duration > this.inp) {
+            this.inp = e.duration;
+          }
+        }
+      });
+      try {
+        eventObserver.observe({ type: "event", buffered: true, durationThreshold: 16 });
+      } catch {
+        eventObserver.observe({ type: "first-input", buffered: true });
+      }
+      this.observers.push(eventObserver);
+    } catch {
+    }
+    const flush = () => {
+      if (lcpValue > 0 && !this.flushed.has("lcp")) {
+        this.flushed.add("lcp");
+        this.report("webvitals.lcp", { valueMs: Math.round(lcpValue) });
+      }
+      if (this.cls > 0 && !this.flushed.has("cls")) {
+        this.flushed.add("cls");
+        this.report("webvitals.cls", { value: Math.round(this.cls * 1e3) / 1e3 });
+      }
+      if (this.inp > 0 && !this.flushed.has("inp")) {
+        this.flushed.add("inp");
+        this.report("webvitals.inp", { valueMs: Math.round(this.inp) });
+      }
+    };
+    const onHidden = () => {
+      if (doc.visibilityState === "hidden") flush();
+    };
+    doc.addEventListener("visibilitychange", onHidden);
+    globalThis.window.addEventListener("pagehide", flush);
+    this.cleanups.push(() => {
+      doc.removeEventListener("visibilitychange", onHidden);
+      globalThis.window.removeEventListener("pagehide", flush);
+    });
+  }
+  uninstall() {
+    for (const o of this.observers) {
+      try {
+        o.disconnect();
+      } catch {
+      }
+    }
+    this.observers = [];
+    for (const fn of this.cleanups.splice(0)) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+  }
+};
+
+// src/consent.ts
+var ALL_GRANTED = {
+  analytics: true,
+  marketing: true,
+  errors: true
+};
+var ConsentManager = class {
+  constructor(options) {
+    this.state = { ...ALL_GRANTED };
+    this.dntDenied = false;
+    if (options?.respectDnt && this.detectDnt()) {
+      this.dntDenied = true;
+      this.state = { analytics: false, marketing: false, errors: false };
+    }
+  }
+  /**
+   * Merge new dimensions onto the current state. Returns the resulting
+   * snapshot. DNT-derived denies cannot be flipped back on by a `set`
+   * call — once the browser says "don't track", we don't track even if
+   * the developer code disagrees. That's the contract.
+   */
+  set(partial) {
+    if (this.dntDenied) return { ...this.state };
+    for (const k of Object.keys(partial)) {
+      const v = partial[k];
+      if (typeof v === "boolean") this.state[k] = v;
+    }
+    return { ...this.state };
+  }
+  /** Snapshot of the current state. */
+  get() {
+    return { ...this.state };
+  }
+  /** Convenience getters for hot paths. */
+  get analytics() {
+    return this.state.analytics;
+  }
+  get marketing() {
+    return this.state.marketing;
+  }
+  get errors() {
+    return this.state.errors;
+  }
+  /** True iff the constructor detected and applied DNT. */
+  get isDntDenied() {
+    return this.dntDenied;
+  }
+  detectDnt() {
+    try {
+      const nav = globalThis.navigator;
+      if (!nav) return false;
+      const sources = [
+        nav.doNotTrack,
+        nav.msDoNotTrack,
+        globalThis.doNotTrack
+      ];
+      return sources.some((v) => v === "1" || v === "yes");
+    } catch {
+      return false;
+    }
+  }
+};
+var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+var CARD_PATTERN = /\b\d(?:[ -]?\d){12,18}\b/g;
+var REPLACEMENT_EMAIL = "[email]";
+var REPLACEMENT_CARD = "[card]";
+function scrubPii(value) {
+  if (!value) return value;
+  let out = value;
+  if (EMAIL_PATTERN.test(out)) {
+    out = out.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL);
+  }
+  EMAIL_PATTERN.lastIndex = 0;
+  if (CARD_PATTERN.test(out)) {
+    out = out.replace(CARD_PATTERN, REPLACEMENT_CARD);
+  }
+  CARD_PATTERN.lastIndex = 0;
+  return out;
+}
+function scrubPiiFromProperties(properties) {
+  const out = {};
+  for (const k of Object.keys(properties)) {
+    const v = properties[k];
+    if (typeof v === "string") {
+      out[k] = scrubPii(v);
+    } else if (Array.isArray(v)) {
+      out[k] = v.map((item) => typeof item === "string" ? scrubPii(item) : item);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
 // src/crossdeck.ts
 var CrossdeckClient = class {
   constructor() {
@@ -879,6 +1834,7 @@ var CrossdeckClient = class {
         message: `Crossdeck.init: environment "${options.environment}" disagrees with key prefix (${keyEnv}). Reconcile the publishable key with the environment declaration.`
       });
     }
+    const localDevMode = isLocalHostname();
     const storage = options.storage ?? detectDefaultStorage();
     const persistIdentity = options.persistIdentity ?? true;
     const autoTrack = resolveAutoTrack(options.autoTrack);
@@ -905,14 +1861,31 @@ var CrossdeckClient = class {
     const http = new HttpClient({
       publicKey: opts.publicKey,
       baseUrl: opts.baseUrl,
-      sdkVersion: opts.sdkVersion
+      sdkVersion: opts.sdkVersion,
+      // Localhost auto-route: HttpClient short-circuits every request
+      // to a successful no-op response when localDevMode is set.
+      // SDK methods continue to work locally; nothing reaches the
+      // server.
+      localDevMode
     });
+    if (localDevMode) {
+      console.log(
+        "[crossdeck] Localhost detected \u2014 running in dev mode (no network calls). Set publicKey: 'cd_pub_test_\u2026' and deploy to a real domain to test against the Crossdeck Sandbox."
+      );
+    }
     const effectiveStorage = persistIdentity ? storage : new MemoryStorage();
     const useCookieRedundancy = persistIdentity && !options.storage && // honour caller's adapter choice
     typeof globalThis.document !== "undefined";
     const cookieStore = useCookieRedundancy ? new CookieStorage() : void 0;
     const identity = new IdentityStore(effectiveStorage, opts.storagePrefix, cookieStore);
     const entitlements = new EntitlementCache();
+    const persistentEvents = persistIdentity ? new PersistentEventStore({ storage: effectiveStorage, prefix: opts.storagePrefix }) : null;
+    if (persistentEvents) {
+      debug.emit(
+        "sdk.queue_restored",
+        "Restored persisted event queue from a prior session."
+      );
+    }
     const events = new EventQueue({
       http,
       batchSize: opts.eventFlushBatchSize,
@@ -922,26 +1895,51 @@ var CrossdeckClient = class {
         environment: opts.environment,
         sdk: { name: SDK_NAME, version: opts.sdkVersion }
       }),
+      persistentStore: persistentEvents ?? void 0,
       onFirstFlushSuccess: () => {
         debug.emit(
           "sdk.first_event_sent",
           "First telemetry event received. View it in Live Events.",
           { appId: opts.appId, environment: opts.environment }
         );
+      },
+      onRetryScheduled: (info) => {
+        debug.emit(
+          "sdk.flush_retry_scheduled",
+          `Event flush failed (${info.lastError}). Retrying in ${info.delayMs}ms (attempt ${info.consecutiveFailures}).`,
+          { ...info }
+        );
       }
     });
     const deviceInfo = autoTrack.deviceInfo ? collectDeviceInfo({ appVersion: opts.appVersion ?? void 0 }) : opts.appVersion ? { appVersion: opts.appVersion } : {};
+    const superProps = new SuperPropertyStore(
+      persistIdentity ? effectiveStorage : new MemoryStorage(),
+      opts.storagePrefix
+    );
+    const consent = new ConsentManager({ respectDnt: options.respectDnt === true });
+    if (consent.isDntDenied) {
+      debug.emit(
+        "sdk.consent_dnt_applied",
+        "Do Not Track detected \u2014 all tracking dimensions denied at init."
+      );
+    }
     this.state = {
       http,
       identity,
       entitlements,
       events,
       autoTracker: null,
+      webVitals: null,
+      superProps,
+      consent,
+      scrubPii: options.scrubPii !== false,
       deviceInfo,
       options: opts,
       debug,
       developerUserId: null,
-      uninstallUnloadFlush: null
+      uninstallUnloadFlush: null,
+      lastServerTime: null,
+      lastClientTime: null
     };
     debug.emit("sdk.configured", `Crossdeck connected to ${opts.appId} in ${opts.environment} mode.`, {
       appId: opts.appId,
@@ -956,10 +1954,18 @@ var CrossdeckClient = class {
       this.state.autoTracker = tracker;
       tracker.install();
     }
+    if (autoTrack.webVitals) {
+      const vitals = new WebVitalsTracker(
+        { enabled: true },
+        (name, properties) => this.track(name, properties)
+      );
+      this.state.webVitals = vitals;
+      vitals.install();
+    }
     this.state.uninstallUnloadFlush = installUnloadFlush(() => {
       void this.flush({ keepalive: true }).catch(() => void 0);
     });
-    if (opts.autoHeartbeat) {
+    if (opts.autoHeartbeat && !localDevMode) {
       void this.heartbeat().catch(() => void 0);
     }
   }
@@ -979,8 +1985,19 @@ var CrossdeckClient = class {
   /**
    * Link the anonymous device to a developer-supplied user ID. Cache
    * the resolved Crossdeck customer for follow-up calls.
+   *
+   * v0.9.0+ accepts an optional `traits` bag — profile data (name,
+   * plan, signupDate, role) persisted on the Crossdeck customer record
+   * and queryable from dashboards. Traits are sanitised through the
+   * same validator that gates `track()` properties, so a `{ avatar:
+   * <File>, onSave: () => {} }` payload can't corrupt the alias call.
+   *
+   *   Crossdeck.identify("user_847", {
+   *     email: "wes@pinet.co.za",
+   *     traits: { name: "Wes", plan: "pro", signedUpAt: "2026-05-11" },
+   *   });
    */
-  async identify(userId, _options) {
+  async identify(userId, options) {
     const s = this.requireStarted();
     if (!userId) {
       throw new CrossdeckError({
@@ -989,13 +2006,163 @@ var CrossdeckClient = class {
         message: "identify(userId) requires a non-empty userId."
       });
     }
+    if (!s.consent.analytics) {
+      s.debug.emit(
+        "sdk.consent_denied",
+        `identify() skipped \u2014 consent denied for analytics.`
+      );
+      return {
+        object: "alias_result",
+        crossdeckCustomerId: s.identity.crossdeckCustomerId ?? "",
+        linked: [],
+        mergePending: false,
+        env: s.options.environment
+      };
+    }
+    const traitsValidation = options?.traits !== void 0 ? validateEventProperties(options.traits) : null;
+    const traits = traitsValidation && Object.keys(traitsValidation.properties).length > 0 ? traitsValidation.properties : void 0;
+    if (s.debug.enabled && traitsValidation && traitsValidation.warnings.length > 0) {
+      for (const w of traitsValidation.warnings) {
+        s.debug.emit(
+          "sdk.property_coerced",
+          `identify() traits key ${JSON.stringify(w.key)} was ${w.kind.replace(/_/g, " ")} during validation.`,
+          { key: w.key, kind: w.kind }
+        );
+      }
+    }
+    const body = {
+      userId,
+      anonymousId: s.identity.anonymousId
+    };
+    if (options?.email) body.email = options.email;
+    if (traits) body.traits = traits;
     const result = await s.http.request("POST", "/identity/alias", {
-      body: { userId, anonymousId: s.identity.anonymousId }
+      body
     });
     s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
     s.developerUserId = userId;
     return result;
   }
+  /**
+   * Register super-properties — Mixpanel pattern. Once set, every
+   * subsequent event of THIS SDK instance carries these keys on its
+   * properties bag automatically.
+   *
+   *   Crossdeck.register({ plan: "pro", releaseChannel: "beta" });
+   *   Crossdeck.track("paywall_shown");  // includes plan + releaseChannel
+   *
+   * Values that are `null` are deleted (the explicit "stop tracking
+   * this key" idiom). Returns the resulting bag.
+   *
+   * Sanitised through `validateEventProperties` so a `{ avatar: File }`
+   * payload can't poison the queue at flush time.
+   */
+  register(properties) {
+    const s = this.requireStarted();
+    const validation = validateEventProperties(properties);
+    return s.superProps.register(validation.properties);
+  }
+  /** Remove a single super-property key. Idempotent. */
+  unregister(key) {
+    const s = this.requireStarted();
+    s.superProps.unregister(key);
+  }
+  /** Snapshot of the current super-property bag. */
+  getSuperProperties() {
+    if (!this.state) return {};
+    return this.state.superProps.getSuperProperties();
+  }
+  /**
+   * Associate the current user with a group (org, team, account, etc.).
+   * Mixpanel / Segment "Group Analytics" pattern.
+   *
+   *   Crossdeck.group("org", "acme_inc");
+   *   Crossdeck.group("team", "design", { headcount: 12 });
+   *
+   * Once set, every subsequent event carries `$groups.<type>: id` on
+   * its properties bag, enabling B2B dashboards ("how is Acme using
+   * the product"). Pass `id: null` to clear a group membership.
+   */
+  group(type, id, traits) {
+    const s = this.requireStarted();
+    if (!type) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_group_type",
+        message: "group(type, id) requires a non-empty type."
+      });
+    }
+    const sanitisedTraits = traits ? validateEventProperties(traits).properties : void 0;
+    s.superProps.setGroup(type, id, sanitisedTraits);
+  }
+  /** Snapshot of the current groups map keyed by type. */
+  getGroups() {
+    if (!this.state) return {};
+    return this.state.superProps.getGroups();
+  }
+  /**
+   * Update consent state. Three independent dimensions:
+   *
+   *   analytics  — track() + identify() + auto-emissions
+   *   marketing  — paid-traffic click IDs + referrer URL on events
+   *   errors     — Web Vitals + (future) error reporting
+   *
+   * Each defaults to `true` (granted). Pass partial state — only the
+   * keys you provide are changed.
+   *
+   *   Crossdeck.consent({ analytics: false });
+   *   Crossdeck.consent({ marketing: true, errors: true });
+   *
+   * DNT-derived denies cannot be flipped back on; if the browser said
+   * "don't track" we don't track even if the developer code disagrees.
+   */
+  consent(state) {
+    const s = this.requireStarted();
+    const next = s.consent.set(state);
+    s.debug.emit("sdk.consent_changed", "Consent state updated.", { ...next });
+    return next;
+  }
+  /** Snapshot of the current consent state. */
+  consentStatus() {
+    if (!this.state) {
+      return { analytics: true, marketing: true, errors: true };
+    }
+    return this.state.consent.get();
+  }
+  /**
+   * GDPR/CCPA "right to be forgotten" — calls the backend's
+   * /v1/identity/forget endpoint to schedule a server-side deletion of
+   * the customer's events and profile, then wipes all local state
+   * (identity, entitlements, queue, super-props, persistent stores).
+   *
+   * Idempotent. Safe to call when no identity has been established
+   * (it just wipes the empty local state).
+   *
+   * After forget() resolves, the SDK is in the same shape as if the
+   * developer had called `Crossdeck.reset()` — a fresh anonymousId is
+   * minted and the next session is a brand new identity-graph entry.
+   */
+  async forget() {
+    const s = this.requireStarted();
+    const identityQuery = this.identityQueryParams();
+    try {
+      await s.http.request("POST", "/identity/forget", {
+        body: {
+          // Send every identity hint we hold; the server resolves the
+          // canonical customer record and queues deletion. Missing
+          // endpoint (older backend) gracefully degrades — local state
+          // still wipes via the reset() call below.
+          ...identityQuery
+        }
+      });
+    } catch (err) {
+      s.debug.emit(
+        "sdk.consent_denied",
+        `forget() server call failed (${err instanceof Error ? err.message : String(err)}). Local state wiped anyway.`
+      );
+    }
+    this.reset();
+  }
   /**
    * Read the current customer's active entitlements from the server.
    * Updates the local cache so subsequent isEntitled() calls answer
@@ -1073,6 +2240,17 @@ var CrossdeckClient = class {
         message: "track(name) requires a non-empty name."
       });
     }
+    const isWebVital = name.startsWith("webvitals.");
+    const consentGateOk = isWebVital ? s.consent.errors : s.consent.analytics;
+    if (!consentGateOk) {
+      if (s.debug.enabled) {
+        s.debug.emit(
+          "sdk.consent_denied",
+          `Dropped event "${name}" \u2014 consent denied for ${isWebVital ? "errors" : "analytics"}.`
+        );
+      }
+      return;
+    }
     if (s.debug.enabled && properties) {
       const flagged = findSensitivePropertyKeys(properties);
       if (flagged.length > 0) {
@@ -1089,9 +2267,21 @@ var CrossdeckClient = class {
         "Using anonymous user until identify(userId) is called."
       );
     }
+    const validation = validateEventProperties(properties);
+    if (s.debug.enabled && validation.warnings.length > 0) {
+      for (const w of validation.warnings) {
+        s.debug.emit(
+          "sdk.property_coerced",
+          `Event "${name}" property ${JSON.stringify(w.key)} was ${w.kind.replace(/_/g, " ")} during validation.`,
+          { eventName: name, key: w.key, kind: w.kind }
+        );
+      }
+    }
     const enriched = { ...s.deviceInfo };
     const sessionId = s.autoTracker?.currentSessionId;
     if (sessionId) enriched.sessionId = sessionId;
+    const pageviewId = s.autoTracker?.currentPageviewId;
+    if (pageviewId) enriched.pageviewId = pageviewId;
     const acquisition = s.autoTracker?.currentAcquisition;
     if (acquisition) {
       if (acquisition.utm_source) enriched.utm_source = acquisition.utm_source;
@@ -1099,14 +2289,31 @@ var CrossdeckClient = class {
       if (acquisition.utm_campaign) enriched.utm_campaign = acquisition.utm_campaign;
       if (acquisition.utm_content) enriched.utm_content = acquisition.utm_content;
       if (acquisition.utm_term) enriched.utm_term = acquisition.utm_term;
-      if (acquisition.referrer) enriched.referrer = acquisition.referrer;
+      if (acquisition.referrer && s.consent.marketing) enriched.referrer = acquisition.referrer;
+      if (s.consent.marketing) {
+        if (acquisition.gclid) enriched.gclid = acquisition.gclid;
+        if (acquisition.fbclid) enriched.fbclid = acquisition.fbclid;
+        if (acquisition.msclkid) enriched.msclkid = acquisition.msclkid;
+        if (acquisition.ttclid) enriched.ttclid = acquisition.ttclid;
+        if (acquisition.li_fat_id) enriched.li_fat_id = acquisition.li_fat_id;
+        if (acquisition.twclid) enriched.twclid = acquisition.twclid;
+      }
+    }
+    const supers = s.superProps.getSuperProperties();
+    for (const k of Object.keys(supers)) {
+      if (!(k in enriched)) enriched[k] = supers[k];
+    }
+    const groupIds = s.superProps.getGroupIds();
+    if (Object.keys(groupIds).length > 0) {
+      enriched.$groups = groupIds;
     }
-    if (properties) Object.assign(enriched, properties);
+    Object.assign(enriched, validation.properties);
+    const finalProperties = s.scrubPii ? scrubPiiFromProperties(enriched) : enriched;
     const event = {
       eventId: this.mintEventId(),
       name,
       timestamp: Date.now(),
-      properties: enriched
+      properties: finalProperties
     };
     Object.assign(event, this.identityHintForEvent());
     s.events.enqueue(event);
@@ -1184,7 +2391,12 @@ var CrossdeckClient = class {
    */
   async heartbeat() {
     const s = this.requireStarted();
-    return await s.http.request("GET", "/sdk/heartbeat");
+    const result = await s.http.request("GET", "/sdk/heartbeat");
+    if (typeof result?.serverTime === "number" && Number.isFinite(result.serverTime)) {
+      s.lastServerTime = result.serverTime;
+      s.lastClientTime = Date.now();
+    }
+    return result;
   }
   /**
    * Wipe persisted identity + entitlement cache. Use on logout. The
@@ -1193,10 +2405,17 @@ var CrossdeckClient = class {
    */
   reset() {
     if (!this.state) return;
+    if (this.state.developerUserId) {
+      try {
+        this.track("user.signed_out", { auto: true });
+      } catch {
+      }
+    }
     this.state.autoTracker?.uninstall();
     this.state.identity.reset();
     this.state.entitlements.clear();
     this.state.events.reset();
+    this.state.superProps.clear();
     this.state.developerUserId = null;
     if (this.state.autoTracker) {
       const tracker = new AutoTracker(
@@ -1224,17 +2443,21 @@ var CrossdeckClient = class {
         developerUserId: null,
         sdkVersion: null,
         baseUrl: null,
-        entitlements: { count: 0, lastUpdated: 0 },
+        clock: { lastServerTime: null, lastClientTime: null, skewMs: null },
+        entitlements: { count: 0, lastUpdated: 0, listenerErrors: 0 },
         events: {
           buffered: 0,
           dropped: 0,
           inFlight: 0,
           lastFlushAt: 0,
-          lastError: null
+          lastError: null,
+          consecutiveFailures: 0,
+          nextRetryAt: null
         }
       };
     }
     const s = this.state;
+    const skewMs = s.lastServerTime !== null && s.lastClientTime !== null ? s.lastClientTime - s.lastServerTime : null;
     return {
       started: true,
       anonymousId: s.identity.anonymousId,
@@ -1242,9 +2465,15 @@ var CrossdeckClient = class {
       developerUserId: s.developerUserId,
       sdkVersion: s.options.sdkVersion,
       baseUrl: s.options.baseUrl,
+      clock: {
+        lastServerTime: s.lastServerTime,
+        lastClientTime: s.lastClientTime,
+        skewMs
+      },
       entitlements: {
         count: s.entitlements.list().length,
-        lastUpdated: s.entitlements.freshness
+        lastUpdated: s.entitlements.freshness,
+        listenerErrors: s.entitlements.listenerErrors
       },
       events: s.events.getStats()
     };
@@ -1273,14 +2502,30 @@ var CrossdeckClient = class {
     if (s.developerUserId) return { userId: s.developerUserId };
     return { anonymousId: s.identity.anonymousId };
   }
-  /** Pick the right identity hint to embed on a queued event. */
+  /**
+   * Embed every known identity axis on the event. Earlier this returned
+   * just the highest-priority hint (cdcust → developerUserId → anonymousId)
+   * to keep payloads small, but that leaked into analytics: once a user
+   * was logged in, every subsequent page.viewed shipped without
+   * anonymousId, and `uniqExact(anonymous_id)` on the warehouse side
+   * counted 0 visitors for the entire authenticated app.
+   *
+   * Bank-grade rule: the server is the single source of truth on
+   * dedup. Send everything we know; let CH count by whichever axis
+   * matches the question. Each field is at most 32 bytes — sending
+   * three on every event costs ~80 bytes per request, which is
+   * trivial compared to the analytics correctness it buys.
+   */
   identityHintForEvent() {
     const s = this.requireStarted();
+    const hint = {
+      anonymousId: s.identity.anonymousId
+    };
+    if (s.developerUserId) hint.developerUserId = s.developerUserId;
     if (s.identity.crossdeckCustomerId) {
-      return { crossdeckCustomerId: s.identity.crossdeckCustomerId };
+      hint.crossdeckCustomerId = s.identity.crossdeckCustomerId;
     }
-    if (s.developerUserId) return { developerUserId: s.developerUserId };
-    return { anonymousId: s.identity.anonymousId };
+    return hint;
   }
   mintEventId() {
     const ts = Date.now().toString(36);
@@ -1293,9 +2538,28 @@ function inferEnvFromKey(publicKey) {
   if (publicKey.startsWith("cd_pub_live_")) return "production";
   return null;
 }
+function isLocalHostname() {
+  const w = globalThis.window;
+  if (w?.__CROSSDECK_FORCE_LIVE__ === true) return false;
+  const hostname = w?.location?.hostname;
+  if (!hostname) return false;
+  if (hostname === "localhost" || hostname === "127.0.0.1") return true;
+  if (hostname === "::1" || hostname === "[::1]") return true;
+  if (hostname.endsWith(".local")) return true;
+  if (/^10\./.test(hostname)) return true;
+  if (/^192\.168\./.test(hostname)) return true;
+  if (/^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname)) return true;
+  return false;
+}
 function resolveAutoTrack(input) {
   if (input === false) {
-    return { sessions: false, pageViews: false, deviceInfo: false };
+    return {
+      sessions: false,
+      pageViews: false,
+      deviceInfo: false,
+      clicks: false,
+      webVitals: false
+    };
   }
   if (input === void 0 || input === true) {
     return { ...DEFAULT_AUTO_TRACK };
@@ -1303,7 +2567,9 @@ function resolveAutoTrack(input) {
   return {
     sessions: input.sessions ?? DEFAULT_AUTO_TRACK.sessions,
     pageViews: input.pageViews ?? DEFAULT_AUTO_TRACK.pageViews,
-    deviceInfo: input.deviceInfo ?? DEFAULT_AUTO_TRACK.deviceInfo
+    deviceInfo: input.deviceInfo ?? DEFAULT_AUTO_TRACK.deviceInfo,
+    clicks: input.clicks ?? DEFAULT_AUTO_TRACK.clicks,
+    webVitals: input.webVitals ?? DEFAULT_AUTO_TRACK.webVitals
   };
 }
 function installUnloadFlush(onUnload) {
@@ -1323,13 +2589,109 @@ function installUnloadFlush(onUnload) {
     w.removeEventListener("beforeunload", onTerminal);
   };
 }
+
+// src/error-codes.ts
+var CROSSDECK_ERROR_CODES = Object.freeze([
+  // ----- Configuration -----
+  {
+    code: "invalid_public_key",
+    type: "configuration_error",
+    description: "The publishable key passed to Crossdeck.init() doesn't start with cd_pub_.",
+    resolution: "Copy the key from your Crossdeck dashboard \u2192 API keys page.",
+    retryable: false
+  },
+  {
+    code: "missing_app_id",
+    type: "configuration_error",
+    description: "Crossdeck.init() was called without an appId.",
+    resolution: "Add appId to your init options \u2014 find it in the dashboard's Apps page.",
+    retryable: false
+  },
+  {
+    code: "invalid_environment",
+    type: "configuration_error",
+    description: "Crossdeck.init() requires environment: 'production' | 'sandbox'.",
+    resolution: 'Pass the literal string "production" or "sandbox" \u2014 no other values are accepted.',
+    retryable: false
+  },
+  {
+    code: "environment_mismatch",
+    type: "configuration_error",
+    description: "The publishable key's env prefix doesn't match the declared environment option.",
+    resolution: "Either change `environment` to match the key prefix (cd_pub_test_ \u2194 sandbox, cd_pub_live_ \u2194 production), or swap the key for one minted in the right env.",
+    retryable: false
+  },
+  {
+    code: "not_initialized",
+    type: "configuration_error",
+    description: "An SDK method was called before Crossdeck.init().",
+    resolution: "Call Crossdeck.init({ appId, publicKey, environment }) once at app startup before any other method.",
+    retryable: false
+  },
+  // ----- Identify / track / purchase argument validation -----
+  {
+    code: "missing_user_id",
+    type: "invalid_request_error",
+    description: "identify() was called with an empty userId.",
+    resolution: "Pass a stable, non-empty user identifier from your auth layer \u2014 never a hardcoded placeholder.",
+    retryable: false
+  },
+  {
+    code: "missing_event_name",
+    type: "invalid_request_error",
+    description: "track() was called without an event name.",
+    resolution: "Pass a non-empty string as the first argument.",
+    retryable: false
+  },
+  {
+    code: "missing_group_type",
+    type: "invalid_request_error",
+    description: "group() was called without a group type.",
+    resolution: 'Pass a non-empty type (e.g. "org", "team") as the first argument.',
+    retryable: false
+  },
+  {
+    code: "missing_signed_transaction_info",
+    type: "invalid_request_error",
+    description: "syncPurchases() was called without StoreKit 2 signed transaction info.",
+    resolution: "Pass the JWS string from Transaction.currentEntitlements / Transaction.updates.",
+    retryable: false
+  },
+  // ----- Network / transport -----
+  {
+    code: "fetch_failed",
+    type: "network_error",
+    description: "The underlying fetch() call failed (typically a network outage or DNS issue).",
+    resolution: "Check the user's network. The SDK will retry automatically with exponential backoff.",
+    retryable: true
+  },
+  {
+    code: "request_timeout",
+    type: "network_error",
+    description: "A request was aborted after the configured timeoutMs (default 15s).",
+    resolution: "Check the user's connection. Increase timeoutMs in init options if the user is on a known-slow network.",
+    retryable: true
+  },
+  {
+    code: "invalid_json_response",
+    type: "internal_error",
+    description: "The server returned a 2xx with an unparseable body.",
+    resolution: "Likely a transient backend bug. Retry; if it persists, contact support with the requestId.",
+    retryable: true
+  }
+]);
+function getErrorCode(code) {
+  return CROSSDECK_ERROR_CODES.find((e) => e.code === code);
+}
 export {
+  CROSSDECK_ERROR_CODES,
   Crossdeck,
   CrossdeckClient,
   CrossdeckError,
   DEFAULT_BASE_URL,
   MemoryStorage,
   SDK_NAME,
-  SDK_VERSION
+  SDK_VERSION,
+  getErrorCode
 };
 //# sourceMappingURL=index.mjs.map