@corbado/observe 1.7.2 → 1.9.0

package/dist/analysis/readers/storage.mjs

@@ -0,0 +1,28 @@
+// src/readers/storage.ts
+function localStorageArea(_meta) {
+  return {
+    getItem: (key) => localStorage.getItem(key),
+    setItem: (key, value) => localStorage.setItem(key, value),
+    removeItem: (key) => localStorage.removeItem(key)
+  };
+}
+function sessionStorageArea(_meta) {
+  return {
+    getItem: (key) => sessionStorage.getItem(key),
+    setItem: (key, value) => sessionStorage.setItem(key, value),
+    removeItem: (key) => sessionStorage.removeItem(key)
+  };
+}
+function cookieJar(_meta) {
+  return {
+    read: () => document.cookie,
+    write: (cookie) => {
+      document.cookie = cookie;
+    }
+  };
+}
+export {
+  cookieJar,
+  localStorageArea,
+  sessionStorageArea
+};

package/dist/analysis/readers/web-lock.mjs

@@ -0,0 +1,56 @@
+// src/readers/web-lock.ts
+function withWebLock(_meta, name, fn, options = {}) {
+  const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+  if (locks?.request) {
+    const timeoutMs = options.timeoutMs;
+    const controller = timeoutMs !== void 0 && typeof AbortController !== "undefined" ? new AbortController() : null;
+    if (timeoutMs !== void 0 && !controller) {
+      return Promise.resolve().then(fn);
+    }
+    try {
+      let ran = false;
+      let timer;
+      const clearAcquisitionTimer = () => {
+        if (timer !== void 0) {
+          clearTimeout(timer);
+          timer = void 0;
+        }
+      };
+      const callback = () => {
+        ran = true;
+        clearAcquisitionTimer();
+        return fn();
+      };
+      const granted = controller ? locks.request(name, { signal: controller.signal }, callback) : locks.request(name, callback);
+      if (controller && timeoutMs !== void 0 && !ran) {
+        timer = setTimeout(() => {
+          timer = void 0;
+          controller.abort();
+          try {
+            options.onTimeout?.();
+          } catch {
+          }
+        }, timeoutMs);
+      }
+      return granted.catch((error) => {
+        if (ran) {
+          throw error;
+        }
+        return fn();
+      }).finally(clearAcquisitionTimer);
+    } catch {
+    }
+  }
+  try {
+    return Promise.resolve(fn());
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+function hasWebLocks(_meta) {
+  return typeof navigator !== "undefined" && !!navigator.locks?.request;
+}
+export {
+  hasWebLocks,
+  withWebLock
+};

package/dist/analysis/readers/window-events.mjs

@@ -0,0 +1,48 @@
+// src/readers/window-events.ts
+function observeWindowLowEvents(_meta, handlers, guard) {
+  const removers = [];
+  const listen = (target, name, handler) => {
+    const safe = (event) => guard(name, () => handler(event));
+    target.addEventListener(name, safe);
+    removers.push(() => target.removeEventListener(name, safe));
+  };
+  listen(window, "blur", () => handlers.blur());
+  listen(window, "focus", () => handlers.focus());
+  listen(document, "visibilitychange", () => handlers.visibilityChange(document.visibilityState === "hidden"));
+  listen(document, "focusout", (event) => handlers.focusOut(event.target, !!event.relatedTarget));
+  listen(document, "focusin", (event) => handlers.focusIn(() => event.composedPath()));
+  listen(document, "pointerdown", (event) => handlers.pointerDown(event.target));
+  if (window.visualViewport) {
+    listen(window.visualViewport, "resize", () => handlers.viewportResize());
+    listen(window.visualViewport, "scroll", () => handlers.viewportScroll());
+  }
+  listen(window, "pagehide", () => handlers.pageHide());
+  const navigation = window.navigation;
+  if (navigation) {
+    listen(navigation, "currententrychange", (event) => {
+      const change = event;
+      const from = change.from?.index;
+      const to = navigation.currentEntry?.index;
+      if (change.navigationType === "traverse" && typeof from === "number" && typeof to === "number" && from >= 0 && to >= 0 && to < from) {
+        handlers.navigateBack();
+      }
+    });
+  }
+  return removers;
+}
+function readFocusedChain(_meta) {
+  const chain = [];
+  for (let active = document.activeElement; active; active = active.shadowRoot?.activeElement ?? null) {
+    chain.push(active);
+  }
+  return chain;
+}
+function readActiveFocus(_meta) {
+  const active = document.activeElement;
+  return { active, idle: active === document.body || !active };
+}
+export {
+  observeWindowLowEvents,
+  readActiveFocus,
+  readFocusedChain
+};

package/dist/analysis/storage/index.mjs

@@ -0,0 +1,249 @@
+// src/storage/index.ts
+import { cookieJar, localStorageArea, sessionStorageArea } from "../readers/storage.mjs";
+function namespacedKey(key, namespace) {
+  return `${key}_${namespace}`;
+}
+var NamespacedStorage = class {
+  constructor(engine, namespace) {
+    this.engine = engine;
+    this.namespace = namespace;
+  }
+  getItem(key) {
+    return this.engine.getItem(namespacedKey(key, this.namespace));
+  }
+  setItem(key, value) {
+    this.engine.setItem(namespacedKey(key, this.namespace), value);
+  }
+  removeItem(key) {
+    this.engine.removeItem(namespacedKey(key, this.namespace));
+  }
+};
+var LocalStorage = class {
+  constructor(logger) {
+    this.logger = logger;
+  }
+  area = localStorageArea({
+    key: "storage:sdk.local-storage",
+    title: "Observe data saved in the browser",
+    accessNote: "localStorage, Observe's own cbo_ keys",
+    group: "Observe SDK state",
+    origin: "observe-internal",
+    fields: [
+      {
+        path: "value",
+        label: "Observe's own saved data",
+        exposure: "none",
+        transform: {
+          note: "own cbo_* keys only (session, sequence, outbox, config cache, experiments, client env, debug); written and read back by the SDK"
+        }
+      }
+    ]
+  });
+  /**
+   * Error situations:
+   *  - localStorage is not available: return null
+   *  - localStorage.getItem throws: catch exception, log error and return null
+   *  - JSON.parse throws: catch exception, log error and return null
+   */
+  getItem(key) {
+    try {
+      if (typeof localStorage === "undefined") return null;
+      const item = this.area.getItem(key);
+      if (item) {
+        return JSON.parse(item);
+      }
+      return null;
+    } catch (error) {
+      this.logger.error(`LocalStorage.getItem failed for key "${key}"`, error);
+      return null;
+    }
+  }
+  /**
+   * Error situations:
+   *  - localStorage is not available: return without writing
+   *  - localStorage.setItem throws: catch exception and log error
+   *  - JSON.stringify throws: catch exception and log error
+   */
+  setItem(key, value) {
+    try {
+      if (typeof localStorage === "undefined") return;
+      this.area.setItem(key, JSON.stringify(value));
+    } catch (error) {
+      this.logger.error(`LocalStorage.setItem failed for key "${key}"`, error);
+      this.logger.reportTelemetry?.("error", `localStorage.setItem failed: ${key}`);
+    }
+  }
+  /**
+   * Error situations:
+   *  - localStorage is not available: return without writing
+   *  - localStorage.removeItem throws: catch exception and log error
+   */
+  removeItem(key) {
+    try {
+      if (typeof localStorage === "undefined") return;
+      this.area.removeItem(key);
+    } catch (error) {
+      this.logger.error(`LocalStorage.removeItem failed for key "${key}"`, error);
+    }
+  }
+};
+var CookieStorage = class {
+  constructor(logger, domain) {
+    this.logger = logger;
+    this.domain = domain;
+  }
+  jar = cookieJar({
+    key: "storage:sdk.cookie",
+    title: "Observe data saved in cookies",
+    accessNote: "document.cookie, Observe's own cbo_ cookies",
+    group: "Observe SDK state",
+    origin: "observe-internal",
+    fields: [
+      {
+        path: "value",
+        label: "Observe's own cookies",
+        exposure: "none",
+        transform: {
+          note: "own cbo_* cookies only (cookie storage mode); the cookie string is scanned for the requested key"
+        }
+      }
+    ]
+  });
+  /**
+   * Error situations:
+   *  - document is not available: return null
+   *  - document.cookie read throws: catch exception, log error and return null
+   *  - decodeURIComponent throws: catch exception, log error and return null
+   *  - JSON.parse throws: catch exception, log error and return null
+   */
+  getItem(key) {
+    try {
+      if (typeof document === "undefined") return null;
+      const name = key + "=";
+      const parts = this.jar.read().split(";");
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i].trim();
+        if (part.indexOf(name) === 0) {
+          const rawValue = part.substring(name.length);
+          return JSON.parse(decodeURIComponent(rawValue));
+        }
+      }
+      return null;
+    } catch (error) {
+      this.logger.error(`CookieStorage.getItem failed for key "${key}"`, error);
+      return null;
+    }
+  }
+  /**
+   * Error situations:
+   *  - document is not available: return without writing
+   *  - document.cookie write throws: catch exception and log error
+   *  - JSON.stringify throws: catch exception and log error
+   */
+  setItem(key, value) {
+    try {
+      if (typeof document === "undefined") return;
+      let cookieString = `${key}=${encodeURIComponent(JSON.stringify(value))}; path=/; SameSite=Lax`;
+      if (this.domain) {
+        cookieString += `; domain=${this.domain}`;
+      }
+      this.jar.write(cookieString);
+    } catch (error) {
+      this.logger.error(`CookieStorage.setItem failed for key "${key}"`, error);
+      this.logger.reportTelemetry?.("error", `cookie.setItem failed: ${key}`);
+    }
+  }
+  /**
+   * Error situations:
+   *  - document is not available: return without writing
+   *  - document.cookie write throws: catch exception and log error
+   */
+  removeItem(key) {
+    try {
+      if (typeof document === "undefined") return;
+      let cookieString = `${key}=; Max-Age=-99999999; path=/`;
+      if (this.domain) {
+        cookieString += `; domain=${this.domain}`;
+      }
+      this.jar.write(cookieString);
+    } catch (error) {
+      this.logger.error(`CookieStorage.removeItem failed for key "${key}"`, error);
+    }
+  }
+};
+var SessionStorage = class {
+  constructor(logger) {
+    this.logger = logger;
+  }
+  area = sessionStorageArea({
+    key: "storage:sdk.session-storage",
+    title: "Observe data saved for the current tab",
+    accessNote: "sessionStorage, Observe's own cbo_ keys",
+    group: "Observe SDK state",
+    origin: "observe-internal",
+    fields: [
+      {
+        path: "value",
+        label: "Observe's own data for this tab",
+        exposure: "none",
+        transform: {
+          note: "own cbo_* keys only (per-tab session, sequence and tab id); written and read back by the SDK"
+        }
+      }
+    ]
+  });
+  /**
+   * Error situations:
+   *  - sessionStorage is not available: return null
+   *  - sessionStorage.getItem throws: catch exception, log error and return null
+   *  - JSON.parse throws: catch exception, log error and return null
+   */
+  getItem(key) {
+    try {
+      if (typeof sessionStorage === "undefined") return null;
+      const item = this.area.getItem(key);
+      if (item) {
+        return JSON.parse(item);
+      }
+      return null;
+    } catch (error) {
+      this.logger.error(`SessionStorage.getItem failed for key "${key}"`, error);
+      return null;
+    }
+  }
+  /**
+   * Error situations:
+   *  - sessionStorage is not available: return without writing
+   *  - sessionStorage.setItem throws: catch exception and log error
+   *  - JSON.stringify throws: catch exception and log error
+   */
+  setItem(key, value) {
+    try {
+      if (typeof sessionStorage === "undefined") return;
+      this.area.setItem(key, JSON.stringify(value));
+    } catch (error) {
+      this.logger.error(`SessionStorage.setItem failed for key "${key}"`, error);
+      this.logger.reportTelemetry?.("error", `sessionStorage.setItem failed: ${key}`);
+    }
+  }
+  /**
+   * Error situations:
+   *  - sessionStorage is not available: return without writing
+   *  - sessionStorage.removeItem throws: catch exception and log error
+   */
+  removeItem(key) {
+    try {
+      if (typeof sessionStorage === "undefined") return;
+      this.area.removeItem(key);
+    } catch (error) {
+      this.logger.error(`SessionStorage.removeItem failed for key "${key}"`, error);
+    }
+  }
+};
+export {
+  CookieStorage,
+  LocalStorage,
+  NamespacedStorage,
+  SessionStorage,
+  namespacedKey
+};

