@corbado/observe 1.8.0 → 1.9.1

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;

package/dist/analysis/utils/email-link-operation-full.mjs

@@ -2,6 +2,7 @@
 import { v7 as uuidv7 } from "uuid";
 import { OperationFull } from "./operation-full.mjs";
 import { findEmailLinkStart, markEmailLinkContinued, rememberEmailLinkStart } from "./email-link-continuity.mjs";
+import { listenWindow } from "../readers/page.mjs";
 var EmailLinkOperationFull = class extends OperationFull {
   send;
   postResponse;
@@ -42,6 +43,7 @@ var EmailLinkContinuationOperation = class extends OperationFull {
   started = false;
   deferred = [];
   onPageHide = () => this.flush();
+  removePageHide;
   constructor(tracker, config = {}) {
     super(tracker, "email-link");
     this.continuationTracker = tracker;
@@ -65,7 +67,25 @@ var EmailLinkContinuationOperation = class extends OperationFull {
     if (this.transaction) {
       this.startDetached(this.createdAt);
     } else if (typeof window !== "undefined") {
-      window.addEventListener("pagehide", this.onPageHide);
+      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 a detached email-link continuation on unload" }
+            }
+          ]
+        },
+        "pagehide",
+        this.onPageHide
+      );
     }
   }
   /** Transaction ID of the continued email link, when known. */
@@ -113,7 +133,7 @@ var EmailLinkContinuationOperation = class extends OperationFull {
     }
   }
   removePageHideListener() {
-    if (typeof window !== "undefined") window.removeEventListener("pagehide", this.onPageHide);
+    if (typeof window !== "undefined") this.removePageHide?.();
   }
   /** Defer step calls until the detached start is emitted; mark the continued link on completion. */
   deferrable(step, completesLink = false) {

package/dist/analysis/utils/email-otp-operation-full.mjs

@@ -26,7 +26,6 @@ var EmailOtpOperationFull = class extends OperationFull {
     }
     this.registerLowFlusher(() => this.lowEventTracker?.flushPending());
   }
-  /** Rebind the ordered OTP group without starting a new subflow. An empty list detaches it. */
   setInputFields(fields) {
     this.lowEventTracker?.setFields(fields);
   }

package/dist/analysis/utils/form-operation-full.mjs

@@ -22,7 +22,6 @@ var FormOperationFull = class extends OperationFull {
     this.registerLowFlusher(() => this.inputBinding?.flushPending());
     if (config?.inputHtmlFields?.length) this.setInputFields(config.inputHtmlFields);
   }
-  /** Bind the fields the form shows now, without starting a new subflow. An empty list detaches all. */
   setInputFields(fields) {
     this.inputBinding?.setFields(fields);
   }

package/dist/analysis/utils/operation-full-provide-identifier-with-cui.mjs

@@ -1,6 +1,7 @@
 // src/utils/operation-full-provide-identifier-with-cui.ts
 import { LowEventInputTracker } from "../low-events/input-tracker.mjs";
 import { OperationFull } from "./operation-full.mjs";
