@cross-deck/web 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -337,9 +337,16 @@ declare class CrossdeckClient {
     /**
      * Force-flush queued events. Useful to call from page-unload handlers.
      *
+     * Pass `{ keepalive: true }` from terminal handlers (pagehide /
+     * visibilitychange→hidden / beforeunload). The browser keeps the
+     * request alive after the page tears down, so the final batch
+     * actually lands instead of being cancelled with the unload.
+     *
      * NorthStar §4: standard method name across all Crossdeck SDKs.
      */
-    flush(): Promise<void>;
+    flush(options?: {
+        keepalive?: boolean;
+    }): Promise<void>;
     /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
     flushEvents(): Promise<void>;
     /**
@@ -441,12 +448,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.
  */
 
 /**
@@ -469,7 +504,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.6.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**

package/dist/index.mjs

@@ -46,7 +46,7 @@ function typeMapForStatus(status) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/web";
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.6.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var HttpClient = class {
   constructor(config) {
@@ -78,7 +78,8 @@ var HttpClient = class {
       response = await fetch(url, {
         method,
         headers,
-        body: bodyInit
+        body: bodyInit,
+        keepalive: options.keepalive === true
       });
     } catch (err) {
       throw new CrossdeckError({
@@ -123,19 +124,25 @@ var HttpClient = class {
 var KEY_ANON = "anon_id";
 var KEY_CDCUST = "cdcust_id";
 var IdentityStore = class {
-  constructor(storage, prefix) {
-    this.storage = storage;
+  constructor(primary, prefix, secondary) {
+    this.primary = primary;
     this.prefix = prefix;
-    const stored = {
-      anon: storage.getItem(prefix + KEY_ANON),
-      cdcust: storage.getItem(prefix + KEY_CDCUST)
-    };
+    this.secondary = secondary ?? null;
+    const anonFromPrimary = primary.getItem(prefix + KEY_ANON);
+    const cdcustFromPrimary = primary.getItem(prefix + KEY_CDCUST);
+    const anonFromSecondary = this.secondary?.getItem(prefix + KEY_ANON) ?? null;
+    const cdcustFromSecondary = this.secondary?.getItem(prefix + KEY_CDCUST) ?? null;
+    const anon = anonFromPrimary ?? anonFromSecondary;
+    const cdcust = cdcustFromPrimary ?? cdcustFromSecondary;
     this.state = {
-      anonymousId: stored.anon ?? this.mintAnonymousId(),
-      crossdeckCustomerId: stored.cdcust
+      anonymousId: anon ?? this.mintAnonymousId(),
+      crossdeckCustomerId: cdcust
     };
-    if (!stored.anon) {
-      storage.setItem(prefix + KEY_ANON, this.state.anonymousId);
+    if (!anonFromPrimary || !anonFromSecondary) {
+      this.writeBoth(prefix + KEY_ANON, this.state.anonymousId);
+    }
+    if (cdcust && (!cdcustFromPrimary || !cdcustFromSecondary)) {
+      this.writeBoth(prefix + KEY_CDCUST, cdcust);
     }
   }
   /** Return the persisted anonymous device ID (always set). */
@@ -149,7 +156,7 @@ var IdentityStore = class {
   /** Persist a newly-resolved Crossdeck customer ID. */
   setCrossdeckCustomerId(value) {
     this.state.crossdeckCustomerId = value;
-    this.storage.setItem(this.prefix + KEY_CDCUST, value);
+    this.writeBoth(this.prefix + KEY_CDCUST, value);
   }
   /**
    * Wipe persisted identity. Called by reset() — used when an end-user
@@ -157,13 +164,13 @@ var IdentityStore = class {
    * pre-login session is a fresh customer in the identity graph.
    */
   reset() {
-    this.storage.removeItem(this.prefix + KEY_ANON);
-    this.storage.removeItem(this.prefix + KEY_CDCUST);
+    this.deleteBoth(this.prefix + KEY_ANON);
+    this.deleteBoth(this.prefix + KEY_CDCUST);
     this.state = {
       anonymousId: this.mintAnonymousId(),
       crossdeckCustomerId: null
     };
-    this.storage.setItem(this.prefix + KEY_ANON, this.state.anonymousId);
+    this.writeBoth(this.prefix + KEY_ANON, this.state.anonymousId);
   }
   /**
    * Generate an anonymousId. Crockford-ish base32 timestamp + random
@@ -175,6 +182,30 @@ var IdentityStore = class {
     const rand = randomChars(10);
     return `anon_${ts}${rand}`;
   }
+  writeBoth(key, value) {
+    try {
+      this.primary.setItem(key, value);
+    } catch {
+    }
+    if (this.secondary) {
+      try {
+        this.secondary.setItem(key, value);
+      } catch {
+      }
+    }
+  }
+  deleteBoth(key) {
+    try {
+      this.primary.removeItem(key);
+    } catch {
+    }
+    if (this.secondary) {
+      try {
+        this.secondary.removeItem(key);
+      } catch {
+      }
+    }
+  }
 };
 function randomChars(count) {
   const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
@@ -303,8 +334,12 @@ 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.
+   *
+   * `options.keepalive` marks the underlying fetch as keepalive so the
+   * browser keeps the request alive past page unload. Use this for
+   * terminal flushes (pagehide / visibilitychange→hidden / beforeunload).
    */
-  async flush() {
+  async flush(options = {}) {
     if (this.buffer.length === 0) return null;
     this.cancelTimerIfSet();
     const batch = this.buffer.splice(0);
@@ -320,7 +355,8 @@ var EventQueue = class {
           environment: env.environment,
           sdk: env.sdk,
           events: batch
-        }
+        },
+        keepalive: options.keepalive === true
       });
       this.lastFlushAt = Date.now();
       this.lastError = null;
@@ -395,6 +431,59 @@ var MemoryStorage = class {
     this.store.delete(key);
   }
 };