package/dist/analysis/storage/migration.mjs

@@ -0,0 +1,56 @@
+// src/storage/migration.ts
+import { namespacedKey } from "./index.mjs";
+var STORAGE_SCHEMA_VERSION = 1;
+var STORAGE_SCHEMA_KEY = "cbo_storage_schema";
+var LOCAL_KEYS = [
+  "cbo_seq",
+  "cbo_sdk_config",
+  "cbo_experiments",
+  "cbo_client_env_handle",
+  "cbo_outbox",
+  "cbo_visibility_change_debug",
+  "cbo_pagehide_debug",
+  "cbo_session"
+];
+var SESSION_KEYS = ["cbo_session_id", "cbo_tab_id"];
+var COOKIE_KEYS = ["cbo_client_env_handle"];
+function writeVerified(storage, key, value) {
+  storage.setItem(key, value);
+  return JSON.stringify(storage.getItem(key)) === JSON.stringify(value);
+}
+function migrateArea(storage, projectId, keys) {
+  const schema = storage.getItem(STORAGE_SCHEMA_KEY);
+  if (schema !== null) {
+    if (schema.version !== STORAGE_SCHEMA_VERSION || schema.projectId !== projectId) return false;
+    if (schema.complete === true) return true;
+    if (schema.complete !== false) return false;
+  } else {
+    if (keys.some((key) => storage.getItem(namespacedKey(key, projectId)) !== null)) {
+      return writeVerified(storage, STORAGE_SCHEMA_KEY, { version: STORAGE_SCHEMA_VERSION, projectId, complete: true });
+    }
+    if (!writeVerified(storage, STORAGE_SCHEMA_KEY, { version: STORAGE_SCHEMA_VERSION, projectId, complete: false })) {
+      return false;
+    }
+  }
+  for (const key of keys) {
+    const target = namespacedKey(key, projectId);
+    if (storage.getItem(target) !== null) continue;
+    const legacy = storage.getItem(key);
+    if (legacy !== null && !writeVerified(storage, target, legacy)) return false;
+  }
+  return writeVerified(storage, STORAGE_SCHEMA_KEY, { version: STORAGE_SCHEMA_VERSION, projectId, complete: true });
+}
+function migrateLegacyStorage(projectId, local, session, cookie, logger) {
+  try {
+    if (!migrateArea(local, projectId, LOCAL_KEYS)) return;
+    migrateArea(session, projectId, SESSION_KEYS);
+    if (cookie) migrateArea(cookie, projectId, COOKIE_KEYS);
+  } catch (error) {
+    logger.error("Failed to migrate legacy Observe storage", error);
+  }
+}
+export {
+  STORAGE_SCHEMA_KEY,
+  STORAGE_SCHEMA_VERSION,
+  migrateLegacyStorage
+};

