@cross-deck/web 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -148,6 +148,15 @@ interface AutoTrackOptions {
     pageViews: boolean;
     /** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
     deviceInfo: boolean;
+    /**
+     * Click autocapture — fire `element.clicked` for every interactive
+     * click on the page. Default true. Mixpanel/Amplitude pattern. Powers
+     * Crossdeck's funnel-attribution USP ("clicked X then converted").
+     * Privacy: skips form inputs / password fields / [class~="cd-noTrack"]
+     * subtrees. Override on individual elements with data-cd-event="custom"
+     * or data-cd-prop-* for custom property tagging.
+     */
+    clicks: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -402,7 +411,20 @@ declare class CrossdeckClient {
      * — matches the resolveCrossdeckCustomerId precedence on the server.
      */
     private identityQueryParams;
-    /** 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.
+     */
     private identityHintForEvent;
     private mintEventId;
 }

package/dist/index.d.ts

@@ -148,6 +148,15 @@ interface AutoTrackOptions {
     pageViews: boolean;
     /** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
     deviceInfo: boolean;
+    /**
+     * Click autocapture — fire `element.clicked` for every interactive
+     * click on the page. Default true. Mixpanel/Amplitude pattern. Powers
+     * Crossdeck's funnel-attribution USP ("clicked X then converted").
+     * Privacy: skips form inputs / password fields / [class~="cd-noTrack"]
+     * subtrees. Override on individual elements with data-cd-event="custom"
+     * or data-cd-prop-* for custom property tagging.
+     */
+    clicks: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -402,7 +411,20 @@ declare class CrossdeckClient {
      * — matches the resolveCrossdeckCustomerId precedence on the server.
      */
     private identityQueryParams;
-    /** 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.
+     */
     private identityHintForEvent;
     private mintEventId;
 }

package/dist/index.mjs

@@ -62,6 +62,9 @@ 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}`,
@@ -104,6 +107,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 +130,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";
@@ -605,7 +659,8 @@ function parseUserAgent(ua) {
 var DEFAULT_AUTO_TRACK = {
   sessions: true,
   pageViews: true,
-  deviceInfo: true
+  deviceInfo: true,
+  clicks: true
 };
 var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
 var EMPTY_ACQUISITION = {
@@ -627,6 +682,7 @@ var AutoTracker = class {
     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) {
@@ -721,11 +777,19 @@ 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.track("page.viewed", {
         path: loc.pathname,
-        url: loc.href,
+        url,
         search: loc.search || void 0,
         hash: loc.hash || void 0,
         title: doc.title,
@@ -747,7 +811,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 +823,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";
 }
@@ -879,6 +1092,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,8 +1119,18 @@ 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";
@@ -959,7 +1183,7 @@ var CrossdeckClient = class {
     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);
     }
   }
@@ -1193,6 +1417,12 @@ 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();
@@ -1273,14 +1503,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 +1539,21 @@ function inferEnvFromKey(publicKey) {
   if (publicKey.startsWith("cd_pub_live_")) return "production";
   return null;
 }
+function isLocalHostname() {
+  const w = globalThis.window;
+  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 };
   }
   if (input === void 0 || input === true) {
     return { ...DEFAULT_AUTO_TRACK };
@@ -1303,7 +1561,8 @@ 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
   };
 }
 function installUnloadFlush(onUnload) {