@cross-deck/web 1.5.7 → 1.6.2

package/dist/react.mjs

@@ -67,7 +67,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.5.7";
+var SDK_VERSION = "1.6.2";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -1416,6 +1416,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: "",
@@ -1431,11 +1433,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
@@ -1447,6 +1451,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;
@@ -1465,6 +1471,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. */
@@ -1472,8 +1479,31 @@ 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();
+    if (now - this.session.lastActivityAt >= SESSION_RESUME_THRESHOLD_MS) {
+      this.pageviewId = null;
+      this.session = this.startNewSession();
+      this.persistSession();
+      this.emitSessionStart();
+      return;
+    }
+    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;
@@ -1496,26 +1526,42 @@ 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) {
-          this.emitSessionEnd();
+        const idleFor = Date.now() - this.session.lastActivityAt;
+        if (idleFor >= SESSION_RESUME_THRESHOLD_MS) {
           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);
@@ -1528,14 +1574,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 });
@@ -1707,6 +1802,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");
@@ -1733,7 +1900,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) {
@@ -2446,6 +2613,210 @@ function sendDiagnosticTelemetry(payload) {
   }
 }
 
+// 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
+  },
+  // ----- Backend-emitted codes (v1.4.0 Phase 6.2 backfill) -----
+  // Mirror of backend/src/api/v1-errors.ts ApiErrorCode. A developer
+  // hitting any of these on the wire can look them up via
+  // getErrorCode(code) for a canonical remediation step instead of
+  // hunting through Slack history.
+  {
+    code: "missing_api_key",
+    type: "authentication_error",
+    description: "No Authorization header (or Crossdeck-Api-Key header) on the request.",
+    resolution: "Make sure Crossdeck.init({ publicKey }) was called with a cd_pub_\u2026 key before the request fired. Re-check your env-vars in CI / Docker if the key is empty at runtime.",
+    retryable: false
+  },
+  {
+    code: "invalid_api_key",
+    type: "authentication_error",
+    description: "The API key is malformed, unknown, or doesn't resolve to a project.",
+    resolution: "Copy the key from your Crossdeck dashboard \u2192 API keys. Confirm prefix is cd_pub_test_ / cd_pub_live_ for client SDKs and cd_sk_test_ / cd_sk_live_ for the Node server SDK.",
+    retryable: false
+  },
+  {
+    code: "key_revoked",
+    type: "authentication_error",
+    description: "The API key was revoked in the Crossdeck dashboard.",
+    resolution: "Mint a fresh key in the dashboard \u2192 API keys \u2192 Create new, swap it in, and redeploy. The revoked key cannot be reactivated.",
+    retryable: false
+  },
+  {
+    code: "identity_token_invalid",
+    type: "authentication_error",
+    description: "The Firebase / Apple / Google ID token supplied with the request didn't verify against the dashboard's configured signers.",
+    resolution: "Refresh the token client-side (Firebase auth.currentUser.getIdToken(true)) and retry. If the failure persists, confirm the signer is registered under dashboard \u2192 Authentication \u2192 Identity sources.",
+    retryable: true
+  },
+  {
+    code: "origin_not_allowed",
+    type: "permission_error",
+    description: "The Origin header isn't in the project's Allowed origins list.",
+    resolution: "Add the origin (e.g. https://app.example.com) under dashboard \u2192 Settings \u2192 Allowed origins. Wildcards like https://*.example.com are supported.",
+    retryable: false
+  },
+  {
+    code: "bundle_id_not_allowed",
+    type: "permission_error",
+    description: "The iOS bundle ID sent via X-Crossdeck-Bundle-Id isn't registered under this app's Apple identity lock.",
+    resolution: "Add the bundle ID under dashboard \u2192 Apps \u2192 <your app> \u2192 iOS bundle IDs.",
+    retryable: false
+  },
+  {
+    code: "package_name_not_allowed",
+    type: "permission_error",
+    description: "The Android package name sent via X-Crossdeck-Package-Name isn't registered under this app's Android identity lock.",
+    resolution: "Add the package name under dashboard \u2192 Apps \u2192 <your app> \u2192 Android package names.",
+    retryable: false
+  },
+  {
+    code: "env_mismatch",
+    type: "permission_error",
+    description: "The request env (inferred from key prefix) doesn't match the resolved app's configured env.",
+    resolution: "Use a cd_pub_live_ / cd_sk_live_ key with a production app, cd_pub_test_ / cd_sk_test_ with a sandbox app. The two cannot cross.",
+    retryable: false
+  },
+  {
+    code: "idempotency_key_in_use",
+    type: "invalid_request_error",
+    description: "An Idempotency-Key was reused for a request with a different body (Stripe-grade contract).",
+    resolution: "Generate a fresh key for a different transaction, or reuse the key only with the EXACT same body. The v1.4.0 SDKs derive keys deterministically from the body so this should never fire on SDK-managed calls.",
+    retryable: false
+  },
+  {
+    code: "rate_limited",
+    type: "rate_limit_error",
+    description: "Request rate exceeded the project's per-second cap.",
+    resolution: "Honour the Retry-After header \u2014 the SDK does this automatically on managed retries. If you're hitting it from a custom code path, throttle to <100 req/s/key.",
+    retryable: true
+  },
+  {
+    code: "internal_error",
+    type: "internal_error",
+    description: "Server-side issue. Safe to retry with backoff.",
+    resolution: "The SDK retries automatically. If your code paths through to this error, contact support with the requestId from the response envelope.",
+    retryable: true
+  },
+  {
+    code: "google_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=google is gated until the Play Developer API reconciliation worker ships.",
+    resolution: "Until v1.5+, Google Play purchases verify via Real-time Developer Notifications. The SDK auto-track path handles this transparently for Android consumers.",
+    retryable: false
+  },
+  {
+    code: "stripe_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=stripe is unsupported \u2014 Stripe Checkout's redirect flow uses platform webhooks instead.",
+    resolution: "Wire Stripe via the standard Checkout / Customer Portal flow; Crossdeck reconciles via the platform webhook automatically. No SDK call needed.",
+    retryable: false
+  },
+  {
+    code: "missing_required_param",
+    type: "invalid_request_error",
+    description: "A required field is absent from the request body.",
+    resolution: "Inspect the error.message \u2014 the missing field name is included verbatim. Refer to the SDK's TypeScript types for the canonical request shape.",
+    retryable: false
+  },
+  {
+    code: "invalid_param_value",
+    type: "invalid_request_error",
+    description: "A field is present but the value failed validation (wrong shape, wrong length, wrong enum value).",
+    resolution: "Read error.message for the specific field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
+    retryable: false
+  }
+]);
+function getErrorCode(code) {
+  return CROSSDECK_ERROR_CODES.find((e) => e.code === code);
+}
+
 // src/_contract-verifiers.ts
 function buildVerifierContext(opts) {
   return {
@@ -2970,13 +3341,64 @@ var VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK = {
     );
   }
 };