package/dist/analysis/store/event-store.mjs

@@ -0,0 +1,132 @@
+// src/store/event-store.ts
+import { withWebLock } from "../readers/web-lock.mjs";
+var OUTBOX_STORAGE_KEY = "cbo_outbox";
+var OUTBOX_LOCK_NAME = "cbo_outbox";
+var DEFAULT_MAX_ENTRIES = 500;
+var DEFAULT_MAX_SERIALIZED_LENGTH = 512 * 1024;
+function isOutboxEntry(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const entry = value;
+  return typeof entry.id === "string" && entry.id !== "" && typeof entry.sessionId === "string" && typeof entry.flushAfter === "number" && Number.isFinite(entry.flushAfter) && typeof entry.attempts === "number" && Number.isFinite(entry.attempts) && typeof entry.event === "object" && entry.event !== null;
+}
+var EventStore = class {
+  constructor(storage, logger, maxEntries = DEFAULT_MAX_ENTRIES, maxSerializedLength = DEFAULT_MAX_SERIALIZED_LENGTH, lockName = OUTBOX_LOCK_NAME, storageKey = OUTBOX_STORAGE_KEY) {
+    this.storage = storage;
+    this.logger = logger;
+    this.maxEntries = maxEntries;
+    this.maxSerializedLength = maxSerializedLength;
+    this.lockName = lockName;
+    this.storageKey = storageKey;
+    this.entries = this.read();
+  }
+  entries = [];
+  /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
+  reportedMalformed = false;
+  read() {
+    const raw = this.storage.getItem(this.storageKey);
+    if (!Array.isArray(raw)) {
+      return [];
+    }
+    const valid = raw.filter(isOutboxEntry);
+    if (valid.length < raw.length && !this.reportedMalformed) {
+      this.reportedMalformed = true;
+      this.logger.error(`EventStore dropped ${raw.length - valid.length} malformed outbox entries`);
+      this.logger.reportTelemetry?.("error", "event store dropped malformed outbox entries");
+    }
+    return valid;
+  }
+  mutate(fn) {
+    return withWebLock(
+      {
+        key: "browser-api:sdk.web-locks",
+        title: "Coordination of Observe data across open tabs",
+        accessNote: "Web Locks API (navigator.locks) on Observe's own lock names",
+        group: "Observe SDK state",
+        origin: "observe-internal",
+        fields: [
+          {
+            path: "result",
+            label: "Coordination between open tabs",
+            exposure: "none",
+            transform: { note: "own cbo_* lock names; serializes the SDK's storage updates across tabs" }
+          }
+        ]
+      },
+      this.lockName,
+      () => {
+        try {
+          let next = fn(this.read());
+          if (next.length > this.maxEntries) {
+            const evicted = next.length - this.maxEntries;
+            next = next.slice(next.length - this.maxEntries);
+            this.logger.error(`EventStore evicted ${evicted} oldest entries (cap ${this.maxEntries})`);
+            this.logger.reportTelemetry?.("error", "event store evicted entries (cap)");
+          }
+          next = this.enforceSizeBudget(next);
+          this.entries = next;
+          this.storage.setItem(this.storageKey, next);
+        } catch (error) {
+          this.logger.error("Failed to mutate event store", error);
+          this.logger.reportTelemetry?.("error", "failed to mutate event store");
+        }
+      }
+    );
+  }
+  /** Evict oldest entries until the serialized outbox fits {@link maxSerializedLength}. */
+  enforceSizeBudget(next) {
+    const sizes = next.map((entry) => JSON.stringify(entry).length);
+    let total = sizes.reduce((sum, size) => sum + size, next.length + 1);
+    let evict = 0;
+    while (total > this.maxSerializedLength && evict < next.length) {
+      total -= sizes[evict] + 1;
+      evict++;
+    }
+    if (evict === 0) {
+      return next;
+    }
+    this.logger.error(`EventStore evicted ${evict} oldest entries (size budget ${this.maxSerializedLength})`);
+    this.logger.reportTelemetry?.("error", "event store evicted entries (size budget)");
+    return next.slice(evict);
+  }
+  /** Append an entry. No-op if an entry with the same id already exists. */
+  add(entry) {
+    return this.mutate((current) => current.some((e) => e.id === entry.id) ? current : [...current, entry]);
+  }
+  /** Re-read from storage and return all entries (memory mirror refreshed). */
+  all() {
+    this.entries = this.read();
+    return this.entries;
+  }
+  /** Entries whose `flushAfter` has elapsed, in insertion order. */
+  getDue(now) {
+    return this.all().filter((entry) => entry.flushAfter <= now);
+  }
+  /** Remove entries by id (acknowledged or permanently dropped). */
+  remove(ids) {
+    if (ids.length === 0) {
+      return Promise.resolve();
+    }
+    const idSet = new Set(ids);
+    return this.mutate((current) => current.filter((entry) => !idSet.has(entry.id)));
+  }
+  /** Replace existing entries (matched by id) with updated copies, e.g. after bumping backoff. */
+  update(updated) {
+    if (updated.length === 0) {
+      return Promise.resolve();
+    }
+    const byId = new Map(updated.map((entry) => [entry.id, entry]));
+    return this.mutate((current) => current.map((entry) => byId.get(entry.id) ?? entry));
+  }
+  size() {
+    return this.all().length;
+  }
+};
+export {
+  DEFAULT_MAX_ENTRIES,
+  DEFAULT_MAX_SERIALIZED_LENGTH,
+  EventStore,
+  OUTBOX_LOCK_NAME,
+  OUTBOX_STORAGE_KEY
+};