@cross-deck/web 0.1.1 → 0.3.0

package/dist/index.mjs

@@ -46,7 +46,7 @@ function typeMapForStatus(status) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/web";
-var SDK_VERSION = "0.1.1";
+var SDK_VERSION = "0.3.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var HttpClient = class {
   constructor(config) {
@@ -245,6 +245,7 @@ var EventQueue = class {
     this.lastFlushAt = 0;
     this.lastError = null;
     this.cancelTimer = null;
+    this.firstFlushFired = false;
   }
   enqueue(event) {
     this.buffer.push(event);
@@ -271,12 +272,25 @@ var EventQueue = class {
     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: { events: batch }
+        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
+        }
       });
       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);
@@ -357,36 +371,354 @@ function detectDefaultStorage() {
   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 start twice with the same options
+   * 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.
    */
-  start(options) {
+  init(options) {
     if (!options.publicKey || !options.publicKey.startsWith("cd_pub_")) {
       throw new CrossdeckError({
         type: "configuration_error",
         code: "invalid_public_key",
-        message: "Crossdeck.start requires a publishable key starting with cd_pub_."
+        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,
       eventFlushIntervalMs: options.eventFlushIntervalMs ?? 5e3,
-      sdkVersion: options.sdkVersion ?? SDK_VERSION
+      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,
@@ -398,20 +730,62 @@ var CrossdeckClient = class {
     const events = new EventQueue({
       http,
       batchSize: opts.eventFlushBatchSize,
-      intervalMs: opts.eventFlushIntervalMs
+      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
     };
+    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();
+    }
     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.
@@ -467,7 +841,7 @@ var CrossdeckClient = class {
   /**
    * Queue a telemetry event. Returns immediately — the network round-
    * trip happens in the background. To flush before the page unloads,
-   * call flushEvents().
+   * call flush().
    */
   track(name, properties) {
     const s = this.requireStarted();
@@ -478,37 +852,97 @@ var CrossdeckClient = class {
         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: properties ?? {}
+      properties: enriched
     };
     Object.assign(event, this.identityHintForEvent());
     s.events.enqueue(event);
   }
-  /** Force-flush queued events. Useful to call from page-unload handlers. */
-  async flushEvents() {
+  /**
+   * Force-flush queued events. Useful to call from page-unload handlers.
+   *
+   * NorthStar §4: standard method name across all Crossdeck SDKs.
+   */
+  async flush() {
     const s = this.requireStarted();
     await s.events.flush();
   }
-  /** Forward an Apple StoreKit 2 transaction for verification + projection. */
-  async purchaseApple(input) {
+  /** @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: "purchaseApple requires a signedTransactionInfo string from StoreKit 2."
+        message: "syncPurchases requires a signedTransactionInfo string from StoreKit 2."
       });
     }
-    const result = await s.http.request("POST", "/purchases", {
-      body: { rail: "apple", ...input }
+    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.
@@ -524,10 +958,19 @@ var CrossdeckClient = class {
    */
   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
@@ -576,8 +1019,8 @@ var CrossdeckClient = class {
     if (!this.state) {
       throw new CrossdeckError({
         type: "configuration_error",
-        code: "not_started",
-        message: "Call Crossdeck.start({ publicKey }) before any other method."
+        code: "not_initialized",
+        message: "Call Crossdeck.init({ appId, publicKey, environment }) before any other method."
       });
     }
     return this.state;
@@ -610,6 +1053,24 @@ var CrossdeckClient = class {
   }
 };
 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
+  };
+}
 export {
   Crossdeck,
   CrossdeckClient,