+var BACKEND_WIRE_CODES = Object.freeze([
+  "missing_api_key",
+  "invalid_api_key",
+  "key_revoked",
+  "identity_token_invalid",
+  "origin_not_allowed",
+  "bundle_id_not_allowed",
+  "package_name_not_allowed",
+  "env_mismatch",
+  "idempotency_key_in_use",
+  "rate_limited",
+  "internal_error",
+  "google_not_supported",
+  "stripe_not_supported",
+  "missing_required_param",
+  "invalid_param_value"
+]);
+var VERIFIER_SDK_ERROR_CODES_CATALOGUE = {
+  contractId: "sdk-error-codes-catalogue",
+  bootTest() {
+    const t0 = nowMs();
+    try {
+      const missing = [];
+      for (const code of BACKEND_WIRE_CODES) {
+        const entry = getErrorCode(code);
+        if (!entry || !entry.description || entry.description.trim().length === 0 || !entry.resolution || entry.resolution.trim().length === 0) {
+          missing.push(code);
+        }
+      }
+      if (missing.length > 0) {
+        return fail(
+          "sdk-error-codes-catalogue",
+          `catalogue missing description+resolution for backend code(s): ${missing.join(", ")}`,
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "sdk-error-codes-catalogue",
+        `all ${BACKEND_WIRE_CODES.length} backend wire codes carry description + resolution`,
+        nowMs() - t0
+      );
+    } catch (err) {
+      return fail(
+        "sdk-error-codes-catalogue",
+        `boot test threw: ${err.message?.slice(0, 80) ?? "unknown error"}`,
+        nowMs() - t0
+      );
+    }
+  }
+};
 var STATIC_VERIFIERS = Object.freeze([
   VERIFIER_PER_USER_CACHE_ISOLATION,
   VERIFIER_IDEMPOTENCY_KEY_DETERMINISTIC,
   VERIFIER_ERROR_ENVELOPE_SHAPE,
   VERIFIER_FLUSH_INTERVAL_PARITY,
   VERIFIER_SUPER_PROPERTY_MERGE_PRECEDENCE,
-  VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK
+  VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK,
+  VERIFIER_SDK_ERROR_CODES_CATALOGUE
 ]);
 async function runBootSelfTest(verifiers, reporter, ctx) {
   if (ctx.disableContractAssertions) {
@@ -3280,19 +3702,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:\/\//,
@@ -4085,7 +4546,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();
@@ -4550,6 +5016,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();
@@ -4565,8 +5037,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()`
@@ -4675,6 +5160,7 @@ var CrossdeckClient = class {
         );
       }
     }
+    s.autoTracker?.markActivity();
     const enriched = { ...s.deviceInfo };
     const sessionId = s.autoTracker?.currentSessionId;
     if (sessionId) enriched.sessionId = sessionId;
@@ -4929,6 +5415,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) {