@cross-deck/web 1.5.7 → 1.6.1

package/dist/error-codes.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-05-28T10:12:32.123Z",
+  "generatedAt": "2026-05-30T11:19:57.320Z",
   "sdk": "@cross-deck/web",
   "codes": [
     {

package/dist/index.cjs

@@ -99,7 +99,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.5.7";
+var SDK_VERSION = "1.6.1";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -1448,6 +1448,8 @@ var DEFAULT_AUTO_TRACK = {
   errors: true
 };
 var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
+var SESSION_STORAGE_KEY = "crossdeck:session";
+var ACTIVITY_PERSIST_THROTTLE_MS = 5e3;
 var EMPTY_ACQUISITION = {
   utm_source: "",
   utm_medium: "",
@@ -1463,11 +1465,13 @@ var EMPTY_ACQUISITION = {
   twclid: ""
 };
 var AutoTracker = class {
-  constructor(cfg, track) {
+  constructor(cfg, track, opts) {
     this.cfg = cfg;
     this.track = track;
     this.session = null;
     this.cleanups = [];
+    /** Last time we flushed lastActivityAt to storage (throttle gate). */
+    this.lastPersistAt = 0;
     /**
      * Stable per-page-view identifier. Minted at every `page.viewed`
      * emission and attached to every subsequent event until the next
@@ -1479,6 +1483,8 @@ var AutoTracker = class {
      * install if `autoTrack.pageViews !== false`).
      */
     this.pageviewId = null;
+    this.storage = opts?.storage ?? null;
+    this.sessionKey = opts?.storageKey ?? SESSION_STORAGE_KEY;
   }
   install() {
     if (!isBrowserSafe()) return;
@@ -1497,6 +1503,7 @@ var AutoTracker = class {
     if (this.session && !this.session.endedSent) {
       this.emitSessionEnd();
     }
+    this.clearStoredSession();
     this.session = null;
   }
   /** Exposed for tests + consumers that want to reset the session manually. */
@@ -1504,8 +1511,24 @@ var AutoTracker = class {
     if (this.session && !this.session.endedSent) this.emitSessionEnd();
     this.pageviewId = null;
     this.session = this.startNewSession();
+    this.persistSession();
     this.emitSessionStart();
   }
+  /**
+   * Keep the rolling session window alive. Called by the host on EVERY
+   * tracked event (auto or custom) so any activity — not just the
+   * pageviews/clicks AutoTracker emits itself — pushes the 30-min idle
+   * boundary forward. In-memory time is updated exactly; the storage
+   * flush is throttled (pagehide forces a final flush).
+   */
+  markActivity() {
+    if (!this.session) return;
+    const now = Date.now();
+    this.session.lastActivityAt = now;
+    if (now - this.lastPersistAt >= ACTIVITY_PERSIST_THROTTLE_MS) {
+      this.persistSession();
+    }
+  }
   /** Exposed for inspection/tests — returns the current sessionId (or null if not in a session). */
   get currentSessionId() {
     return this.session?.sessionId ?? null;
@@ -1528,26 +1551,43 @@ var AutoTracker = class {
   }
   // ---------- sessions ----------
   installSessionTracking() {
-    this.session = this.startNewSession();
-    this.emitSessionStart();
+    const now = Date.now();
+    const stored = this.readStoredSession();
+    if (stored && now - stored.lastActivityAt < SESSION_RESUME_THRESHOLD_MS) {
+      this.session = {
+        sessionId: stored.id,
+        startedAt: stored.startedAt,
+        lastActivityAt: now,
+        hiddenAt: null,
+        endedSent: false,
+        acquisition: stored.acquisition
+      };
+      this.persistSession();
+    } else {
+      this.session = this.startNewSession();
+      this.persistSession();
+      this.emitSessionStart();
+    }
     const onVisChange = () => {
       if (!this.session) return;
       const doc2 = globalThis.document;
       if (doc2.visibilityState === "hidden") {
         this.session.hiddenAt = Date.now();
+        this.persistSession();
       } else if (doc2.visibilityState === "visible") {
-        const hiddenFor = this.session.hiddenAt ? Date.now() - this.session.hiddenAt : 0;
-        if (hiddenFor >= SESSION_RESUME_THRESHOLD_MS) {
+        const idleFor = Date.now() - this.session.lastActivityAt;
+        if (idleFor >= SESSION_RESUME_THRESHOLD_MS) {
           this.emitSessionEnd();
           this.pageviewId = null;
           this.session = this.startNewSession();
+          this.persistSession();
           this.emitSessionStart();
         } else {
           this.session.hiddenAt = null;
         }
       }
     };
-    const onPageHide = () => this.emitSessionEnd();
+    const onPageHide = () => this.persistSession();
     const w = globalThis.window;
     const doc = globalThis.document;
     doc.addEventListener("visibilitychange", onVisChange);
@@ -1560,14 +1600,63 @@ var AutoTracker = class {
     });
   }
   startNewSession() {
+    const now = Date.now();
     return {
       sessionId: mintSessionId(),
-      startedAt: Date.now(),
+      startedAt: now,
+      lastActivityAt: now,
       hiddenAt: null,
       endedSent: false,
       acquisition: captureAcquisition()
     };
   }
+  /**
+   * Read the persisted session continuity record. Returns null on no
+   * storage, no record, malformed JSON, or a record missing its required
+   * fields — every failure degrades to "no session to resume", which is
+   * the safe (start-fresh) path.
+   */
+  readStoredSession() {
+    if (!this.storage) return null;
+    try {
+      const raw = this.storage.getItem(this.sessionKey);
+      if (!raw) return null;
+      const p = JSON.parse(raw);
+      if (!p || typeof p.id !== "string" || typeof p.startedAt !== "number" || typeof p.lastActivityAt !== "number") {
+        return null;
+      }
+      return {
+        id: p.id,
+        startedAt: p.startedAt,
+        lastActivityAt: p.lastActivityAt,
+        acquisition: p.acquisition && typeof p.acquisition === "object" ? p.acquisition : EMPTY_ACQUISITION
+      };
+    } catch {
+      return null;
+    }
+  }
+  /** Flush the current session to storage. No-op without storage/session. */
+  persistSession() {
+    if (!this.storage || !this.session) return;
+    this.lastPersistAt = Date.now();
+    try {
+      const rec = {
+        id: this.session.sessionId,
+        startedAt: this.session.startedAt,
+        lastActivityAt: this.session.lastActivityAt,
+        acquisition: this.session.acquisition
+      };
+      this.storage.setItem(this.sessionKey, JSON.stringify(rec));
+    } catch {
+    }
+  }
+  clearStoredSession() {
+    if (!this.storage) return;
+    try {
+      this.storage.removeItem(this.sessionKey);
+    } catch {
+    }
+  }
   emitSessionStart() {
     if (!this.session) return;
     this.track("session.started", { sessionId: this.session.sessionId });
@@ -1739,6 +1828,78 @@ function isInsidePasswordField(el) {
   if (el.closest('input[type="password"]')) return true;
   return false;
 }
+var INLINE_LABEL_TAGS = /* @__PURE__ */ new Set([
+  "span",
+  "b",
+  "strong",
+  "em",
+  "i",
+  "small",
+  "mark",
+  "u",
+  "label",
+  "abbr",
+  "time",
+  "bdi",
+  "cite",
+  "code",
+  "kbd",
+  "q",
+  "sub",
+  "sup"
+]);
+var NON_LABEL_SUBTREES = /* @__PURE__ */ new Set(["svg", "style", "script", "noscript"]);
+var CONTAINER_MARKERS = "a[href], button, input, select, textarea, [role='button'], [role='link'], h1, h2, h3, h4, h5, h6";
+var HEADING_SELECTOR = "h1, h2, h3, h4, h5, h6";
+function collapseWs(s) {
+  return s.replace(/\s+/g, " ").trim();
+}
+function boundaryText(el) {
+  let out = "";
+  const walk = (node) => {
+    const kids = node.childNodes;
+    for (let i = 0; i < kids.length; i++) {
+      const child = kids[i];
+      if (!child) continue;
+      if (child.nodeType === 3) {
+        out += child.textContent || "";
+      } else if (child.nodeType === 1) {
+        if (NON_LABEL_SUBTREES.has(child.tagName.toLowerCase())) continue;
+        out += " ";
+        walk(child);
+        out += " ";
+      }
+    }
+  };
+  walk(el);
+  return collapseWs(out);
+}
+function directLabel(el) {
+  let out = "";
+  const kids = el.childNodes;
+  for (let i = 0; i < kids.length; i++) {
+    const child = kids[i];
+    if (!child) continue;
+    if (child.nodeType === 3) {
+      out += " " + (child.textContent || "");
+    } else if (child.nodeType === 1 && INLINE_LABEL_TAGS.has(child.tagName.toLowerCase())) {
+      out += " " + boundaryText(child);
+    }
+  }
+  return collapseWs(out);
+}
+function visibleLabel(el) {
+  const isContainer = el.querySelector(CONTAINER_MARKERS) !== null;
+  if (!isContainer) return boundaryText(el);
+  const direct = directLabel(el);
+  if (direct) return direct;
+  const heading = el.querySelector(HEADING_SELECTOR);
+  if (heading) {
+    const h = boundaryText(heading);
+    if (h) return h;
+  }
+  return "";
+}
 function extractText(el) {
   const clean = (s) => s.replace(/\s+/g, " ").trim();
   const explicit = el.getAttribute("data-cd-track") || el.getAttribute("data-track") || el.getAttribute("data-testid");
@@ -1765,7 +1926,7 @@ function extractText(el) {
     const t = clean(el.value);
     if (t) return t;
   }
-  const text = clean(el.textContent || "");
+  const text = visibleLabel(el);
   if (text) return text;
   const title = el.getAttribute("title");
   if (title) {
@@ -3312,19 +3473,58 @@ var DEFAULT_ERROR_CAPTURE = {
     "ResizeObserver loop completed with undelivered notifications",
     "Non-Error promise rejection captured"
     // NOTE: We deliberately do NOT drop cross-origin "Script error."
-    // events here. They used to be silently filtered as noise, but
-    // silent drops are the opposite of "developer sleeps well at
-    // night". We now capture them with a clear label and the
-    // `cross_origin` tag so the dashboard surfaces them as a
-    // distinct, actionable category (the fix is always the same —
-    // add `crossorigin="anonymous"` to the script tag + CORS
-    // headers on the script's origin). Apps that genuinely want
-    // them muted can re-add "Script error" to ignoreErrors via
-    // init config.
+    // events here. The actionability principle (see denyUrls
+    // comment below) draws the line at "developer cannot act":
+    // cross-origin CORS opacity HAS a real, code-shaped fix (add
+    // `crossorigin="anonymous"` to the script tag + CORS headers
+    // on the script's origin). The dashboard surfaces these with a
+    // `cross_origin` tag pointing at that fix. Apps that genuinely
+    // want them muted can re-add "Script error" to ignoreErrors
+    // via init config.
   ],
   allowUrls: [],
   denyUrls: [
-    // Common third-party extensions that pollute error streams.
+    // The actionability principle
+    // ---------------------------
+    // Crossdeck's default philosophy is "classify, don't silently
+    // drop" — surfacing errors the developer can fix is more useful
+    // than hiding them. That's right for cross-origin "Script
+    // error." (real, code-shaped CORS fix) and for plain
+    // application bugs (obviously real).
+    //
+    // It's NOT right for events the developer cannot act on.
+    //   - A user's installed browser extension throwing inside
+    //     its own `chrome-extension://` URL: the developer can't
+    //     ship a fix for someone else's extension.
+    //   - An ad blocker preventing `googletagmanager.com` from
+    //     loading: the developer can't unblock the user's blocker.
+    //
+    // Capturing these creates a noise tab that's always non-empty
+    // and never actionable, which trains the dev to ignore the
+    // noise tab — and then the actionable noise (CORS opacity,
+    // etc.) gets ignored along with it. Same lesson as Crossdeck's
+    // "0-2 notifications a week" discipline: a signal that fires
+    // constantly with nothing actionable behind it stops being a
+    // signal.
+    //
+    // So we drop at the source for the unactionable category, and
+    // keep capturing for the actionable category. Same principle
+    // applied to two structurally different inputs — not a new
+    // philosophy.
+    //
+    // The bootstrap list below is the minimum that ships in code.
+    // The full, versioned list arrives at boot via /v1/config —
+    // see `backend/src/lib/error-noise-deny-list.ts`. The SDK
+    // applies the union of (bootstrap + remote), so a freshly-
+    // installed SDK protects users immediately, and remote updates
+    // (new ad-network domains, new pixel hosts) reach every
+    // install without an SDK release.
+    //
+    // The backend Layer-2 classifier
+    // (`backend/src/api/lib/noise-classifier.ts`) is the safety
+    // net for events that slip past these patterns — older SDK
+    // versions in the wild that haven't fetched the remote list
+    // yet, or brand-new patterns the list hasn't named.
     /^chrome-extension:\/\//,
     /^moz-extension:\/\//,
     /^safari-extension:\/\//,
@@ -4117,7 +4317,12 @@ var CrossdeckClient = class {
     if (autoTrack.sessions || autoTrack.pageViews) {
       const tracker = new AutoTracker(
         autoTrack,
-        (name, properties) => this.track(name, properties)
+        (name, properties) => this.track(name, properties),
+        // Persist session continuity on the SAME adapter as identity, so
+        // a visit survives full-page navigations (multi-page sites
+        // re-install the SDK on every page) and honours the same consent
+        // posture — MemoryStorage when identity persistence is off.
+        { storage: effectiveStorage, storageKey: opts.storagePrefix + "session" }
       );
       this.state.autoTracker = tracker;
       tracker.install();
@@ -4582,6 +4787,12 @@ var CrossdeckClient = class {
    * true even before the session's first network round-trip. Returns
    * false only for a genuinely new install that has never completed a
    * getEntitlements(), or for an entitlement past its own validUntil.
+   *
+   * Throws `not_initialized` (CrossdeckError, type
+   * `configuration_error`) if called before `Crossdeck.init()`. The
+   * `useEntitlement` React hook and the Vue composable both swallow
+   * this and return `false`; bare callers must guard for it (or call
+   * after `init()` resolves).
    */
   isEntitled(key) {
     const s = this.requireStarted();
@@ -4597,8 +4808,21 @@ var CrossdeckClient = class {
    *
    * The listener is invoked AFTER the cache mutates — once after a
    * successful `getEntitlements()` warms it, again after `syncPurchases()`
-   * delivers fresh entitlements, and once on `reset()` to fire the
-   * empty-cache state for logout flows.
+   * delivers fresh entitlements, once on `reset()` to fire the empty-
+   * cache state for logout flows, AND once on `identify()` after the
+   * per-user cache slot rotates and re-hydrates from device storage.
+   *
+   * IMPORTANT — the `identify()` fire is a TRAP if you treat it as
+   * authoritative network state. `identify()` does NOT fetch entitlements;
+   * it switches the per-user cache slot and rehydrates from device
+   * storage (which is empty for a brand-new install, and last-known-good
+   * — possibly stale — for a returning user). A listener that gates a
+   * paywall on the first fire after an identity switch will read
+   * `false` for a paying customer on a fresh device and let them past
+   * the gate as free. The network-truth fire is the one that follows
+   * the next `getEntitlements()` resolution. Either call
+   * `getEntitlements()` explicitly after `identify()`, or have your
+   * gating code tolerate the empty-then-populated transition.
    *
    * It is NOT invoked synchronously on subscribe. Callers that need
    * the current state should read it via `isEntitled()` / `listEntitlements()`
@@ -4707,6 +4931,7 @@ var CrossdeckClient = class {
         );
       }
     }
+    s.autoTracker?.markActivity();
     const enriched = { ...s.deviceInfo };
     const sessionId = s.autoTracker?.currentSessionId;
     if (sessionId) enriched.sessionId = sessionId;
@@ -4961,6 +5186,25 @@ var CrossdeckClient = class {
       events: s.events.getStats()
     };
   }
+  /**
+   * The stable reference to hand Stripe at checkout so the resulting
+   * purchase attributes to THIS person. Stamp it on the Checkout Session
+   * as `metadata.crossdeck_ref` (see docs/connect-stripe) — the platform
+   * webhook reads it back, validates it, and attaches the subscription to
+   * the right customer instead of stranding it on an anonymous record.
+   *
+   * Returns the strongest identifier the SDK currently holds, in the same
+   * precedence the server resolves by:
+   *   crossdeckCustomerId (cdcust_…) > developerUserId > anonymousId
+   * anonymousId is always present, so this always returns a usable,
+   * non-empty reference — even before identify(). Identify the user as
+   * early as you can, though, so the reference is their stable identity
+   * and not a per-device anon id.
+   */
+  getCheckoutReference() {
+    const s = this.requireStarted();
+    return s.identity.crossdeckCustomerId ?? s.developerUserId ?? s.identity.anonymousId;
+  }
   // ---------- private helpers ----------
   requireStarted() {
     if (!this.state) {
@@ -5282,8 +5526,8 @@ function getErrorCode(code) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/web@1.5.7";
-var SDK_VERSION2 = "1.5.7";
+var BUNDLED_IN = "@cross-deck/web@1.6.1";
+var SDK_VERSION2 = "1.6.1";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -5405,7 +5649,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "error-envelope-shape",
@@ -5444,7 +5688,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "flush-interval-parity",
@@ -5489,7 +5733,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "idempotency-key-deterministic",
@@ -5594,7 +5838,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 2.2.a + 2.2.b + 2.2.c",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "init-reentry-drains-prior-queue",
@@ -5621,7 +5865,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "per-user-cache-isolation",
@@ -5700,7 +5944,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "sdk-error-codes-catalogue",
@@ -5740,7 +5984,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   },
   {
     "id": "sync-purchases-funnel-parity",
@@ -5773,7 +6017,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/web@1.5.7"
+    "bundledIn": "@cross-deck/web@1.6.1"
   }
 ]);