+import { acceptHandoffs } from "../handoff.mjs";
 var OperationFullProvideIdentifierWithCUI = class extends OperationFull {
   lowEventTracker;
   cui;
@@ -12,14 +13,13 @@ var OperationFullProvideIdentifierWithCUI = class extends OperationFull {
         this.trigger(data, options);
       },
       // getOptions only fetches assertion options; it is not a user interaction on its own.
-      getOptions: this.defineStep(
-        "cui-get-options",
-        true
+      getOptions: acceptHandoffs(
+        this.defineStep("cui-get-options", true)
       ),
-      ceremony: this.defineStep(
-        "cui-ceremony"
+      ceremony: acceptHandoffs(
+        this.defineStep("cui-ceremony")
       ),
-      postResponse: this.defineStep("cui-post-response")
+      postResponse: acceptHandoffs(this.defineStep("cui-post-response"))
     };
     this.provideIdentifier = {
       trigger: (data, options) => {

package/dist/analysis/utils/passkey-enrollment-operation-full.mjs

@@ -1,6 +1,7 @@
 // src/utils/passkey-enrollment-operation-full.ts
 import { LowEventWindowTracker } from "../low-events/window-tracker.mjs";
 import { OperationFull } from "./operation-full.mjs";
+import { acceptHandoffs } from "../handoff.mjs";
 var PasskeyEnrollmentOperationFull = class extends OperationFull {
   getOptions;
   ceremony;
@@ -10,14 +11,16 @@ var PasskeyEnrollmentOperationFull = class extends OperationFull {
     super(tracker, "passkey-enrollment");
     this.lowEventTracker = new LowEventWindowTracker(tracker.getLogger(), this.lowEventSink("ceremony"));
     this.registerLowFlusher(() => this.lowEventTracker.disarm());
-    this.getOptions = this.defineStep(
-      "get-options"
+    this.getOptions = acceptHandoffs(
+      this.defineStep("get-options")
     );
-    this.ceremony = this.withWindowLowEvents(
-      this.defineStep("ceremony"),
-      this.lowEventTracker
+    this.ceremony = acceptHandoffs(
+      this.withWindowLowEvents(
+        this.defineStep("ceremony"),
+        this.lowEventTracker
+      )
     );
-    this.postResponse = this.defineStep("post-response");
+    this.postResponse = acceptHandoffs(this.defineStep("post-response"));
     void this.subflowStart({
       explicitSpecType: config?.explicitSpecType,
       ...config?.ignoreAsInteraction ? { ignoreAsInteraction: true } : {}

package/dist/analysis/utils/passkey-login-operation-full.mjs

@@ -1,6 +1,7 @@
 // src/utils/passkey-login-operation-full.ts
 import { LowEventWindowTracker } from "../low-events/window-tracker.mjs";
 import { OperationFull } from "./operation-full.mjs";
+import { acceptHandoffs } from "../handoff.mjs";
 var PasskeyLoginOperationFull = class extends OperationFull {
   getOptions;
   ceremony;
@@ -10,12 +11,16 @@ var PasskeyLoginOperationFull = class extends OperationFull {
     super(tracker, "passkey-login");
     this.lowEventTracker = new LowEventWindowTracker(tracker.getLogger(), this.lowEventSink("ceremony"));
     this.registerLowFlusher(() => this.lowEventTracker.disarm());
-    this.getOptions = this.defineStep("get-options");
-    this.ceremony = this.withWindowLowEvents(
-      this.defineStep("ceremony"),
-      this.lowEventTracker
+    this.getOptions = acceptHandoffs(
+      this.defineStep("get-options")
     );
-    this.postResponse = this.defineStep("post-response");
+    this.ceremony = acceptHandoffs(
+      this.withWindowLowEvents(
+        this.defineStep("ceremony"),
+        this.lowEventTracker
+      )
+    );
+    this.postResponse = acceptHandoffs(this.defineStep("post-response"));
     void this.subflowStart({ explicitSpecType: config?.explicitSpecType });
   }
   /**

package/dist/analysis/utils/password-login-operation-full.mjs

@@ -1,6 +1,7 @@
 // src/utils/password-login-operation-full.ts
 import { LowEventInputTracker } from "../low-events/input-tracker.mjs";
 import { OperationFull } from "./operation-full.mjs";
+import { acceptHandoffs } from "../handoff.mjs";
 var PasswordLoginOperationFull = class extends OperationFull {
   clientValidation;
   postResponse;
@@ -18,11 +19,14 @@ var PasswordLoginOperationFull = class extends OperationFull {
     this.postResponse = this.defineStep("post-response");
     this.cui = {
       // getOptions only fetches assertion options; it is not a user interaction on its own.
-      getOptions: this.defineStep(
-        "cui-get-options",
-        true
+      getOptions: acceptHandoffs(
+        this.defineStep("cui-get-options", true)
+      ),
+      ceremony: acceptHandoffs(
+        this.defineStep(
+          "cui-ceremony"
+        )
       ),
-      ceremony: this.defineStep("cui-ceremony"),
       postResponse: this.defineStep("cui-post-response")
     };
     void this.subflowStart({ explicitSpecType: config?.explicitSpecType });

package/dist/analysis/utils/password-manager-sampler.mjs

@@ -1,4 +1,5 @@
 // src/utils/password-manager-sampler.ts
+import { listenWindow, readDocumentComplete } from "../readers/page.mjs";
 import {
   readPasswordManagerExtensions
 } from "../readers/password-manager-extensions.mjs";
@@ -12,15 +13,49 @@ var PasswordManagerSampler = class {
     this.isEnabled = isEnabled;
     if (typeof window === "undefined" || typeof document === "undefined") return;
     this.sample();
-    if (document.readyState === "complete") {
+    if (readDocumentComplete({
+      key: "page:lifecycle.ready-state",
+      title: "Page load state",
+      accessNote: "document.readyState",
+      group: "Page lifecycle",
+      origin: "observe-external",
+      fields: [
+        {
+          path: "readyState",
+          label: "Whether the page has finished loading",
+          exposure: "enum",
+          transform: { values: ["complete", "other"] }
+        }
+      ]
+    })) {
       this.sampleAfter(LOAD_RESAMPLE_DELAY_MS);
     } else {
       const onLoad = () => {
         this.sampleWhenIdle();
         this.sampleAfter(LOAD_RESAMPLE_DELAY_MS);
       };
-      window.addEventListener("load", onLoad, { once: true });
-      this.removers.push(() => window.removeEventListener("load", onLoad));
+      this.removers.push(
+        listenWindow(
+          {
+            key: "page:lifecycle.load",
+            title: "Page load",
+            accessNote: "load event on window",
+            group: "Page lifecycle",
+            origin: "observe-external",
+            fields: [
+              {
+                path: "event.load",
+                label: "Page finished loading",
+                exposure: "presence",
+                transform: { note: "schedules a password manager sample" }
+              }
+            ]
+          },
+          "load",
+          onLoad,
+          { once: true }
+        )
+      );
     }
     const removeFocus = windowObserver.onInputFocus((field) => {
       if (!this.isEnabled() || this.sampledFields.has(field)) return;
@@ -89,9 +124,14 @@ var PasswordManagerSampler = class {
     try {
       const found = readPasswordManagerExtensions({
         key: "browser-api:password-managers.extensions",
+        title: "Installed password manager extensions",
+        accessNote: "globals and DOM elements that known password manager extensions inject",
+        group: "Password manager detection",
+        origin: "observe-external",
         fields: [
           {
             path: "result[].name",
+            label: "Names of known password managers found",
             exposure: "enum",
             transform: {
               values: [
@@ -107,7 +147,7 @@ var PasswordManagerSampler = class {
             }
           },
           // Read to merge samples, never reported (takeReport keeps only the name).
-          { path: "result[].signedIn", exposure: "none" }
+          { path: "result[].signedIn", label: "Whether the password manager is signed in", exposure: "none" }
         ],
         dataConfig: "pmd"
       });

package/dist/analysis/utils/sms-otp-operation-full.mjs

@@ -26,7 +26,6 @@ var SmsOtpOperationFull = class extends OperationFull {
     }
     this.registerLowFlusher(() => this.lowEventTracker?.flushPending());
   }
-  /** Rebind the ordered OTP group without starting a new subflow. An empty list detaches it. */
   setInputFields(fields) {
     this.lowEventTracker?.setFields(fields);
   }

package/dist/analysis/utils/totp-operation-full.mjs

@@ -22,7 +22,6 @@ var TotpOperationFull = class extends OperationFull {
     }
     this.registerLowFlusher(() => this.lowEventTracker?.flushPending());
   }
-  /** Rebind the ordered code input group without starting a new subflow. An empty list detaches it. */
   setInputFields(fields) {
     this.lowEventTracker?.setFields(fields);
   }

package/dist/analysis/version.mjs

@@ -1,6 +1,6 @@
 // src/version.ts
 var SDK_NAME = "@corbado/observe";
-var SDK_VERSION = true ? "1.8.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.9.1" : "0.0.0-dev";
 export {
   SDK_NAME,
   SDK_VERSION