@corbado/observe 1.8.0 → 1.9.0

package/dist/analysis/queue.mjs

@@ -3,6 +3,7 @@ import { v7 as uuidv7 } from "uuid";
 import { AuthEventName } from "./types.mjs";
 import { CONFIG_REQUEST_HEADER, DEFAULT_RELIABILITY_CONFIG } from "./config.mjs";
 import { EventStore } from "./store/event-store.mjs";
+import { listenWindow, readDocumentHidden, readPageUrl } from "./readers/page.mjs";
 var PROBE_QUEUE_MAX_ITEMS = 500;
 var PROBE_QUEUE_MAX_BYTES = 512 * 1024;
 var PROBE_BATCH_MAX_ITEMS = 200;
@@ -96,6 +97,8 @@ var RequestQueue = class {
   dirtySinceSyncFlush = false;
   onVisibilityChange = null;
   onPageHide = null;
+  removeVisibilityChange = null;
+  removePageHide = null;
   batchSize;
   flushIntervalOverride;
   debug;
@@ -743,7 +746,21 @@ var RequestQueue = class {
     this.onVisibilityChange = () => {
       try {
         this.writeLifecycleDebugOutput("cbo_visibility_change_debug");
-        if (document.visibilityState === "hidden" && this.config.tvc) {
+        if (readDocumentHidden({
+          key: "page:lifecycle.visibility",
+          title: "Page visibility",
+          accessNote: "document.visibilityState",
+          group: "Page lifecycle",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "visibilityState",
+              label: "Whether the page is hidden",
+              exposure: "enum",
+              transform: { values: ["hidden", "other"] }
+            }
+          ]
+        }) && this.config.tvc) {
           this.flushSync("visibility-change");
         }
       } catch (error) {
@@ -760,8 +777,44 @@ var RequestQueue = class {
         this.logger.error("Unexpected error in queue flushSync", error);
       }
     };
-    window.addEventListener("visibilitychange", this.onVisibilityChange);
-    window.addEventListener("pagehide", this.onPageHide);
+    this.removeVisibilityChange = listenWindow(
+      {
+        key: "page:lifecycle.visibilitychange",
+        title: "Page visibility changes",
+        accessNote: "visibilitychange event on document",
+        group: "Page lifecycle",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "event.visibilitychange",
+            label: "Page hidden or shown again",
+            exposure: "presence",
+            transform: { note: "flushes pending events when the page is hidden" }
+          }
+        ]
+      },
+      "visibilitychange",
+      this.onVisibilityChange
+    );
+    this.removePageHide = listenWindow(
+      {
+        key: "page:lifecycle.pagehide",
+        title: "Leaving the page",
+        accessNote: "pagehide event on window",
+        group: "Page lifecycle",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "event.pagehide",
+            label: "Leaving the page",
+            exposure: "presence",
+            transform: { note: "flushes pending events on unload" }
+          }
+        ]
+      },
+      "pagehide",
+      this.onPageHide
+    );
   }
   writeLifecycleDebugOutput(key) {
     if (!this.debug || !this.storage) {
@@ -769,7 +822,21 @@ var RequestQueue = class {
     }
     const output = {
       last_executed: Date.now(),
-      url: window.location.href
+      url: readPageUrl({
+        key: "page:location.url",
+        title: "Page address (debug output only)",
+        accessNote: "location.href, only written to the debug log",
+        group: "Page",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "url",
+            label: "Full page address",
+            exposure: "raw",
+            transform: { note: "debug mode only; written to own localStorage, never sent" }
+          }
+        ]
+      })
     };
     this.storage.setItem(key, output);
   }