+var CookieStorage = class {
+  constructor(options) {
+    this.maxAgeSec = options?.maxAgeSec ?? 63072e3;
+    this.secure = options?.secure ?? defaultSecure();
+    this.sameSite = options?.sameSite ?? "Lax";
+  }
+  getItem(key) {
+    if (!hasDocument()) return null;
+    const doc = globalThis.document;
+    const cookies = doc.cookie ? doc.cookie.split(/;\s*/) : [];
+    const prefix = encodeURIComponent(key) + "=";
+    for (const c of cookies) {
+      if (c.startsWith(prefix)) {
+        try {
+          return decodeURIComponent(c.slice(prefix.length));
+        } catch {
+          return null;
+        }
+      }
+    }
+    return null;
+  }
+  setItem(key, value) {
+    if (!hasDocument()) return;
+    const doc = globalThis.document;
+    const parts = [
+      `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,
+      "Path=/",
+      `Max-Age=${this.maxAgeSec}`,
+      `SameSite=${this.sameSite}`
+    ];
+    if (this.secure) parts.push("Secure");
+    try {
+      doc.cookie = parts.join("; ");
+    } catch {
+    }
+  }
+  removeItem(key) {
+    if (!hasDocument()) return;
+    const doc = globalThis.document;
+    const parts = [
+      `${encodeURIComponent(key)}=`,
+      "Path=/",
+      "Max-Age=0",
+      `SameSite=${this.sameSite}`
+    ];
+    if (this.secure) parts.push("Secure");
+    try {
+      doc.cookie = parts.join("; ");
+    } catch {
+    }
+  }
+};
 function detectDefaultStorage() {
   try {
     const ls = globalThis.localStorage;
@@ -408,6 +497,17 @@ function detectDefaultStorage() {
   }
   return new MemoryStorage();
 }
+function defaultSecure() {
+  try {
+    const loc = globalThis.location;
+    return loc?.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function hasDocument() {
+  return typeof globalThis.document !== "undefined";
+}
 
 // src/device-info.ts
 function isBrowser() {
@@ -508,6 +608,14 @@ var DEFAULT_AUTO_TRACK = {
   deviceInfo: true
 };
 var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
+var EMPTY_ACQUISITION = {
+  utm_source: "",
+  utm_medium: "",
+  utm_campaign: "",
+  utm_content: "",
+  utm_term: "",
+  referrer: ""
+};
 var AutoTracker = class {
   constructor(cfg, track) {
     this.cfg = cfg;
@@ -543,6 +651,18 @@ var AutoTracker = class {
   get currentSessionId() {
     return this.session?.sessionId ?? null;
   }
+  /**
+   * Per-session acquisition context — utm_* + referrer, captured once
+   * at session start. Returns empty strings when there's no session
+   * (Node, before init, after uninstall) so callers can spread without
+   * conditional logic. Bank-grade rule: capture once, attach to every
+   * event of the session, don't re-read on every track() (the URL
+   * changes via SPA pushState; the source-of-record is the URL we
+   * landed on).
+   */
+  get currentAcquisition() {
+    return this.session?.acquisition ?? EMPTY_ACQUISITION;
+  }
   // ---------- sessions ----------
   installSessionTracking() {
     this.session = this.startNewSession();
@@ -580,7 +700,8 @@ var AutoTracker = class {
       sessionId: mintSessionId(),
       startedAt: Date.now(),
       hiddenAt: null,
-      endedSent: false
+      endedSent: false,
+      acquisition: captureAcquisition()
     };
   }
   emitSessionStart() {
@@ -646,6 +767,26 @@ function mintSessionId() {
   const ts = Date.now().toString(36);
   return `sess_${ts}${randomChars(10)}`;
 }
+function captureAcquisition() {
+  if (!isBrowserSafe()) return { ...EMPTY_ACQUISITION };
+  const result = { ...EMPTY_ACQUISITION };
+  try {
+    const w = globalThis.window;
+    const params = new URLSearchParams(w.location.search ?? "");
+    result.utm_source = params.get("utm_source") ?? "";
+    result.utm_medium = params.get("utm_medium") ?? "";
+    result.utm_campaign = params.get("utm_campaign") ?? "";
+    result.utm_content = params.get("utm_content") ?? "";
+    result.utm_term = params.get("utm_term") ?? "";
+  } catch {
+  }
+  try {
+    const doc = globalThis.document;
+    if (typeof doc.referrer === "string") result.referrer = doc.referrer;
+  } catch {
+  }
+  return result;
+}
 
 // src/debug.ts
 var SENSITIVE_KEY_PATTERNS = [
@@ -750,7 +891,11 @@ var CrossdeckClient = class {
       storagePrefix: options.storagePrefix ?? "crossdeck:",
       autoHeartbeat: options.autoHeartbeat ?? true,
       eventFlushBatchSize: options.eventFlushBatchSize ?? 20,
-      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 5e3,
+      // 1500ms idle window. Short enough that an event queued on page
+      // load still flushes if the user leaves quickly (the keepalive
+      // pagehide handler picks up anything that doesn't); long enough
+      // that bursts of clicks coalesce into one network round-trip.
+      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 1500,
       sdkVersion: options.sdkVersion ?? SDK_VERSION,
       autoTrack,
       appVersion: options.appVersion ?? null
@@ -763,7 +908,10 @@ var CrossdeckClient = class {
       sdkVersion: opts.sdkVersion
     });
     const effectiveStorage = persistIdentity ? storage : new MemoryStorage();
-    const identity = new IdentityStore(effectiveStorage, opts.storagePrefix);
+    const useCookieRedundancy = persistIdentity && !options.storage && // honour caller's adapter choice
+    typeof globalThis.document !== "undefined";
+    const cookieStore = useCookieRedundancy ? new CookieStorage() : void 0;
+    const identity = new IdentityStore(effectiveStorage, opts.storagePrefix, cookieStore);
     const entitlements = new EntitlementCache();
     const events = new EventQueue({
       http,
@@ -792,7 +940,8 @@ var CrossdeckClient = class {
       deviceInfo,
       options: opts,
       debug,
-      developerUserId: null
+      developerUserId: null,
+      uninstallUnloadFlush: null
     };
     debug.emit("sdk.configured", `Crossdeck connected to ${opts.appId} in ${opts.environment} mode.`, {
       appId: opts.appId,
@@ -807,6 +956,9 @@ var CrossdeckClient = class {
       this.state.autoTracker = tracker;
       tracker.install();
     }
+    this.state.uninstallUnloadFlush = installUnloadFlush(() => {
+      void this.flush({ keepalive: true }).catch(() => void 0);
+    });
     if (opts.autoHeartbeat) {
       void this.heartbeat().catch(() => void 0);
     }
@@ -940,6 +1092,15 @@ var CrossdeckClient = class {
     const enriched = { ...s.deviceInfo };
     const sessionId = s.autoTracker?.currentSessionId;
     if (sessionId) enriched.sessionId = sessionId;
+    const acquisition = s.autoTracker?.currentAcquisition;
+    if (acquisition) {
+      if (acquisition.utm_source) enriched.utm_source = acquisition.utm_source;
+      if (acquisition.utm_medium) enriched.utm_medium = acquisition.utm_medium;
+      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 (properties) Object.assign(enriched, properties);
     const event = {
       eventId: this.mintEventId(),
@@ -953,11 +1114,16 @@ var CrossdeckClient = class {
   /**
    * Force-flush queued events. Useful to call from page-unload handlers.
    *
+   * Pass `{ keepalive: true }` from terminal handlers (pagehide /
+   * visibilitychange→hidden / beforeunload). The browser keeps the
+   * request alive after the page tears down, so the final batch
+   * actually lands instead of being cancelled with the unload.
+   *
    * NorthStar §4: standard method name across all Crossdeck SDKs.
    */
-  async flush() {
+  async flush(options = {}) {
     const s = this.requireStarted();
-    await s.events.flush();
+    await s.events.flush(options);
   }
   /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
   async flushEvents() {
@@ -1140,6 +1306,23 @@ function resolveAutoTrack(input) {
     deviceInfo: input.deviceInfo ?? DEFAULT_AUTO_TRACK.deviceInfo
   };
 }
+function installUnloadFlush(onUnload) {
+  const w = globalThis.window;
+  const doc = globalThis.document;
+  if (!w || !doc) return () => void 0;
+  const onVisChange = () => {
+    if (doc.visibilityState === "hidden") onUnload();
+  };
+  const onTerminal = () => onUnload();
+  doc.addEventListener("visibilitychange", onVisChange);
+  w.addEventListener("pagehide", onTerminal);
+  w.addEventListener("beforeunload", onTerminal);
+  return () => {
+    doc.removeEventListener("visibilitychange", onVisChange);
+    w.removeEventListener("pagehide", onTerminal);
+    w.removeEventListener("beforeunload", onTerminal);
+  };
+}
 export {
   Crossdeck,
   CrossdeckClient,