@cross-deck/web 0.5.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;
 }
@@ -448,12 +470,40 @@ declare class CrossdeckError extends Error {
 /**
  * Storage adapters for SDK-persisted state.
  *
- * Two flavours:
+ * Three flavours:
  *   - browser localStorage (default in browsers)
+ *   - 1st-party document.cookie (redundancy for cleared localStorage)
  *   - in-memory (default in Node, or as an explicit fallback)
  *
  * Detection is at construction time, not at every call — picking the
  * adapter once means we don't hit `typeof window` checks on hot paths.
+ *
+ * ----- Bank-grade identity continuity -----
+ *
+ * Plain localStorage is not enough. ITP, private browsing, "clear site
+ * data" actions, and aggressive privacy extensions all wipe it. When
+ * that happens, the SDK mints a fresh anonymousId on next page load
+ * and the customer's analytics see one human as multiple "new
+ * visitors" — a credibility hit on every dashboard chart that depends
+ * on visitor uniqueness (new vs returning, retention, funnels).
+ *
+ * The fix is redundancy: we write the same identity to BOTH
+ * localStorage AND a 1st-party cookie. On boot we read both; whichever
+ * survived wins. On set, we write to both stores so a future clear of
+ * either doesn't lose the user.
+ *
+ * Caveats (documented honestly):
+ *   1. Safari ITP caps client-set 1st-party cookies at 7 days. Cookie
+ *      redundancy protects against localStorage clears WITHIN that
+ *      7-day window, not beyond it. The full ITP-bypass story (server-
+ *      set cookies via a customer-CNAMEd subdomain) is a Phase 2
+ *      follow-up that requires customer DNS configuration.
+ *   2. We never write fingerprintable data — only the same anonymousId
+ *      already in localStorage. Privacy posture is unchanged from
+ *      single-store identity.
+ *   3. `persistIdentity: false` disables BOTH stores so customers
+ *      running strict consent flows can defer cookie writes until the
+ *      user opts in.
  */
 
 /**
@@ -476,7 +526,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.5.0";
+declare const SDK_VERSION = "0.6.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**

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;
 }
@@ -448,12 +470,40 @@ declare class CrossdeckError extends Error {
 /**
  * Storage adapters for SDK-persisted state.
  *
- * Two flavours:
+ * Three flavours:
  *   - browser localStorage (default in browsers)
+ *   - 1st-party document.cookie (redundancy for cleared localStorage)
  *   - in-memory (default in Node, or as an explicit fallback)
  *
  * Detection is at construction time, not at every call — picking the
  * adapter once means we don't hit `typeof window` checks on hot paths.
+ *
+ * ----- Bank-grade identity continuity -----
+ *
+ * Plain localStorage is not enough. ITP, private browsing, "clear site
+ * data" actions, and aggressive privacy extensions all wipe it. When
+ * that happens, the SDK mints a fresh anonymousId on next page load
+ * and the customer's analytics see one human as multiple "new
+ * visitors" — a credibility hit on every dashboard chart that depends
+ * on visitor uniqueness (new vs returning, retention, funnels).
+ *
+ * The fix is redundancy: we write the same identity to BOTH
+ * localStorage AND a 1st-party cookie. On boot we read both; whichever
+ * survived wins. On set, we write to both stores so a future clear of
+ * either doesn't lose the user.
+ *
+ * Caveats (documented honestly):
+ *   1. Safari ITP caps client-set 1st-party cookies at 7 days. Cookie
+ *      redundancy protects against localStorage clears WITHIN that
+ *      7-day window, not beyond it. The full ITP-bypass story (server-
+ *      set cookies via a customer-CNAMEd subdomain) is a Phase 2
+ *      follow-up that requires customer DNS configuration.
+ *   2. We never write fingerprintable data — only the same anonymousId
+ *      already in localStorage. Privacy posture is unchanged from
+ *      single-store identity.
+ *   3. `persistIdentity: false` disables BOTH stores so customers
+ *      running strict consent flows can defer cookie writes until the
+ *      user opts in.
  */
 
 /**
@@ -476,7 +526,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.5.0";
+declare const SDK_VERSION = "0.6.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**