@cross-deck/web 0.7.0 → 1.0.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 = "1.0.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+var DEFAULT_TIMEOUT_MS = 15e3;
 var HttpClient = class {
   constructor(config) {
     this.config = config;
@@ -71,25 +91,38 @@ var HttpClient = class {
       "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);
@@ -286,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) {
@@ -299,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
@@ -352,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 {
@@ -369,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);
@@ -378,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 {
@@ -387,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
@@ -396,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?.();
@@ -423,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 {
@@ -442,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;
@@ -452,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") {
@@ -470,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() {
@@ -660,7 +888,9 @@ var DEFAULT_AUTO_TRACK = {
   sessions: true,
   pageViews: true,
   deviceInfo: true,
-  clicks: true
+  clicks: true,
+  webVitals: true,
+  errors: true
 };
 var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
 var EMPTY_ACQUISITION = {
@@ -669,7 +899,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) {
@@ -677,6 +913,17 @@ 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;
@@ -707,6 +954,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
@@ -787,7 +1038,9 @@ var AutoTracker = class {
       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,
         search: loc.search || void 0,
@@ -991,6 +1244,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 {
@@ -1048,6 +1307,1025 @@ 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/breadcrumbs.ts
+var BreadcrumbBuffer = class {
+  constructor(maxSize = 50) {
+    this.maxSize = maxSize;
+    this.items = [];
+  }
+  add(crumb) {
+    this.items.push(crumb);
+    if (this.items.length > this.maxSize) {
+      this.items.shift();
+    }
+  }
+  /** Defensive copy — caller can read freely without mutating buffer state. */
+  snapshot() {
+    return this.items.slice();
+  }
+  clear() {
+    this.items = [];
+  }
+  get size() {
+    return this.items.length;
+  }
+};
+
+// src/stack-parser.ts
+function parseStack(stack) {
+  if (!stack || typeof stack !== "string") return [];
+  const lines = stack.split("\n");
+  const frames = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const frame = parseLine(trimmed);
+    if (frame) frames.push(frame);
+  }
+  return frames;
+}
+function parseLine(line) {
+  let m = /^at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)$/.exec(line);
+  if (m) {
+    return buildFrame({
+      function: m[1],
+      filename: m[2],
+      lineno: parseInt(m[3], 10),
+      colno: parseInt(m[4], 10),
+      raw: line
+    });
+  }
+  m = /^at\s+(.+?):(\d+):(\d+)$/.exec(line);
+  if (m) {
+    return buildFrame({
+      function: "?",
+      filename: m[1],
+      lineno: parseInt(m[2], 10),
+      colno: parseInt(m[3], 10),
+      raw: line
+    });
+  }
+  m = /^(.*?)@(.+?):(\d+):(\d+)$/.exec(line);
+  if (m) {
+    return buildFrame({
+      function: m[1] || "?",
+      filename: m[2],
+      lineno: parseInt(m[3], 10),
+      colno: parseInt(m[4], 10),
+      raw: line
+    });
+  }
+  if (/^\w*Error/.test(line) || !line.includes(":")) {
+    return null;
+  }
+  return {
+    function: "?",
+    filename: "",
+    lineno: 0,
+    colno: 0,
+    in_app: true,
+    raw: line
+  };
+}
+function buildFrame(input) {
+  return {
+    function: input.function || "?",
+    filename: input.filename,
+    lineno: Number.isFinite(input.lineno) ? input.lineno : 0,
+    colno: Number.isFinite(input.colno) ? input.colno : 0,
+    in_app: isInAppFrame(input.filename),
+    raw: input.raw
+  };
+}
+function isInAppFrame(filename) {
+  if (!filename) return true;
+  if (/^(?:chrome|moz|safari|webkit)-extension:\/\//.test(filename)) return false;
+  if (/\bcdn\.jsdelivr\.net\b/.test(filename)) return false;
+  if (/\bunpkg\.com\b/.test(filename)) return false;
+  if (/\bgoogletagmanager\.com\b/.test(filename)) return false;
+  if (/\bgoogle-analytics\.com\b/.test(filename)) return false;
+  if (/\b@cross-deck\/web\b/.test(filename)) return false;
+  if (/\/crossdeck\.umd\.min\.js$/.test(filename)) return false;
+  return true;
+}
+function fingerprintError(message, frames) {
+  const inAppFrames = frames.filter((f) => f.in_app).slice(0, 3);
+  const key = [
+    (message || "").slice(0, 200),
+    ...inAppFrames.map((f) => `${f.function}@${f.filename}:${f.lineno}`)
+  ].join("|");
+  return djb2Hex(key);
+}
+function djb2Hex(input) {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = (h << 5) + h + input.charCodeAt(i) | 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/error-capture.ts
+var DEFAULT_ERROR_CAPTURE = {
+  enabled: true,
+  onError: true,
+  onUnhandledRejection: true,
+  wrapFetch: true,
+  wrapXhr: true,
+  captureConsole: false,
+  ignoreErrors: [
+    // Classic browser noise. These aren't application bugs.
+    "ResizeObserver loop limit exceeded",
+    "ResizeObserver loop completed with undelivered notifications",
+    "Non-Error promise rejection captured",
+    // Cross-origin script errors that the browser strips — no info,
+    // no way to act on them, just noise.
+    "Script error.",
+    "Script error"
+  ],
+  allowUrls: [],
+  denyUrls: [
+    // Common third-party extensions that pollute error streams.
+    /^chrome-extension:\/\//,
+    /^moz-extension:\/\//,
+    /^safari-extension:\/\//,
+    /^webkit-extension:\/\//,
+    /^safari-web-extension:\/\//
+  ],
+  sampleRate: 1,
+  maxPerFingerprintPerMinute: 5,
+  maxPerSession: 100
+};
+var ErrorTracker = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.installed = false;
+    this.cleanups = [];
+    this._reporting = false;
+    this.sessionCount = 0;
+    this.fingerprintWindow = /* @__PURE__ */ new Map();
+  }
+  install() {
+    if (this.installed) return;
+    if (!this.opts.config.enabled) return;
+    if (typeof globalThis === "undefined" || !("window" in globalThis)) return;
+    const w = globalThis.window;
+    if (this.opts.config.onError) this.installOnErrorListener(w);
+    if (this.opts.config.onUnhandledRejection) this.installRejectionListener(w);
+    if (this.opts.config.wrapFetch) this.installFetchWrap(w);
+    if (this.opts.config.wrapXhr) this.installXhrWrap(w);
+    if (this.opts.config.captureConsole) this.installConsoleWrap();
+    this.installed = true;
+  }
+  uninstall() {
+    for (const fn of this.cleanups.splice(0)) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+    this.installed = false;
+  }
+  /**
+   * Manual API. Either an Error instance or any unknown value (we
+   * coerce). Returns silently — never throws.
+   */
+  captureError(error, options) {
+    if (!this.opts.isConsented()) return;
+    try {
+      const captured = this.buildFromUnknown(error, "error.handled", options?.level ?? "error");
+      if (options?.context) captured.context = { ...captured.context, ...options.context };
+      if (options?.tags) captured.tags = { ...captured.tags, ...options.tags };
+      this.maybeReport(captured);
+    } catch {
+    }
+  }
+  /**
+   * Capture a non-error event as an issue. For "we hit a soft-warning
+   * code path" / "deprecated API used" kinds of signals. Pairs with
+   * Sentry's captureMessage().
+   */
+  captureMessage(message, level = "info") {
+    if (!this.opts.isConsented()) return;
+    try {
+      const captured = {
+        timestamp: Date.now(),
+        kind: "error.message",
+        level,
+        message,
+        errorType: null,
+        frames: [],
+        rawStack: null,
+        filename: null,
+        lineno: null,
+        colno: null,
+        fingerprint: fingerprintError(message, []),
+        breadcrumbs: this.opts.breadcrumbs.snapshot(),
+        context: this.opts.getContext(),
+        tags: this.opts.getTags()
+      };
+      this.maybeReport(captured);
+    } catch {
+    }
+  }
+  // ============================================================
+  // Listener installation
+  // ============================================================
+  installOnErrorListener(w) {
+    const handler = (event) => {
+      if (this._reporting) return;
+      if (!this.opts.isConsented()) return;
+      try {
+        this._reporting = true;
+        const captured = this.buildFromErrorEvent(event);
+        this.maybeReport(captured);
+      } catch {
+      } finally {
+        this._reporting = false;
+      }
+    };
+    w.addEventListener("error", handler, true);
+    this.cleanups.push(() => w.removeEventListener("error", handler, true));
+  }
+  installRejectionListener(w) {
+    const handler = (event) => {
+      if (this._reporting) return;
+      if (!this.opts.isConsented()) return;
+      try {
+        this._reporting = true;
+        const captured = this.buildFromUnknown(
+          event.reason,
+          "error.unhandledrejection",
+          "error"
+        );
+        this.maybeReport(captured);
+      } catch {
+      } finally {
+        this._reporting = false;
+      }
+    };
+    w.addEventListener("unhandledrejection", handler);
+    this.cleanups.push(() => w.removeEventListener("unhandledrejection", handler));
+  }
+  /**
+   * Wrap fetch() so failed HTTP requests get auto-captured. We do NOT
+   * call this an "error" for 4xx (those are often expected — auth
+   * required, validation failed). Only 5xx + network failures fire.
+   */
+  installFetchWrap(w) {
+    const origFetch = w.fetch?.bind(w);
+    if (!origFetch) return;
+    const wrapped = async (...args) => {
+      const input = args[0];
+      const init = args[1] ?? {};
+      const url = typeof input === "string" ? input : input?.url ?? "";
+      const method = (init.method || "GET").toUpperCase();
+      const start = Date.now();
+      this.opts.breadcrumbs.add({
+        timestamp: start,
+        category: "http",
+        message: `${method} ${url}`,
+        data: { url, method }
+      });
+      try {
+        const response = await origFetch(...args);
+        if (response.status >= 500 && this.opts.isConsented()) {
+          if (!url.includes("api.cross-deck.com")) {
+            this.captureHttp({
+              url,
+              method,
+              status: response.status,
+              statusText: response.statusText
+            });
+          }
+        }
+        return response;
+      } catch (err) {
+        if (this.opts.isConsented() && !url.includes("api.cross-deck.com")) {
+          this.captureHttp({
+            url,
+            method,
+            status: 0,
+            statusText: err instanceof Error ? err.message : "network error"
+          });
+        }
+        throw err;
+      }
+    };
+    w.fetch = wrapped;
+    this.cleanups.push(() => {
+      if (w.fetch === wrapped) w.fetch = origFetch;
+    });
+  }
+  /**
+   * Wrap XMLHttpRequest for legacy consumers (jQuery $.ajax under the
+   * hood, older bundlers). Same capture semantics as fetch.
+   */
+  installXhrWrap(w) {
+    const xhrCtor = w.XMLHttpRequest;
+    const proto = xhrCtor?.prototype;
+    if (!proto) return;
+    const origOpen = proto.open;
+    const origSend = proto.send;
+    const tracker = this;
+    proto.open = function(method, url, ...rest) {
+      this._cdMethod = method;
+      this._cdUrl = url;
+      return origOpen.apply(this, [method, url, ...rest]);
+    };
+    proto.send = function(body) {
+      const xhr = this;
+      const onLoad = () => {
+        try {
+          if (xhr.status >= 500 && tracker.opts.isConsented()) {
+            const url = xhr._cdUrl ?? "";
+            if (!url.includes("api.cross-deck.com")) {
+              tracker.captureHttp({
+                url,
+                method: (xhr._cdMethod ?? "GET").toUpperCase(),
+                status: xhr.status,
+                statusText: xhr.statusText
+              });
+            }
+          }
+        } catch {
+        }
+      };
+      xhr.addEventListener("loadend", onLoad);
+      return origSend.apply(this, [body ?? null]);
+    };
+    this.cleanups.push(() => {
+      proto.open = origOpen;
+      proto.send = origSend;
+    });
+  }
+  installConsoleWrap() {
+    const console2 = globalThis.console;
+    if (!console2) return;
+    const orig = console2.error.bind(console2);
+    console2.error = (...args) => {
+      try {
+        if (this.opts.isConsented()) {
+          this.captureMessage(args.map((a) => safeStringify2(a)).join(" "), "error");
+        }
+      } catch {
+      }
+      return orig(...args);
+    };
+    this.cleanups.push(() => {
+      console2.error = orig;
+    });
+  }
+  // ============================================================
+  // Builders
+  // ============================================================
+  buildFromErrorEvent(event) {
+    const err = event.error;
+    const message = event.message || (err instanceof Error ? err.message : "Unknown error");
+    const stack = err instanceof Error ? err.stack ?? null : null;
+    const frames = parseStack(stack);
+    return {
+      timestamp: Date.now(),
+      kind: "error.unhandled",
+      level: "error",
+      message: String(message).slice(0, 1024),
+      errorType: err instanceof Error ? err.name : null,
+      frames,
+      rawStack: stack,
+      filename: event.filename || null,
+      lineno: typeof event.lineno === "number" ? event.lineno : null,
+      colno: typeof event.colno === "number" ? event.colno : null,
+      fingerprint: fingerprintError(message, frames),
+      breadcrumbs: this.opts.breadcrumbs.snapshot(),
+      context: this.opts.getContext(),
+      tags: this.opts.getTags()
+    };
+  }
+  buildFromUnknown(err, kind, level) {
+    if (err instanceof Error) {
+      const frames = parseStack(err.stack);
+      return {
+        timestamp: Date.now(),
+        kind,
+        level,
+        message: String(err.message).slice(0, 1024),
+        errorType: err.name,
+        frames,
+        rawStack: err.stack ?? null,
+        filename: null,
+        lineno: null,
+        colno: null,
+        fingerprint: fingerprintError(err.message, frames),
+        breadcrumbs: this.opts.breadcrumbs.snapshot(),
+        context: this.opts.getContext(),
+        tags: this.opts.getTags()
+      };
+    }
+    const message = safeStringify2(err).slice(0, 1024);
+    return {
+      timestamp: Date.now(),
+      kind,
+      level,
+      message,
+      errorType: null,
+      frames: [],
+      rawStack: null,
+      filename: null,
+      lineno: null,
+      colno: null,
+      fingerprint: fingerprintError(message, []),
+      breadcrumbs: this.opts.breadcrumbs.snapshot(),
+      context: this.opts.getContext(),
+      tags: this.opts.getTags()
+    };
+  }
+  captureHttp(info) {
+    try {
+      const message = `HTTP ${info.status} ${info.method} ${info.url}`;
+      const captured = {
+        timestamp: Date.now(),
+        kind: "error.http",
+        level: "error",
+        message,
+        errorType: `HTTPError`,
+        frames: [],
+        rawStack: null,
+        filename: info.url,
+        lineno: null,
+        colno: null,
+        fingerprint: fingerprintError(`HTTP ${info.status} ${info.method}`, []),
+        breadcrumbs: this.opts.breadcrumbs.snapshot(),
+        context: this.opts.getContext(),
+        tags: this.opts.getTags(),
+        http: info
+      };
+      this.maybeReport(captured);
+    } catch {
+    }
+  }
+  // ============================================================
+  // Reporting pipeline — filter / sample / rate-limit / send
+  // ============================================================
+  maybeReport(err) {
+    if (this.sessionCount >= this.opts.config.maxPerSession) return;
+    if (this.shouldIgnore(err)) return;
+    if (!this.passesUrlGate(err)) return;
+    if (!this.passesSample(err)) return;
+    if (!this.passesRateLimit(err)) return;
+    let finalErr = err;
+    if (this.opts.beforeSend) {
+      try {
+        finalErr = this.opts.beforeSend(err);
+      } catch {
+        finalErr = err;
+      }
+      if (!finalErr) return;
+    }
+    this.sessionCount += 1;
+    try {
+      this.opts.report(finalErr);
+    } catch {
+    }
+  }
+  shouldIgnore(err) {
+    for (const pat of this.opts.config.ignoreErrors) {
+      if (typeof pat === "string" && err.message.includes(pat)) return true;
+      if (pat instanceof RegExp && pat.test(err.message)) return true;
+    }
+    return false;
+  }
+  passesUrlGate(err) {
+    const topFrame = err.frames.find((f) => f.filename) ?? null;
+    const url = topFrame?.filename ?? err.filename ?? "";
+    if (!url) return true;
+    for (const pat of this.opts.config.denyUrls) {
+      if (typeof pat === "string" && url.includes(pat)) return false;
+      if (pat instanceof RegExp && pat.test(url)) return false;
+    }
+    if (this.opts.config.allowUrls.length > 0) {
+      for (const pat of this.opts.config.allowUrls) {
+        if (typeof pat === "string" && url.includes(pat)) return true;
+        if (pat instanceof RegExp && pat.test(url)) return true;
+      }
+      return false;
+    }
+    return true;
+  }
+  passesSample(err) {
+    if (this.opts.config.sampleRate >= 1) return true;
+    if (this.opts.config.sampleRate <= 0) return false;
+    const hashByte = parseInt(err.fingerprint.slice(0, 2), 16);
+    return hashByte / 255 < this.opts.config.sampleRate;
+  }
+  passesRateLimit(err) {
+    const windowMs = 6e4;
+    const now = Date.now();
+    const max = this.opts.config.maxPerFingerprintPerMinute;
+    const arr = this.fingerprintWindow.get(err.fingerprint) ?? [];
+    const fresh = arr.filter((t) => now - t < windowMs);
+    if (fresh.length >= max) {
+      this.fingerprintWindow.set(err.fingerprint, fresh);
+      return false;
+    }
+    fresh.push(now);
+    this.fingerprintWindow.set(err.fingerprint, fresh);
+    return true;
+  }
+};
+function safeStringify2(v) {
+  if (v == null) return String(v);
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return Object.prototype.toString.call(v);
+  }
+}
+
 // src/crossdeck.ts
 var CrossdeckClient = class {
   constructor() {
@@ -1137,6 +2415,13 @@ var CrossdeckClient = class {
     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,
@@ -1146,26 +2431,57 @@ 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."
+      );
+    }
+    const breadcrumbs = new BreadcrumbBuffer(50);
     this.state = {
       http,
       identity,
       entitlements,
       events,
       autoTracker: null,
+      webVitals: null,
+      errors: null,
+      breadcrumbs,
+      errorContext: {},
+      errorTags: {},
+      errorBeforeSend: 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,
@@ -1180,6 +2496,27 @@ 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();
+    }
+    if (autoTrack.errors) {
+      const tracker = new ErrorTracker({
+        config: { ...DEFAULT_ERROR_CAPTURE, enabled: true },
+        breadcrumbs,
+        report: (err) => this.reportError(err),
+        getContext: () => ({ ...this.state.errorContext }),
+        getTags: () => ({ ...this.state.errorTags }),
+        beforeSend: this.state.errorBeforeSend,
+        isConsented: () => this.state.consent.errors
+      });
+      this.state.errors = tracker;
+      tracker.install();
+    }
     this.state.uninstallUnloadFlush = installUnloadFlush(() => {
       void this.flush({ keepalive: true }).catch(() => void 0);
     });
@@ -1203,8 +2540,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({
@@ -1213,13 +2561,265 @@ 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();
+  }
+  // ============================================================
+  // Error capture surface (v1.0.0+)
+  // ============================================================
+  /**
+   * Manually capture an error from a try/catch block.
+   *
+   *   try { …risky… } catch (err) {
+   *     Crossdeck.captureError(err, { context: { plan: "pro" } });
+   *   }
+   *
+   * The error is shipped through the same event queue as analytics
+   * (durable, retried, rate-limited per fingerprint). Sends are gated
+   * by `consent.errors`. Returns silently — never throws, even if the
+   * SDK isn't initialised yet.
+   */
+  captureError(error, options) {
+    if (!this.state?.errors) return;
+    this.state.errors.captureError(error, options);
+  }
+  /**
+   * Capture a non-error event you want to surface as an issue
+   * ("deprecated path hit", "we entered the slow code path"). Sentry
+   * captureMessage pattern. Returns silently if not initialised.
+   */
+  captureMessage(message, level = "info") {
+    if (!this.state?.errors) return;
+    this.state.errors.captureMessage(message, level);
+  }
+  /**
+   * Attach a tag to every subsequent error report. Tags are key/value
+   * strings (Sentry pattern): `setTag("flow", "checkout")` → every
+   * error from this point on carries `tags.flow === "checkout"`.
+   */
+  setTag(key, value) {
+    if (!this.state) return;
+    this.state.errorTags[key] = value;
+  }
+  /** Bulk-set tags. Merges with existing tags. */
+  setTags(tags) {
+    if (!this.state) return;
+    Object.assign(this.state.errorTags, tags);
+  }
+  /**
+   * Attach a structured context blob to every subsequent error report.
+   * Unlike tags (flat key/value), context is a named bag of arbitrary
+   * data: `setContext("cart", { items: 3, total: 42.99 })`.
+   */
+  setContext(name, data) {
+    if (!this.state) return;
+    this.state.errorContext[name] = data;
+  }
+  /**
+   * Add a custom breadcrumb to the rolling buffer. Useful for marking
+   * domain-meaningful moments ("user opened paywall") that aren't
+   * already auto-captured. The buffer caps at 50 entries; old ones
+   * evict.
+   */
+  addBreadcrumb(crumb) {
+    if (!this.state) return;
+    this.state.breadcrumbs.add(crumb);
+  }
+  /**
+   * Install a pre-send hook for errors. Return null to drop, or a
+   * modified CapturedError to scrub / rewrite. Sentry's beforeSend
+   * pattern — the only way to redact app-specific PII (auth tokens
+   * in URLs, etc.) before the report leaves the browser.
+   */
+  setErrorBeforeSend(hook) {
+    if (!this.state) return;
+    this.state.errorBeforeSend = hook;
+  }
+  /**
+   * Internal: turn a CapturedError into a Crossdeck event and enqueue
+   * it. Goes through the same queue / persistence / consent / scrub
+   * pipeline as analytics events.
+   */
+  reportError(err) {
+    const properties = {
+      // Identifiers
+      fingerprint: err.fingerprint,
+      level: err.level,
+      // Error shape
+      errorType: err.errorType,
+      message: err.message,
+      // Stack
+      stack: err.rawStack ?? void 0,
+      frames: err.frames,
+      filename: err.filename ?? void 0,
+      lineno: err.lineno ?? void 0,
+      colno: err.colno ?? void 0,
+      // Context
+      tags: err.tags,
+      context: err.context,
+      breadcrumbs: err.breadcrumbs,
+      // HTTP (only when applicable)
+      http: err.http
+    };
+    for (const k of Object.keys(properties)) {
+      if (properties[k] === void 0) delete properties[k];
+    }
+    this.track(err.kind, properties);
+  }
+  /**
+   * 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
@@ -1297,6 +2897,18 @@ var CrossdeckClient = class {
         message: "track(name) requires a non-empty name."
       });
     }
+    const isError = name.startsWith("error.");
+    const isWebVital = name.startsWith("webvitals.");
+    const consentGateOk = isError || 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) {
@@ -1313,9 +2925,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;
@@ -1323,17 +2947,46 @@ 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];
     }
-    if (properties) Object.assign(enriched, properties);
+    const groupIds = s.superProps.getGroupIds();
+    if (Object.keys(groupIds).length > 0) {
+      enriched.$groups = groupIds;
+    }
+    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);
+    if (!isError && !isWebVital) {
+      const category = name.startsWith("page.") ? "navigation" : name.startsWith("element.") || name === "session.started" ? "ui.click" : "custom";
+      s.breadcrumbs.add({
+        timestamp: event.timestamp,
+        category,
+        message: name,
+        // Strip the device-info / session bloat from the breadcrumb
+        // payload — only the caller-supplied properties belong in
+        // the user-readable trail.
+        data: properties ? { ...properties } : void 0
+      });
+    }
   }
   /**
    * Force-flush queued events. Useful to call from page-unload handlers.
@@ -1408,7 +3061,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
@@ -1427,6 +3085,10 @@ var CrossdeckClient = class {
     this.state.identity.reset();
     this.state.entitlements.clear();
     this.state.events.reset();
+    this.state.superProps.clear();
+    this.state.breadcrumbs.clear();
+    this.state.errorContext = {};
+    this.state.errorTags = {};
     this.state.developerUserId = null;
     if (this.state.autoTracker) {
       const tracker = new AutoTracker(
@@ -1454,17 +3116,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,
@@ -1472,9 +3138,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()
     };
@@ -1541,6 +3213,7 @@ function inferEnvFromKey(publicKey) {
 }
 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;
@@ -1553,7 +3226,14 @@ function isLocalHostname() {
 }
 function resolveAutoTrack(input) {
   if (input === false) {
-    return { sessions: false, pageViews: false, deviceInfo: false, clicks: false };
+    return {
+      sessions: false,
+      pageViews: false,
+      deviceInfo: false,
+      clicks: false,
+      webVitals: false,
+      errors: false
+    };
   }
   if (input === void 0 || input === true) {
     return { ...DEFAULT_AUTO_TRACK };
@@ -1562,7 +3242,9 @@ function resolveAutoTrack(input) {
     sessions: input.sessions ?? DEFAULT_AUTO_TRACK.sessions,
     pageViews: input.pageViews ?? DEFAULT_AUTO_TRACK.pageViews,
     deviceInfo: input.deviceInfo ?? DEFAULT_AUTO_TRACK.deviceInfo,
-    clicks: input.clicks ?? DEFAULT_AUTO_TRACK.clicks
+    clicks: input.clicks ?? DEFAULT_AUTO_TRACK.clicks,
+    webVitals: input.webVitals ?? DEFAULT_AUTO_TRACK.webVitals,
+    errors: input.errors ?? DEFAULT_AUTO_TRACK.errors
   };
 }
 function installUnloadFlush(onUnload) {
@@ -1582,13 +3264,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