@@ -862,11 +929,11 @@ var RequestQueue = class {
       this.clearTimer();
       this.dropProbes(this.probeQueue.slice());
       if (typeof window !== "undefined") {
-        if (this.onVisibilityChange) {
-          window.removeEventListener("visibilitychange", this.onVisibilityChange);
+        if (this.removeVisibilityChange) {
+          this.removeVisibilityChange();
         }
-        if (this.onPageHide) {
-          window.removeEventListener("pagehide", this.onPageHide);
+        if (this.removePageHide) {
+          this.removePageHide();
         }
       }
     } catch (error) {

package/dist/analysis/{low-events/input-paste-observer.mjs → readers/input-paste.mjs}

@@ -1,6 +1,6 @@
-// src/low-events/input-paste-observer.ts
+// src/readers/input-paste.ts
 var InputPasteObserver = class {
-  constructor(inputs, logger, changed, reserveCaptureSeq) {
+  constructor(_meta, inputs, logger, changed, reserveCaptureSeq) {
     this.inputs = inputs;
     this.logger = logger;
     this.changed = changed;

package/dist/analysis/readers/input.mjs

@@ -0,0 +1,61 @@
+// src/readers/input.ts
+var FIELD_EVENTS = ["focus", "blur", "pointerdown", "pointerup", "click", "input", "keyup"];
+function observeInputField(_meta, field, handlers, guard, order = FIELD_EVENTS) {
+  const listeners = [];
+  for (const type of order) {
+    const listener = reduceFieldEvent(type, handlers, guard);
+    if (listener) listeners.push([type, listener]);
+  }
+  for (const [type, listener] of listeners) field.addEventListener(type, listener);
+  return () => {
+    for (const [type, listener] of listeners) field.removeEventListener(type, listener);
+  };
+}
+function reduceFieldEvent(type, handlers, guard) {
+  switch (type) {
+    case "focus":
+    case "blur": {
+      const handler = handlers[type];
+      return handler && ((event) => guard(type, () => handler(event.relatedTarget)));
+    }
+    case "pointerdown":
+    case "pointerup":
+    case "click": {
+      const handler = handlers[type];
+      return handler && (() => guard(type, () => handler()));
+    }
+    case "input": {
+      const handler = handlers.input;
+      return handler && ((event) => guard(
+        "input",
+        () => handler(
+          event.isComposing || event.inputType === "insertCompositionText",
+          event
+        )
+      ));
+    }
+    case "keyup": {
+      const handler = handlers.keyupEscape;
+      return handler && ((event) => guard("keyup", () => {
+        if (event.key === "Escape") handler();
+      }));
+    }
+  }
+}
+function readInputContentLength(_meta, field) {
+  if (field.type === "checkbox" || field.type === "radio") return field.checked ? 1 : 0;
+  return field.value.length;
+}
+function readInputGroupValueLength(_meta, fields) {
+  return fields.reduce((total, field) => total + field.value.length, 0);
+}
+function readFocusedField(_meta, fields) {
+  const active = document.activeElement;
+  return fields.find((field) => field === active);
+}
+export {
+  observeInputField,
+  readFocusedField,
+  readInputContentLength,
+  readInputGroupValueLength
+};

package/dist/analysis/readers/loader-global.mjs

@@ -0,0 +1,15 @@
+// src/readers/loader-global.ts
+function drainLoaderQueue(_meta, name, replay) {
+  const global = window.Corbado;
+  if (global?.[name]) {
+    replay(global[name]);
+    delete window.Corbado[name];
+  }
+}
+function installLoaderGlobal(_meta, api) {
+  window.Corbado = api;
+}
+export {
+  drainLoaderQueue,
+  installLoaderGlobal
+};

package/dist/analysis/readers/network.mjs

@@ -0,0 +1,14 @@
+// src/readers/network.ts
+function sendFetch(_meta, url, init) {
+  return fetch(url, init);
+}
+function beaconSender(_meta) {
+  if (typeof navigator?.sendBeacon !== "function") {
+    return void 0;
+  }
+  return (url, data) => navigator.sendBeacon(url, data);
+}
+export {
+  beaconSender,
+  sendFetch
+};

package/dist/analysis/readers/page.mjs

@@ -0,0 +1,30 @@
+// src/readers/page.ts
+import { applySourcePathQuery } from "../utils/source-path.mjs";
+function listenWindow(_meta, type, handler, options) {
+  if (options === void 0) {
+    window.addEventListener(type, handler);
+  } else {
+    window.addEventListener(type, handler, options);
+  }
+  return () => window.removeEventListener(type, handler);
+}
+function readDocumentHidden(_meta) {
+  return document.visibilityState === "hidden";
+}
+function readDocumentComplete(_meta) {
+  return document.readyState === "complete";
+}
+function readPageUrl(_meta) {
+  return window.location.href;
+}
+function readSourcePath(_meta, mode, allow) {
+  const search = applySourcePathQuery(window.location.search, mode, allow);
+  return `${window.location.pathname}${search}`;
+}
+export {
+  listenWindow,
+  readDocumentComplete,
+  readDocumentHidden,
+  readPageUrl,
+  readSourcePath
+};

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/{utils → readers}/web-lock.mjs

@@ -1,5 +1,5 @@
-// src/utils/web-lock.ts
-function withWebLock(name, fn, options = {}) {
+// 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;
@@ -47,6 +47,10 @@ function withWebLock(name, fn, options = {}) {
     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

@@ -1,4 +1,5 @@
 // src/storage/index.ts
+import { cookieJar, localStorageArea, sessionStorageArea } from "../readers/storage.mjs";
 function namespacedKey(key, namespace) {
   return `${key}_${namespace}`;
 }
@@ -21,6 +22,23 @@ 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
@@ -30,7 +48,7 @@ var LocalStorage = class {
   getItem(key) {
     try {
       if (typeof localStorage === "undefined") return null;
-      const item = localStorage.getItem(key);
+      const item = this.area.getItem(key);
       if (item) {
         return JSON.parse(item);
       }
@@ -49,7 +67,7 @@ var LocalStorage = class {
   setItem(key, value) {
     try {
       if (typeof localStorage === "undefined") return;
-      localStorage.setItem(key, JSON.stringify(value));
+      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}`);
@@ -63,7 +81,7 @@ var LocalStorage = class {
   removeItem(key) {
     try {
       if (typeof localStorage === "undefined") return;
-      localStorage.removeItem(key);
+      this.area.removeItem(key);
     } catch (error) {
       this.logger.error(`LocalStorage.removeItem failed for key "${key}"`, error);
     }
@@ -74,6 +92,23 @@ var CookieStorage = class {
     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
@@ -85,7 +120,7 @@ var CookieStorage = class {
     try {
       if (typeof document === "undefined") return null;
       const name = key + "=";
-      const parts = document.cookie.split(";");
+      const parts = this.jar.read().split(";");
       for (let i = 0; i < parts.length; i++) {
         const part = parts[i].trim();
         if (part.indexOf(name) === 0) {
@@ -112,7 +147,7 @@ var CookieStorage = class {
       if (this.domain) {
         cookieString += `; domain=${this.domain}`;
       }
-      document.cookie = cookieString;
+      this.jar.write(cookieString);
     } catch (error) {
       this.logger.error(`CookieStorage.setItem failed for key "${key}"`, error);
       this.logger.reportTelemetry?.("error", `cookie.setItem failed: ${key}`);
@@ -130,7 +165,7 @@ var CookieStorage = class {
       if (this.domain) {
         cookieString += `; domain=${this.domain}`;
       }
-      document.cookie = cookieString;
+      this.jar.write(cookieString);
     } catch (error) {
       this.logger.error(`CookieStorage.removeItem failed for key "${key}"`, error);
     }
@@ -140,6 +175,23 @@ 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
@@ -149,7 +201,7 @@ var SessionStorage = class {
   getItem(key) {
     try {
       if (typeof sessionStorage === "undefined") return null;
-      const item = sessionStorage.getItem(key);
+      const item = this.area.getItem(key);
       if (item) {
         return JSON.parse(item);
       }
@@ -168,7 +220,7 @@ var SessionStorage = class {
   setItem(key, value) {
     try {
       if (typeof sessionStorage === "undefined") return;
-      sessionStorage.setItem(key, JSON.stringify(value));
+      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}`);
@@ -182,7 +234,7 @@ var SessionStorage = class {
   removeItem(key) {
     try {
       if (typeof sessionStorage === "undefined") return;
-      sessionStorage.removeItem(key);
+      this.area.removeItem(key);
     } catch (error) {
       this.logger.error(`SessionStorage.removeItem failed for key "${key}"`, error);
     }

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

@@ -1,5 +1,5 @@
 // src/store/event-store.ts
-import { withWebLock } from "../utils/web-lock.mjs";
+import { withWebLock } from "../readers/web-lock.mjs";
 var OUTBOX_STORAGE_KEY = "cbo_outbox";
 var OUTBOX_LOCK_NAME = "cbo_outbox";
 var DEFAULT_MAX_ENTRIES = 500;
@@ -38,23 +38,41 @@ var EventStore = class {
     return valid;
   }
   mutate(fn) {
-    return withWebLock(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)");
+    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");
         }
-        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) {

package/dist/analysis/transports/fetch.mjs

@@ -1,5 +1,6 @@
 // src/transports/fetch.ts
 import { parseReliabilityConfig } from "../config.mjs";
+import { beaconSender, sendFetch } from "../readers/network.mjs";
 var MAX_KEEPALIVE_BODY_BYTES = 6e4;
 var FETCH_TIMEOUT_MS = 6e4;
 var FetchTransport = class {
@@ -37,7 +38,33 @@ var FetchTransport = class {
           keepalive: new Blob([body]).size <= MAX_KEEPALIVE_BODY_BYTES,
           ...controller ? { signal: controller.signal } : {}
         };
-        const response = await fetch(this.options.url, requestOptions);
+        const response = await sendFetch(
+          {
+            key: "network:observe.events",
+            title: "Sending events to Corbado Observe",
+            accessNote: "fetch (keepalive) to the Observe ingestion API",
+            group: "Event delivery",
+            origin: "observe-internal",
+            fields: [
+              { path: "response.status", label: "Response code", exposure: "raw" },
+              { path: "response.header.retry-after", label: "Retry delay requested by the server", exposure: "raw" },
+              {
+                path: "response.header.x-corbado-observe-accepted",
+                label: "Whether Observe accepted the events",
+                exposure: "enum",
+                transform: { values: ["1", "other"] }
+              },
+              {
+                path: "response.body",
+                label: "Observe settings in the response",
+                exposure: "raw",
+                transform: { note: "SDK reliability config (HTTP 200 only)" }
+              }
+            ]
+          },
+          this.options.url,
+          requestOptions
+        );
         const result = {
           statusCode: response.status,
           headers: {
@@ -77,7 +104,22 @@ var FetchTransport = class {
   sendBeacon(batch) {
     try {
       this.options.logger.debug(`Sending ${batch.events.length} events via beacon`);
-      if (typeof navigator?.sendBeacon !== "function") {
+      const send = beaconSender({
+        key: "network:observe.events-beacon",
+        title: "Sending events to Corbado Observe when the page closes",
+        accessNote: "navigator.sendBeacon to the Observe ingestion API",
+        group: "Event delivery",
+        origin: "observe-internal",
+        fields: [
+          {
+            path: "result",
+            label: "Whether the browser accepted the data for sending",
+            exposure: "enum",
+            transform: { values: [true, false], note: "whether the browser queued the beacon" }
+          }
+        ]
+      });
+      if (!send) {
         return false;
       }
       batch.meta = {
@@ -90,7 +132,7 @@ var FetchTransport = class {
         // can handle both text/plain and application/json.
         type: "text/plain"
       });
-      return navigator.sendBeacon(this.options.url, blob);
+      return send(this.options.url, blob);
     } catch (error) {
       this.options.logger.error("Failed to send event via beacon", error);
       return false;