@cross-deck/web 0.3.0 → 0.5.0

package/dist/react.mjs

@@ -0,0 +1,1236 @@
+// src/react.ts
+import { useEffect, useState } from "react";
+
+// src/errors.ts
+var CrossdeckError = class _CrossdeckError extends Error {
+  constructor(payload) {
+    super(payload.message);
+    this.name = "CrossdeckError";
+    this.type = payload.type;
+    this.code = payload.code;
+    this.requestId = payload.requestId;
+    this.status = payload.status;
+    Object.setPrototypeOf(this, _CrossdeckError.prototype);
+  }
+};
+async function crossdeckErrorFromResponse(res) {
+  const requestId = res.headers.get("x-request-id") ?? void 0;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  const envelope = body?.error;
+  if (envelope && typeof envelope.type === "string" && typeof envelope.code === "string") {
+    return new CrossdeckError({
+      type: envelope.type,
+      code: envelope.code,
+      message: envelope.message ?? `HTTP ${res.status}`,
+      requestId: envelope.request_id ?? requestId,
+      status: res.status
+    });
+  }
+  return new CrossdeckError({
+    type: typeMapForStatus(res.status),
+    code: `http_${res.status}`,
+    message: `HTTP ${res.status} ${res.statusText || ""}`.trim(),
+    requestId,
+    status: res.status
+  });
+}
+function typeMapForStatus(status) {
+  if (status === 401) return "authentication_error";
+  if (status === 403) return "permission_error";
+  if (status === 429) return "rate_limit_error";
+  if (status >= 400 && status < 500) return "invalid_request_error";
+  return "internal_error";
+}
+
+// src/http.ts
+var SDK_NAME = "@cross-deck/web";
+var SDK_VERSION = "0.5.0";
+var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Issue a request. `path` is relative to the configured baseUrl
+   * ("/entitlements", "/identity/alias", etc.).
+   *
+   * Throws CrossdeckError on:
+   *   - Network failure (`type: "network_error"`)
+   *   - Non-2xx response (typed from the body envelope)
+   *   - JSON parse failure on a 2xx (treated as `internal_error`)
+   */
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const headers = {
+      Authorization: `Bearer ${this.config.publicKey}`,
+      "Crossdeck-Sdk-Version": `${SDK_NAME}@${this.config.sdkVersion}`,
+      Accept: "application/json"
+    };
+    let bodyInit;
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      bodyInit = JSON.stringify(options.body);
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: bodyInit,
+        keepalive: options.keepalive === true
+      });
+    } catch (err) {
+      throw new CrossdeckError({
+        type: "network_error",
+        code: "fetch_failed",
+        message: err instanceof Error ? err.message : "fetch failed"
+      });
+    }
+    if (!response.ok) {
+      throw await crossdeckErrorFromResponse(response);
+    }
+    if (response.status === 204) return void 0;
+    try {
+      return await response.json();
+    } catch (err) {
+      throw new CrossdeckError({
+        type: "internal_error",
+        code: "invalid_json_response",
+        message: "Server returned a 2xx with an unparseable body.",
+        requestId: response.headers.get("x-request-id") ?? void 0,
+        status: response.status
+      });
+    }
+  }
+  buildUrl(path, query) {
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    let url = base + cleanPath;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (typeof v === "string" && v.length > 0) params.append(k, v);
+      }
+      const qs = params.toString();
+      if (qs) url += (url.includes("?") ? "&" : "?") + qs;
+    }
+    return url;
+  }
+};
+
+// src/identity.ts
+var KEY_ANON = "anon_id";
+var KEY_CDCUST = "cdcust_id";
+var IdentityStore = class {
+  constructor(storage, prefix) {
+    this.storage = storage;
+    this.prefix = prefix;
+    const stored = {
+      anon: storage.getItem(prefix + KEY_ANON),
+      cdcust: storage.getItem(prefix + KEY_CDCUST)
+    };
+    this.state = {
+      anonymousId: stored.anon ?? this.mintAnonymousId(),
+      crossdeckCustomerId: stored.cdcust
+    };
+    if (!stored.anon) {
+      storage.setItem(prefix + KEY_ANON, this.state.anonymousId);
+    }
+  }
+  /** Return the persisted anonymous device ID (always set). */
+  get anonymousId() {
+    return this.state.anonymousId;
+  }
+  /** Return the resolved cross­deckCustomerId once we have one, else null. */
+  get crossdeckCustomerId() {
+    return this.state.crossdeckCustomerId;
+  }
+  /** Persist a newly-resolved Crossdeck customer ID. */
+  setCrossdeckCustomerId(value) {
+    this.state.crossdeckCustomerId = value;
+    this.storage.setItem(this.prefix + KEY_CDCUST, value);
+  }
+  /**
+   * Wipe persisted identity. Called by reset() — used when an end-user
+   * logs out. After reset the SDK mints a new anonymousId so the next
+   * 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.state = {
+      anonymousId: this.mintAnonymousId(),
+      crossdeckCustomerId: null
+    };
+    this.storage.setItem(this.prefix + KEY_ANON, this.state.anonymousId);
+  }
+  /**
+   * Generate an anonymousId. Crockford-ish base32 timestamp + random
+   * suffix. Same shape Stripe / Segment / others use — sortable, log-
+   * friendly, no PII.
+   */
+  mintAnonymousId() {
+    const ts = Date.now().toString(36);
+    const rand = randomChars(10);
+    return `anon_${ts}${rand}`;
+  }
+};
+function randomChars(count) {
+  const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+  const out = [];
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.getRandomValues) {
+    const buf = new Uint8Array(count);
+    cryptoApi.getRandomValues(buf);
+    for (let i = 0; i < count; i++) {
+      out.push(alphabet[buf[i] % alphabet.length] ?? "0");
+    }
+  } else {
+    for (let i = 0; i < count; i++) {
+      out.push(alphabet[Math.floor(Math.random() * alphabet.length)] ?? "0");
+    }
+  }
+  return out.join("");
+}
+
+// src/entitlement-cache.ts
+var EntitlementCache = class {
+  constructor() {
+    this.active = /* @__PURE__ */ new Set();
+    this.all = [];
+    this.lastUpdated = 0;
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /** Sync read — true iff the entitlement key is currently active. */
+  isEntitled(key) {
+    return this.active.has(key);
+  }
+  /** Full snapshot for callers that need source / validUntil details. */
+  list() {
+    return this.all.slice();
+  }
+  /** When the cache was last refreshed. 0 means "never". */
+  get freshness() {
+    return this.lastUpdated;
+  }
+  /**
+   * Replace the cache with a fresh server response. The backend already
+   * filters to active + env-matching, so we don't re-filter — just trust
+   * what we got.
+   *
+   * Fires listeners AFTER the mutation so each listener sees the new state.
+   */
+  setFromList(entitlements) {
+    this.all = entitlements.slice();
+    this.active = new Set(entitlements.filter((e) => e.isActive).map((e) => e.key));
+    this.lastUpdated = Date.now();
+    this.notify();
+  }
+  /**
+   * Wipe — used on reset() (logout). The SDK forgets everything until
+   * the next identify + read.
+   *
+   * Fires listeners so React/SwiftUI/etc bindings re-render to the
+   * logged-out state immediately.
+   */
+  clear() {
+    this.active.clear();
+    this.all = [];
+    this.lastUpdated = 0;
+    this.notify();
+  }
+  /**
+   * Subscribe to cache mutations. Returns an unsubscribe function.
+   *
+   * The listener is invoked AFTER setFromList() or clear() with the
+   * current snapshot. Throwing inside a listener is non-fatal — the
+   * error is swallowed and subsequent listeners still run.
+   *
+   * Used by `@cross-deck/web/react`'s `useEntitlement` hook to
+   * trigger re-renders when entitlements change.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    let unsubscribed = false;
+    return () => {
+      if (unsubscribed) return;
+      unsubscribed = true;
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    if (this.listeners.size === 0) return;
+    const snapshot = this.all.slice();
+    const listenersSnapshot = [...this.listeners];
+    for (const listener of listenersSnapshot) {
+      try {
+        listener(snapshot);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/event-queue.ts
+var HARD_BUFFER_CAP = 1e3;
+var EventQueue = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.buffer = [];
+    this.dropped = 0;
+    this.inFlight = 0;
+    this.lastFlushAt = 0;
+    this.lastError = null;
+    this.cancelTimer = null;
+    this.firstFlushFired = false;
+  }
+  enqueue(event) {
+    this.buffer.push(event);
+    if (this.buffer.length > HARD_BUFFER_CAP) {
+      const overflow = this.buffer.length - HARD_BUFFER_CAP;
+      this.buffer.splice(0, overflow);
+      this.dropped += overflow;
+      this.cfg.onDrop?.(overflow);
+    }
+    if (this.buffer.length >= this.cfg.batchSize) {
+      void this.flush();
+    } else {
+      this.scheduleIdleFlush();
+    }
+  }
+  /**
+   * 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(options = {}) {
+    if (this.buffer.length === 0) return null;
+    this.cancelTimerIfSet();
+    const batch = this.buffer.splice(0);
+    this.inFlight += batch.length;
+    try {
+      const env = this.cfg.envelope();
+      const result = await this.cfg.http.request("POST", "/events", {
+        body: {
+          // NorthStar §13.1 batch envelope. The backend validates these
+          // against the API-key-resolved app and rejects mismatches loudly
+          // (env_mismatch).
+          appId: env.appId,
+          environment: env.environment,
+          sdk: env.sdk,
+          events: batch
+        },
+        keepalive: options.keepalive === true
+      });
+      this.lastFlushAt = Date.now();
+      this.lastError = null;
+      this.inFlight -= batch.length;
+      if (!this.firstFlushFired) {
+        this.firstFlushFired = true;
+        this.cfg.onFirstFlushSuccess?.();
+      }
+      return result;
+    } catch (err) {
+      this.buffer.unshift(...batch);
+      this.inFlight -= batch.length;
+      this.lastError = err instanceof Error ? err.message : String(err);
+      this.scheduleIdleFlush();
+      return null;
+    }
+  }
+  /** Cancel any pending timer and clear in-memory state. */
+  reset() {
+    this.cancelTimerIfSet();
+    this.buffer = [];
+    this.dropped = 0;
+    this.inFlight = 0;
+    this.lastError = null;
+  }
+  getStats() {
+    return {
+      buffered: this.buffer.length,
+      dropped: this.dropped,
+      inFlight: this.inFlight,
+      lastFlushAt: this.lastFlushAt,
+      lastError: this.lastError
+    };
+  }
+  scheduleIdleFlush() {
+    this.cancelTimerIfSet();
+    const sched = this.cfg.scheduler ?? defaultScheduler;
+    this.cancelTimer = sched(() => {
+      void this.flush();
+    }, this.cfg.intervalMs);
+  }
+  cancelTimerIfSet() {
+    if (this.cancelTimer) {
+      this.cancelTimer();
+      this.cancelTimer = null;
+    }
+  }
+};
+function defaultScheduler(fn, ms) {
+  const id = setTimeout(fn, ms);
+  if (typeof id.unref === "function") {
+    try {
+      id.unref();
+    } catch {
+    }
+  }
+  return () => clearTimeout(id);
+}
+
+// src/storage.ts
+var MemoryStorage = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+};
+function detectDefaultStorage() {
+  try {
+    const ls = globalThis.localStorage;
+    if (ls) {
+      const probe = "__crossdeck_probe__";
+      ls.setItem(probe, "1");
+      ls.removeItem(probe);
+      return ls;
+    }
+  } catch {
+  }
+  return new MemoryStorage();
+}
+
+// src/device-info.ts
+function isBrowser() {
+  return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined" && typeof globalThis.navigator !== "undefined";
+}
+function collectDeviceInfo(extra) {
+  const info = {};
+  if (extra?.appVersion) info.appVersion = extra.appVersion;
+  if (!isBrowser()) return info;
+  const w = globalThis.window;
+  const nav = globalThis.navigator;
+  const doc = globalThis.document;
+  try {
+    if (typeof nav.language === "string") info.locale = nav.language;
+  } catch {
+  }
+  try {
+    info.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+  }
+  try {
+    if (w.screen) {
+      info.screenWidth = w.screen.width;
+      info.screenHeight = w.screen.height;
+    }
+    info.viewportWidth = w.innerWidth;
+    info.viewportHeight = w.innerHeight;
+    info.devicePixelRatio = w.devicePixelRatio;
+  } catch {
+  }
+  try {
+    const ua = nav.userAgent ?? "";
+    const parsed = parseUserAgent(ua);
+    Object.assign(info, parsed);
+  } catch {
+  }
+  try {
+    const uaData = nav.userAgentData;
+    if (uaData?.platform && !info.os) info.os = uaData.platform;
+    if (uaData?.brands && !info.browser) {
+      const real = uaData.brands.find(
+        (b) => !/Not[ .;A]*Brand/i.test(b.brand) && !/Chromium/i.test(b.brand)
+      );
+      if (real) {
+        info.browser = real.brand;
+        info.browserVersion = real.version;
+      }
+    }
+  } catch {
+  }
+  void doc;
+  return info;
+}
+function parseUserAgent(ua) {
+  const out = {};
+  if (/iPad|iPhone|iPod/.test(ua)) {
+    out.os = "iOS";
+    const m = ua.match(/OS (\d+[._]\d+(?:[._]\d+)?)/);
+    if (m?.[1]) out.osVersion = m[1].replace(/_/g, ".");
+  } else if (/Android/.test(ua)) {
+    out.os = "Android";
+    const m = ua.match(/Android (\d+(?:\.\d+)*)/);
+    if (m?.[1]) out.osVersion = m[1];
+  } else if (/Windows/.test(ua)) {
+    out.os = "Windows";
+    const m = ua.match(/Windows NT (\d+\.\d+)/);
+    if (m?.[1]) out.osVersion = m[1];
+  } else if (/Mac OS X|Macintosh/.test(ua)) {
+    out.os = "macOS";
+    const m = ua.match(/Mac OS X (\d+[._]\d+(?:[._]\d+)?)/);
+    if (m?.[1]) out.osVersion = m[1].replace(/_/g, ".");
+  } else if (/Linux/.test(ua)) {
+    out.os = "Linux";
+  }
+  if (/Edg\/(\d+(?:\.\d+)*)/.test(ua)) {
+    out.browser = "Edge";
+    out.browserVersion = ua.match(/Edg\/(\d+(?:\.\d+)*)/)?.[1];
+  } else if (/Firefox\/(\d+(?:\.\d+)*)/.test(ua)) {
+    out.browser = "Firefox";
+    out.browserVersion = ua.match(/Firefox\/(\d+(?:\.\d+)*)/)?.[1];
+  } else if (/OPR\/(\d+(?:\.\d+)*)/.test(ua)) {
+    out.browser = "Opera";
+    out.browserVersion = ua.match(/OPR\/(\d+(?:\.\d+)*)/)?.[1];
+  } else if (/Chrome\/(\d+(?:\.\d+)*)/.test(ua)) {
+    out.browser = "Chrome";
+    out.browserVersion = ua.match(/Chrome\/(\d+(?:\.\d+)*)/)?.[1];
+  } else if (/Version\/(\d+(?:\.\d+)*).*Safari/.test(ua)) {
+    out.browser = "Safari";
+    out.browserVersion = ua.match(/Version\/(\d+(?:\.\d+)*)/)?.[1];
+  }
+  return out;
+}
+
+// src/auto-track.ts
+var DEFAULT_AUTO_TRACK = {
+  sessions: true,
+  pageViews: true,
+  deviceInfo: true
+};
+var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
+var AutoTracker = class {
+  constructor(cfg, track) {
+    this.cfg = cfg;
+    this.track = track;
+    this.session = null;
+    this.cleanups = [];
+  }
+  install() {
+    if (!isBrowserSafe()) return;
+    if (this.cfg.sessions) this.installSessionTracking();
+    if (this.cfg.pageViews) this.installPageViewTracking();
+  }
+  uninstall() {
+    while (this.cleanups.length) {
+      const fn = this.cleanups.pop();
+      try {
+        fn?.();
+      } catch {
+      }
+    }
+    if (this.session && !this.session.endedSent) {
+      this.emitSessionEnd();
+    }
+    this.session = null;
+  }
+  /** Exposed for tests + consumers that want to reset the session manually. */
+  resetSession() {
+    if (this.session && !this.session.endedSent) this.emitSessionEnd();
+    this.session = this.startNewSession();
+    this.emitSessionStart();
+  }
+  /** Exposed for inspection/tests — returns the current sessionId (or null if not in a session). */
+  get currentSessionId() {
+    return this.session?.sessionId ?? null;
+  }
+  // ---------- sessions ----------
+  installSessionTracking() {
+    this.session = this.startNewSession();
+    this.emitSessionStart();
+    const onVisChange = () => {
+      if (!this.session) return;
+      const doc2 = globalThis.document;
+      if (doc2.visibilityState === "hidden") {
+        this.session.hiddenAt = Date.now();
+      } else if (doc2.visibilityState === "visible") {
+        const hiddenFor = this.session.hiddenAt ? Date.now() - this.session.hiddenAt : 0;
+        if (hiddenFor >= SESSION_RESUME_THRESHOLD_MS) {
+          this.emitSessionEnd();
+          this.session = this.startNewSession();
+          this.emitSessionStart();
+        } else {
+          this.session.hiddenAt = null;
+        }
+      }
+    };
+    const onPageHide = () => this.emitSessionEnd();
+    const w = globalThis.window;
+    const doc = globalThis.document;
+    doc.addEventListener("visibilitychange", onVisChange);
+    w.addEventListener("pagehide", onPageHide);
+    w.addEventListener("beforeunload", onPageHide);
+    this.cleanups.push(() => {
+      doc.removeEventListener("visibilitychange", onVisChange);
+      w.removeEventListener("pagehide", onPageHide);
+      w.removeEventListener("beforeunload", onPageHide);
+    });
+  }
+  startNewSession() {
+    return {
+      sessionId: mintSessionId(),
+      startedAt: Date.now(),
+      hiddenAt: null,
+      endedSent: false
+    };
+  }
+  emitSessionStart() {
+    if (!this.session) return;
+    this.track("session.started", { sessionId: this.session.sessionId });
+  }
+  emitSessionEnd() {
+    if (!this.session || this.session.endedSent) return;
+    const duration = Date.now() - this.session.startedAt;
+    this.track("session.ended", {
+      sessionId: this.session.sessionId,
+      durationMs: duration
+    });
+    this.session.endedSent = true;
+  }
+  // ---------- page views ----------
+  installPageViewTracking() {
+    const w = globalThis.window;
+    const doc = globalThis.document;
+    const fire = () => {
+      const loc = w.location;
+      this.track("page.viewed", {
+        path: loc.pathname,
+        url: loc.href,
+        search: loc.search || void 0,
+        hash: loc.hash || void 0,
+        title: doc.title,
+        // referrer only on the first hit of the session — afterward it's
+        // always our previous URL, which isn't useful.
+        referrer: doc.referrer || void 0
+      });
+    };
+    fire();
+    const origPush = w.history.pushState;
+    const origReplace = w.history.replaceState;
+    function patchedPush(data, unused, url) {
+      origPush.apply(this, [data, unused, url]);
+      queueMicrotask(fire);
+    }
+    function patchedReplace(data, unused, url) {
+      origReplace.apply(this, [data, unused, url]);
+      queueMicrotask(fire);
+    }
+    w.history.pushState = patchedPush;
+    w.history.replaceState = patchedReplace;
+    const onPopState = () => fire();
+    w.addEventListener("popstate", onPopState);
+    this.cleanups.push(() => {
+      if (w.history.pushState === patchedPush) {
+        w.history.pushState = origPush;
+      }
+      if (w.history.replaceState === patchedReplace) {
+        w.history.replaceState = origReplace;
+      }
+      w.removeEventListener("popstate", onPopState);
+    });
+  }
+};
+function isBrowserSafe() {
+  return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+}
+function mintSessionId() {
+  const ts = Date.now().toString(36);
+  return `sess_${ts}${randomChars(10)}`;
+}
+
+// src/debug.ts
+var SENSITIVE_KEY_PATTERNS = [
+  /^email$/i,
+  /^password$/i,
+  /^token$/i,
+  /^secret$/i,
+  /^card$/i,
+  /^phone$/i,
+  /password/i,
+  /credit_?card/i
+];
+function findSensitivePropertyKeys(properties) {
+  if (!properties) return [];
+  const hits = [];
+  for (const k of Object.keys(properties)) {
+    if (SENSITIVE_KEY_PATTERNS.some((re) => re.test(k))) hits.push(k);
+  }
+  return hits;
+}
+var ConsoleDebugLogger = class {
+  constructor() {
+    this.enabled = false;
+    this.seen = /* @__PURE__ */ new Set();
+  }
+  emit(signal, message, context) {
+    if (!this.enabled) return;
+    if (ONCE_SIGNALS.has(signal)) {
+      if (this.seen.has(signal)) return;
+      this.seen.add(signal);
+    }
+    const ctx = context ? ` ${safeJson(context)}` : "";
+    console.info(`[crossdeck:${signal}] ${message}${ctx}`);
+  }
+};
+var ONCE_SIGNALS = /* @__PURE__ */ new Set([
+  "sdk.configured",
+  "sdk.first_event_sent",
+  "sdk.environment_mismatch"
+]);
+function safeJson(obj) {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return "[unserialisable context]";
+  }
+}
+
+// src/crossdeck.ts
+var CrossdeckClient = class {
+  constructor() {
+    this.state = null;
+  }
+  /**
+   * Boot the SDK. Idempotent — calling init twice with the same options
+   * is a no-op; calling with different options replaces the previous
+   * configuration.
+   *
+   * NorthStar §11.1: signature is `Crossdeck.init({ appId, publicKey,
+   * environment })`. The trio is validated up-front so a typo'd key or a
+   * mismatched env fails fast at boot rather than at first event-flush.
+   */
+  init(options) {
+    if (!options.publicKey || !options.publicKey.startsWith("cd_pub_")) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "invalid_public_key",
+        message: "Crossdeck.init requires a publishable key starting with cd_pub_."
+      });
+    }
+    if (!options.appId) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "missing_app_id",
+        message: "Crossdeck.init requires an appId. Find yours in the Crossdeck dashboard."
+      });
+    }
+    if (options.environment !== "production" && options.environment !== "sandbox") {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "invalid_environment",
+        message: 'Crossdeck.init requires environment: "production" | "sandbox".'
+      });
+    }
+    const keyEnv = inferEnvFromKey(options.publicKey);
+    if (keyEnv && keyEnv !== options.environment) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "environment_mismatch",
+        message: `Crossdeck.init: environment "${options.environment}" disagrees with key prefix (${keyEnv}). Reconcile the publishable key with the environment declaration.`
+      });
+    }
+    const storage = options.storage ?? detectDefaultStorage();
+    const persistIdentity = options.persistIdentity ?? true;
+    const autoTrack = resolveAutoTrack(options.autoTrack);
+    const opts = {
+      appId: options.appId,
+      publicKey: options.publicKey,
+      environment: options.environment,
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      persistIdentity,
+      storagePrefix: options.storagePrefix ?? "crossdeck:",
+      autoHeartbeat: options.autoHeartbeat ?? true,
+      eventFlushBatchSize: options.eventFlushBatchSize ?? 20,
+      // 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
+    };
+    const debug = new ConsoleDebugLogger();
+    debug.enabled = options.debug === true;
+    const http = new HttpClient({
+      publicKey: opts.publicKey,
+      baseUrl: opts.baseUrl,
+      sdkVersion: opts.sdkVersion
+    });
+    const effectiveStorage = persistIdentity ? storage : new MemoryStorage();
+    const identity = new IdentityStore(effectiveStorage, opts.storagePrefix);
+    const entitlements = new EntitlementCache();
+    const events = new EventQueue({
+      http,
+      batchSize: opts.eventFlushBatchSize,
+      intervalMs: opts.eventFlushIntervalMs,
+      envelope: () => ({
+        appId: opts.appId,
+        environment: opts.environment,
+        sdk: { name: SDK_NAME, version: opts.sdkVersion }
+      }),
+      onFirstFlushSuccess: () => {
+        debug.emit(
+          "sdk.first_event_sent",
+          "First telemetry event received. View it in Live Events.",
+          { appId: opts.appId, environment: opts.environment }
+        );
+      }
+    });
+    const deviceInfo = autoTrack.deviceInfo ? collectDeviceInfo({ appVersion: opts.appVersion ?? void 0 }) : opts.appVersion ? { appVersion: opts.appVersion } : {};
+    this.state = {
+      http,
+      identity,
+      entitlements,
+      events,
+      autoTracker: null,
+      deviceInfo,
+      options: opts,
+      debug,
+      developerUserId: null,
+      uninstallUnloadFlush: null
+    };
+    debug.emit("sdk.configured", `Crossdeck connected to ${opts.appId} in ${opts.environment} mode.`, {
+      appId: opts.appId,
+      environment: opts.environment,
+      sdkVersion: opts.sdkVersion
+    });
+    if (autoTrack.sessions || autoTrack.pageViews) {
+      const tracker = new AutoTracker(
+        autoTrack,
+        (name, properties) => this.track(name, properties)
+      );
+      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);
+    }
+  }
+  /**
+   * @deprecated Use `init()` instead. NorthStar §4 standardised the
+   * lifecycle method name across SDKs as `init` (formerly `start` /
+   * `configure`). `start` will be removed in a future major version.
+   */
+  start(options) {
+    if (typeof console !== "undefined") {
+      console.warn(
+        "[crossdeck] Crossdeck.start() is deprecated \u2014 use Crossdeck.init() instead. The signature is the same."
+      );
+    }
+    this.init(options);
+  }
+  /**
+   * Link the anonymous device to a developer-supplied user ID. Cache
+   * the resolved Crossdeck customer for follow-up calls.
+   */
+  async identify(userId, _options) {
+    const s = this.requireStarted();
+    if (!userId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_user_id",
+        message: "identify(userId) requires a non-empty userId."
+      });
+    }
+    const result = await s.http.request("POST", "/identity/alias", {
+      body: { userId, anonymousId: s.identity.anonymousId }
+    });
+    s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
+    s.developerUserId = userId;
+    return result;
+  }
+  /**
+   * Read the current customer's active entitlements from the server.
+   * Updates the local cache so subsequent isEntitled() calls answer
+   * synchronously.
+   */
+  async getEntitlements() {
+    const s = this.requireStarted();
+    const query = this.identityQueryParams();
+    const result = await s.http.request(
+      "GET",
+      "/entitlements",
+      { query }
+    );
+    if (result.crossdeckCustomerId) {
+      s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
+    }
+    s.entitlements.setFromList(result.data);
+    return result.data;
+  }
+  /**
+   * Synchronous read from the local cache. Returns false if the cache
+   * has never been populated (call getEntitlements first to warm it).
+   */
+  isEntitled(key) {
+    const s = this.requireStarted();
+    return s.entitlements.isEntitled(key);
+  }
+  /** Snapshot of the local entitlement cache. */
+  listEntitlements() {
+    const s = this.requireStarted();
+    return s.entitlements.list();
+  }
+  /**
+   * Subscribe to entitlement-cache changes. Returns an unsubscribe fn.
+   *
+   * 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.
+   *
+   * It is NOT invoked synchronously on subscribe. Callers that need
+   * the current state should read it via `isEntitled()` / `listEntitlements()`
+   * inline; the listener fires only on FUTURE changes.
+   *
+   * This is the foundation of the `useEntitlement` React hook in
+   * `@cross-deck/web/react` — without it, React (or SwiftUI / Compose
+   * / Vue) would have no way to re-render when entitlements arrive
+   * asynchronously after init. The naive pattern of calling
+   * `Crossdeck.isEntitled("pro")` directly inside a render path
+   * shows the empty-cache result forever; binding the result to
+   * component state via `onEntitlementsChange` is the correct
+   * pattern.
+   *
+   * Idempotent unsubscribe — calling the returned function multiple
+   * times is safe.
+   *
+   * Listener errors are swallowed (a buggy listener can't crash the
+   * SDK or other listeners).
+   */
+  onEntitlementsChange(listener) {
+    const s = this.requireStarted();
+    return s.entitlements.subscribe(listener);
+  }
+  /**
+   * Queue a telemetry event. Returns immediately — the network round-
+   * trip happens in the background. To flush before the page unloads,
+   * call flush().
+   */
+  track(name, properties) {
+    const s = this.requireStarted();
+    if (!name) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_event_name",
+        message: "track(name) requires a non-empty name."
+      });
+    }
+    if (s.debug.enabled && properties) {
+      const flagged = findSensitivePropertyKeys(properties);
+      if (flagged.length > 0) {
+        s.debug.emit(
+          "sdk.sensitive_property_warning",
+          `Event "${name}" has potentially sensitive property names: ${flagged.join(", ")}. Crossdeck is privacy-first \u2014 avoid sending PII unless intentional.`,
+          { eventName: name, flagged }
+        );
+      }
+    }
+    if (s.debug.enabled && !s.developerUserId && !s.identity.crossdeckCustomerId) {
+      s.debug.emit(
+        "sdk.no_identity",
+        "Using anonymous user until identify(userId) is called."
+      );
+    }
+    const enriched = { ...s.deviceInfo };
+    const sessionId = s.autoTracker?.currentSessionId;
+    if (sessionId) enriched.sessionId = sessionId;
+    if (properties) Object.assign(enriched, properties);
+    const event = {
+      eventId: this.mintEventId(),
+      name,
+      timestamp: Date.now(),
+      properties: enriched
+    };
+    Object.assign(event, this.identityHintForEvent());
+    s.events.enqueue(event);
+  }
+  /**
+   * 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(options = {}) {
+    const s = this.requireStarted();
+    await s.events.flush(options);
+  }
+  /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
+  async flushEvents() {
+    return this.flush();
+  }
+  /**
+   * Forward purchase evidence to the backend for verification + entitlement
+   * projection. NorthStar §4 + §13 canonical name.
+   *
+   * Today the web SDK only supports Apple StoreKit 2 forwarding (web apps
+   * that sit alongside an iOS app). Stripe doesn't need this method —
+   * Stripe webhooks deliver evidence server-side without a client round-trip.
+   */
+  async syncPurchases(input) {
+    const s = this.requireStarted();
+    if (!input.signedTransactionInfo) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_signed_transaction_info",
+        message: "syncPurchases requires a signedTransactionInfo string from StoreKit 2."
+      });
+    }
+    const result = await s.http.request("POST", "/purchases/sync", {
+      body: { rail: input.rail ?? "apple", ...input }
+    });
+    s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
+    s.entitlements.setFromList(result.entitlements);
+    s.debug.emit(
+      "sdk.purchase_evidence_sent",
+      "StoreKit transaction forwarded. Waiting for backend verification.",
+      { rail: input.rail ?? "apple" }
+    );
+    return result;
+  }
+  /** @deprecated Use `syncPurchases()` instead. NorthStar §4 standardised the name. */
+  async purchaseApple(input) {
+    return this.syncPurchases({ rail: "apple", ...input });
+  }
+  /**
+   * Toggle verbose diagnostic logging — NorthStar §16. When enabled, the
+   * SDK emits a fixed vocabulary of debug signals to console.info that the
+   * dashboard's onboarding checklist can also surface as live events.
+   */
+  setDebugMode(enabled) {
+    const s = this.requireStarted();
+    s.debug.enabled = enabled;
+    if (enabled) {
+      s.debug.emit(
+        "sdk.configured",
+        `Debug mode enabled for ${s.options.appId} in ${s.options.environment} mode.`,
+        { appId: s.options.appId, environment: s.options.environment }
+      );
+    }
+  }
+  /**
+   * Send the boot heartbeat. Called automatically by start() unless
+   * autoHeartbeat:false. Safe to call manually as a "we're still here" ping.
+   */
+  async heartbeat() {
+    const s = this.requireStarted();
+    return await s.http.request("GET", "/sdk/heartbeat");
+  }
+  /**
+   * Wipe persisted identity + entitlement cache. Use on logout. The
+   * next pre-login session generates a fresh anonymousId and starts a
+   * new identity-graph entry.
+   */
+  reset() {
+    if (!this.state) return;
+    this.state.autoTracker?.uninstall();
+    this.state.identity.reset();
+    this.state.entitlements.clear();
+    this.state.events.reset();
+    this.state.developerUserId = null;
+    if (this.state.autoTracker) {
+      const tracker = new AutoTracker(
+        this.state.options.autoTrack,
+        (name, props) => this.track(name, props)
+      );
+      this.state.autoTracker = tracker;
+      tracker.install();
+    }
+  }
+  /**
+   * Diagnostic: current state + queue stats. Useful for the dashboard's
+   * heartbeat row and debugging in dev.
+   *
+   * Returns a stable shape regardless of whether start() has been called —
+   * callers don't need to narrow on `started` to access `events` or
+   * `entitlements`. Pre-start values are sensible empties.
+   */
+  diagnostics() {
+    if (!this.state) {
+      return {
+        started: false,
+        anonymousId: null,
+        crossdeckCustomerId: null,
+        developerUserId: null,
+        sdkVersion: null,
+        baseUrl: null,
+        entitlements: { count: 0, lastUpdated: 0 },
+        events: {
+          buffered: 0,
+          dropped: 0,
+          inFlight: 0,
+          lastFlushAt: 0,
+          lastError: null
+        }
+      };
+    }
+    const s = this.state;
+    return {
+      started: true,
+      anonymousId: s.identity.anonymousId,
+      crossdeckCustomerId: s.identity.crossdeckCustomerId,
+      developerUserId: s.developerUserId,
+      sdkVersion: s.options.sdkVersion,
+      baseUrl: s.options.baseUrl,
+      entitlements: {
+        count: s.entitlements.list().length,
+        lastUpdated: s.entitlements.freshness
+      },
+      events: s.events.getStats()
+    };
+  }
+  // ---------- private helpers ----------
+  requireStarted() {
+    if (!this.state) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "not_initialized",
+        message: "Call Crossdeck.init({ appId, publicKey, environment }) before any other method."
+      });
+    }
+    return this.state;
+  }
+  /**
+   * Build the identity query for /v1/entitlements. Priority:
+   *   crossdeckCustomerId > developerUserId > anonymousId
+   * — matches the resolveCrossdeckCustomerId precedence on the server.
+   */
+  identityQueryParams() {
+    const s = this.requireStarted();
+    if (s.identity.crossdeckCustomerId) {
+      return { customerId: s.identity.crossdeckCustomerId };
+    }
+    if (s.developerUserId) return { userId: s.developerUserId };
+    return { anonymousId: s.identity.anonymousId };
+  }
+  /** Pick the right identity hint to embed on a queued event. */
+  identityHintForEvent() {
+    const s = this.requireStarted();
+    if (s.identity.crossdeckCustomerId) {
+      return { crossdeckCustomerId: s.identity.crossdeckCustomerId };
+    }
+    if (s.developerUserId) return { developerUserId: s.developerUserId };
+    return { anonymousId: s.identity.anonymousId };
+  }
+  mintEventId() {
+    const ts = Date.now().toString(36);
+    return `evt_${ts}${randomChars(8)}`;
+  }
+};
+var Crossdeck = new CrossdeckClient();
+function inferEnvFromKey(publicKey) {
+  if (publicKey.startsWith("cd_pub_test_")) return "sandbox";
+  if (publicKey.startsWith("cd_pub_live_")) return "production";
+  return null;
+}
+function resolveAutoTrack(input) {
+  if (input === false) {
+    return { sessions: false, pageViews: false, deviceInfo: false };
+  }
+  if (input === void 0 || input === true) {
+    return { ...DEFAULT_AUTO_TRACK };
+  }
+  return {
+    sessions: input.sessions ?? DEFAULT_AUTO_TRACK.sessions,
+    pageViews: input.pageViews ?? DEFAULT_AUTO_TRACK.pageViews,
+    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);
+  };
+}
+
+// src/react.ts
+function useEntitlement(key) {
+  const [isEntitled, setIsEntitled] = useState(() => safeIsEntitled(key));
+  useEffect(() => {
+    setIsEntitled(safeIsEntitled(key));
+    let unsubscribe = null;
+    try {
+      unsubscribe = Crossdeck.onEntitlementsChange(() => {
+        setIsEntitled(safeIsEntitled(key));
+      });
+    } catch {
+    }
+    return () => {
+      if (unsubscribe) unsubscribe();
+    };
+  }, [key]);
+  return isEntitled;
+}
+function useEntitlements() {
+  const [keys, setKeys] = useState(() => safeListKeys());
+  useEffect(() => {
+    setKeys(safeListKeys());
+    let unsubscribe = null;
+    try {
+      unsubscribe = Crossdeck.onEntitlementsChange((entitlements) => {
+        setKeys(entitlements.filter((e) => e.isActive).map((e) => e.key));
+      });
+    } catch {
+    }
+    return () => {
+      if (unsubscribe) unsubscribe();
+    };
+  }, []);
+  return keys;
+}
+function safeIsEntitled(key) {
+  try {
+    return Crossdeck.isEntitled(key);
+  } catch {
+    return false;
+  }
+}
+function safeListKeys() {
+  try {
+    return Crossdeck.listEntitlements().filter((e) => e.isActive).map((e) => e.key);
+  } catch {
+    return [];
+  }
+}
+export {
+  useEntitlement,
+  useEntitlements
+};
+//# sourceMappingURL=react.mjs.map