@cross-deck/web 0.2.0 → 0.4.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.2.0";
+var SDK_VERSION = "0.3.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var HttpClient = class {
   constructor(config) {
@@ -200,6 +200,7 @@ var EntitlementCache = class {
     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) {
@@ -217,20 +218,57 @@ var EntitlementCache = class {
    * 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 {
+      }
+    }
   }
 };
 
@@ -245,6 +283,7 @@ var EventQueue = class {
     this.lastFlushAt = 0;
     this.lastError = null;
     this.cancelTimer = null;
+    this.firstFlushFired = false;
   }
   enqueue(event) {
     this.buffer.push(event);
@@ -271,12 +310,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);
@@ -595,29 +647,104 @@ function mintSessionId() {
   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:",
@@ -628,6 +755,8 @@ var CrossdeckClient = class {
       autoTrack,
       appVersion: options.appVersion ?? null
     };
+    const debug = new ConsoleDebugLogger();
+    debug.enabled = options.debug === true;
     const http = new HttpClient({
       publicKey: opts.publicKey,
       baseUrl: opts.baseUrl,
@@ -639,7 +768,19 @@ 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 = {
@@ -650,8 +791,14 @@ var CrossdeckClient = class {
       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,
@@ -664,6 +811,19 @@ var CrossdeckClient = class {
       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.
@@ -716,10 +876,41 @@ var CrossdeckClient = class {
     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 flushEvents().
+   * call flush().
    */
   track(name, properties) {
     const s = this.requireStarted();
@@ -730,6 +921,22 @@ 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;
@@ -743,28 +950,68 @@ var CrossdeckClient = class {
     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.
@@ -841,8 +1088,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;
@@ -875,6 +1122,11 @@ 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 };