@corbado/observe 1.8.0 → 1.9.0

package/dist/analysis/client.mjs

@@ -4,7 +4,8 @@ import {
   KeyRegistrationOperationFull
 } from "./utils/key-operation-full.mjs";
 import { reserveCaptureSeq } from "./low-events/capture-sequence.mjs";
-import { applySourcePathQuery } from "./utils/source-path.mjs";
+import { readSourcePath } from "./readers/page.mjs";
+import { readUserAgent } from "./readers/device.mjs";
 import { SharedWindowObserver, getCapturePageId } from "./low-events/shared-window-observer.mjs";
 import {
   AuthEventName
@@ -33,7 +34,7 @@ import { PasskeyLoginOperationFull } from "./utils/passkey-login-operation-full.
 import { EmailOtpOperationFull } from "./utils/email-otp-operation-full.mjs";
 import { SmsOtpOperationFull } from "./utils/sms-otp-operation-full.mjs";
 import { isBlockedUserAgent } from "./utils/blocked-user-agents.mjs";
-import { withWebLock } from "./utils/web-lock.mjs";
+import { hasWebLocks, withWebLock } from "./readers/web-lock.mjs";
 import { SDK_NAME, SDK_VERSION } from "./version.mjs";
 import {
   EmailLinkContinuationOperation,
@@ -507,7 +508,23 @@ var CorbadoTracker = class _CorbadoTracker {
     if (typeof navigator === "undefined") {
       return false;
     }
-    return isBlockedUserAgent(navigator.userAgent);
+    return isBlockedUserAgent(
+      readUserAgent({
+        key: "browser-api:sdk.blocked-user-agent",
+        title: "User agent check for crawlers and bots",
+        accessNote: "navigator.userAgent, matched against a list of crawler and bot patterns",
+        group: "Observe SDK state",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "result",
+            label: "Whether the browser looks like a bot",
+            exposure: "computed",
+            transform: { note: "matched against the blocked user-agent list; only the boolean is used (tracking off)" }
+          }
+        ]
+      })
+    );
   }
   resolveSessionId() {
     try {
@@ -678,27 +695,74 @@ var CorbadoTracker = class _CorbadoTracker {
       return current;
     };
     const timeoutMs = this.config.seqLockTimeoutMs;
-    if (timeoutMs === 0 || typeof navigator === "undefined" || !navigator.locks?.request) {
+    if (timeoutMs === 0 || !hasWebLocks({
+      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: "available",
+          label: "Whether the browser supports tab coordination",
+          exposure: "enum",
+          transform: { values: [true, false] }
+        }
+      ]
+    })) {
       return allocate();
     }
-    return withWebLock(this.seqLockName, allocate, {
-      timeoutMs,
-      onTimeout: () => {
-        this.logger.warn(`Sequence Web Lock acquisition timed out after ${timeoutMs}ms; using fallback`);
-        this.reportTelemetry("info", `seq web lock timeout; using fallback, ${timeoutMs}ms`);
+    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.seqLockName,
+      allocate,
+      {
+        timeoutMs,
+        onTimeout: () => {
+          this.logger.warn(`Sequence Web Lock acquisition timed out after ${timeoutMs}ms; using fallback`);
+          this.reportTelemetry("info", `seq web lock timeout; using fallback, ${timeoutMs}ms`);
+        }
       }
-    });
+    );
   }
   resolveTrackingSourcePath() {
     if (typeof window === "undefined") {
       return void 0;
     }
-    const search = applySourcePathQuery(
-      window.location.search,
+    return readSourcePath(
+      {
+        key: "page:location.source-path",
+        title: "Page path and allowed query parameters",
+        accessNote: "location.pathname and location.search; the query is reduced by the sourcePathQuery policy inside the reader (trackingSourcePath)",
+        group: "Page",
+        origin: "observe-external",
+        fields: [
+          { path: "url.path", label: "Page path", exposure: "raw" },
+          {
+            path: "url.query",
+            label: "Page address parameters (allowed ones only)",
+            exposure: "redacted",
+            transform: { note: "sourcePathQuery 'allowlist': values of non-allowlisted keys become '*'; 'all': raw" }
+          }
+        ]
+      },
       this.config.sourcePathQuery,
       this.config.sourcePathQueryAllow
     );
-    return `${window.location.pathname}${search}`;
   }
   /**
    * Per-tab id for event meta, cached after the first successful resolution: the id is
@@ -1535,56 +1599,18 @@ var CorbadoTracker = class _CorbadoTracker {
   smsOtpOperationFull(config) {
     return new SmsOtpOperationFull(this, config);
   }
-  /**
-   * Track a code from an authenticator app (TOTP) through its verification.
-   *
-   * @param config - Optional code input field(s) and spec type (`totp-login` or `totp-enrollment`).
-   * @remarks
-   * There is no send step: the code comes from the user's authenticator, not from the application.
-   * Report the verification request on postResponse. Bind the code input to capture typing and
-   * autofill; use setInputFields when the input is rendered after the operation starts.
-   * @example
-   * ```ts
-   * const totp = tracker.totpOperationFull({ explicitSpecType: "totp-login", inputHtmlField: codeInput });
-   * totp.postResponse.start({});
-   * totp.postResponse.finished({});
-   * ```
-   */
   totpOperationFull(config) {
     return new TotpOperationFull(this, config);
   }
   provideIdentifierOperationFull(config) {
-    return new OperationFullProvideIdentifierWithCUI(this, config);
+    return new OperationFullProvideIdentifierWithCUI(
+      this,
+      config
+    );
   }
   provideDataOperationFull(config) {
     return new ProvideDataOperationFull(this, config);
   }
-  /**
-   * Track one form: a page, step or modal where the user provides one coherent set of data and submits
-   * it, typically as one step of a custom process flow such as an onboarding.
-   *
-   * @param config - The form's stable `name` (required); optionally the names of its `fields`, the
-   *   `inputHtmlFields` to collect interaction signals from, and `startedAt` when the form became
-   *   visible earlier than this call.
-   * @remarks
-   * Create the operation when the form is shown; one operation per visit, so going back to a form
-   * creates a new one with the same name. Report `submit` when the application accepted the form, or
-   * `skip` when the user left it forward without submitting (e.g. "Do it later"). A form that ends with
-   * neither counts as abandoned; one whose last submit failed counts as failed. Without a name the form
-   * is not counted. Send field names only, never values. A form spread over several pages stays one
-   * operation: bind each page's inputs with `setInputFields`.
-   * @example
-   * ```ts
-   * const form = tracker.formOperationFull({ name: "personal-details", fields: ["firstName", "lastName"] });
-   * form.submit.start({});
-   * try {
-   *   await savePersonalDetails(values);
-   *   form.submit.finished({});
-   * } catch (error) {
-   *   form.submit.error(error);
-   * }
-   * ```
-   */
   formOperationFull(config) {
     return new FormOperationFull(this, config);
   }
@@ -1829,7 +1855,7 @@ var PROBE_PAGE_ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwx
 function randomProbePageId() {
   const bytes = new Uint8Array(16);
   try {
-    globalThis.crypto.getRandomValues(bytes);
+    crypto.getRandomValues(bytes);
   } catch {
     for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
   }

package/dist/analysis/config-manager.mjs

@@ -1,5 +1,6 @@
 // src/config-manager.ts
 import { cacheConfig, loadCachedConfig, parseReliabilityConfig } from "./config.mjs";
+import { sendFetch } from "./readers/network.mjs";
 var CONFIG_FETCH_TIMEOUT_MS = 10 * 1e3;
 var CONFIG_REFRESH_INTERVAL_MS = 10 * 60 * 1e3;
 var CONFIG_RETRY_DELAYS_MS = [1e3, 3e3];
@@ -36,11 +37,35 @@ var ConfigManager = class {
     this.requestTimer = controller ? setTimeout(() => controller.abort(), CONFIG_FETCH_TIMEOUT_MS) : void 0;
     let retryable = true;
     try {
-      const response = await fetch(this.url, {
-        method: "GET",
-        cache: "no-store",
-        ...controller ? { signal: controller.signal } : {}
-      });
+      const response = await sendFetch(
+        {
+          key: "network:observe.sdk-config",
+          title: "Observe settings download",
+          accessNote: "fetch to the Observe API; the response is the SDK reliability config",
+          group: "Event delivery",
+          origin: "observe-internal",
+          fields: [
+            { path: "response.status", label: "Response code", exposure: "raw" },
+            {
+              path: "response.header.retry-after",
+              label: "Whether the server asked to retry later",
+              exposure: "presence"
+            },
+            {
+              path: "response.body",
+              label: "Observe settings",
+              exposure: "raw",
+              transform: { note: "SDK reliability config" }
+            }
+          ]
+        },
+        this.url,
+        {
+          method: "GET",
+          cache: "no-store",
+          ...controller ? { signal: controller.signal } : {}
+        }
+      );
       if (!response.ok) {
         retryable = (response.status === 408 || response.status === 429 || response.status >= 500) && !response.headers.has("Retry-After");
         throw new Error(`SDK config request failed (${response.status})`);

package/dist/analysis/device-info-manager.mjs

@@ -1,6 +1,21 @@
 // src/device-info-manager.ts
+import { readDocumentHidden } from "./readers/page.mjs";
 function isDocumentHidden() {
-  return typeof document !== "undefined" && document.visibilityState === "hidden";
+  return typeof document !== "undefined" && 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"] }
+      }
+    ]
+  });
 }
 var DeviceInfoManager = class {
   constructor(logger, source, refreshInterval, attachInterval, diagnostics, onUndelivered) {

package/dist/analysis/device.mjs

@@ -180,7 +180,18 @@ var DeviceCollector = class {
         "navigator.bluetooth.getAvailability",
         () => readBluetoothAvailability({
           key: "browser-api:device.bluetooth-availability",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Bluetooth availability",
+          accessNote: "navigator.bluetooth.getAvailability()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether Bluetooth is available",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -188,9 +199,14 @@ var DeviceCollector = class {
         "PublicKeyCredential.getClientCapabilities",
         () => readClientCapabilities({
           key: "browser-api:device.client-capabilities",
+          title: "Passkey features supported by the browser",
+          accessNote: "PublicKeyCredential.getClientCapabilities(), every returned key",
+          group: "Device information",
+          origin: "observe-external",
           fields: [
             {
               path: "result.<capability>",
+              label: "Supported passkey features",
               exposure: "enum",
               transform: { values: ["true", "false"], note: "open set of capability names, kept as reported" }
             }
@@ -202,7 +218,18 @@ var DeviceCollector = class {
         "PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable",
         () => readUserVerifyingPlatformAuthenticatorAvailable({
           key: "browser-api:device.uvpaa",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Built-in passkey support on the device",
+          accessNote: "PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether the device has a built-in passkey authenticator",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -210,7 +237,18 @@ var DeviceCollector = class {
         "PublicKeyCredential.isConditionalMediationAvailable",
         () => readConditionalMediationAvailable({
           key: "browser-api:device.conditional-mediation",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Passkey autofill availability",
+          accessNote: "PublicKeyCredential.isConditionalMediationAvailable()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether passkey autofill is available",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -218,11 +256,20 @@ var DeviceCollector = class {
         "navigator.userAgentData.getHighEntropyValues",
         () => readJavaScriptHighEntropy({
           key: "browser-api:device.ua-high-entropy",
+          title: "Device platform, version and model reported by the browser",
+          accessNote: "User-Agent Client Hints: navigator.userAgentData.getHighEntropyValues()",
+          group: "Device information",
+          origin: "observe-external",
           fields: [
-            { path: "result.platform", exposure: "raw" },
-            { path: "result.mobile", exposure: "enum", transform: { values: [true, false] } },
-            { path: "result.platformVersion", exposure: "raw" },
-            { path: "result.model", exposure: "raw" }
+            { path: "result.platform", label: "Operating system", exposure: "raw" },
+            {
+              path: "result.mobile",
+              label: "Whether the device is a mobile device",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            },
+            { path: "result.platformVersion", label: "Operating system version", exposure: "raw" },
+            { path: "result.model", label: "Device model", exposure: "raw" }
           ]
         })
       ),
@@ -231,7 +278,18 @@ var DeviceCollector = class {
         "navigator.webdriver",
         () => readWebdriver({
           key: "browser-api:device.webdriver",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Browser automation flag",
+          accessNote: "navigator.webdriver",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether the browser is controlled by automation",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -239,7 +297,11 @@ var DeviceCollector = class {
         "navigator.maxTouchPoints",
         () => readMaxTouchPoints({
           key: "browser-api:device.max-touch-points",
-          fields: [{ path: "result", exposure: "raw" }]
+          title: "Touch screen support",
+          accessNote: "navigator.maxTouchPoints",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [{ path: "result", label: "Number of touch points of the screen", exposure: "raw" }]
         })
       )
     ];
@@ -377,7 +439,18 @@ var DeviceCollector = class {
       source,
       () => typeof __CBO_DATA_PRIVATE_MODE__ === "boolean" && !__CBO_DATA_PRIVATE_MODE__ ? void 0 : readPrivateMode({
         key: "browser-api:device.private-mode",
-        fields: [{ path: "result.isPrivate", exposure: "enum", transform: { values: [true, false] } }],
+        title: "Private browsing mode",
+        accessNote: "detectincognitojs library (IndexedDB, storage quota and browser-specific probes)",
+        group: "Device information",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "result.isPrivate",
+            label: "Whether private browsing is on",
+            exposure: "enum",
+            transform: { values: [true, false] }
+          }
+        ],
         dataConfig: "privateMode"
       })
     );
@@ -456,9 +529,14 @@ var DeviceCollector = class {
   static getUserAgent() {
     return readUserAgent({
       key: "browser-api:device.user-agent",
+      title: "Browser and operating system",
+      accessNote: "navigator.userAgent",
+      group: "Device information",
+      origin: "observe-external",
       fields: [
         {
           path: "result",
+          label: "Browser and operating system",
           exposure: "class",
           transform: {
             classes: [

package/dist/analysis/handoff.mjs

@@ -0,0 +1,7 @@
+// src/handoff.ts
+function acceptHandoffs(step) {
+  return step;
+}
+export {
+  acceptHandoffs
+};

package/dist/analysis/low-events/grouped-input-tracker.mjs

@@ -1,6 +1,8 @@
 // src/low-events/grouped-input-tracker.ts
 import { InputChangeRecorder } from "./input-change-recorder.mjs";
-import { InputPasteObserver } from "./input-paste-observer.mjs";
+import { InputPasteObserver } from "../readers/input-paste.mjs";
+import { observeInputField, readFocusedField, readInputGroupValueLength } from "../readers/input.mjs";
+import { listenWindow } from "../readers/page.mjs";
 var LowEventGroupedInputTracker = class {
   constructor(logger, fields, sink) {
     this.logger = logger;
@@ -13,6 +15,27 @@ var LowEventGroupedInputTracker = class {
       sink.reserveCaptureSeq
     );
     this.paste = new InputPasteObserver(
+      {
+        key: "dom:input.paste",
+        title: "Paste into tracked input fields",
+        accessNote: "paste events on the input elements the integration passes to Observe; pasted values never leave the reader",
+        group: "Input interaction",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "event.paste",
+            label: "Paste into the field",
+            exposure: "presence",
+            transform: { note: "trusted paste events only" }
+          },
+          {
+            path: "value",
+            label: "Length of the pasted text",
+            exposure: "size",
+            transform: { note: "inserted length only; values are compared in memory and discarded" }
+          }
+        ]
+      },
       this.inputs,
       logger,
       (ts, _inserted, captureSeq) => {
@@ -32,35 +55,115 @@ var LowEventGroupedInputTracker = class {
     );
     this.unregisterInputs = sink.registerInputs?.(this.inputs, () => this.flushPending());
     this.capturePrefill();
+    const guard = (_name, run) => this.safe(run);
     for (const input of this.inputs) {
-      this.listen(input, "input", (event) => {
-        if (this.paste.handlesInput(event)) return;
-        this.composing ||= event.isComposing || event.inputType === "insertCompositionText";
-        if (this.changeTimer !== null) return;
-        this.changeTime = Date.now();
-        this.changeSeq = sink.reserveCaptureSeq?.();
-        this.changeTimer = setTimeout(() => this.safe(() => this.flushChanges()), 0);
-      });
-      this.listen(input, "focus", (event) => {
-        if (this.contains(event.relatedTarget)) return;
-        this.emit("focus");
-      });
-      this.listen(input, "blur", (event) => {
-        if (this.contains(event.relatedTarget)) return;
-        this.flushPending();
-        this.emit("blur");
-      });
-      for (const type of ["click", "pointerdown", "pointerup"]) this.listen(input, type, () => this.emit(type));
-      this.listen(input, "keyup", (event) => {
-        if (event.key === "Escape") this.emit("keyup-escape");
-      });
+      this.listeners.push(
+        observeInputField(
+          {
+            key: "dom:input.events",
+            title: "Interaction with tracked input fields",
+            accessNote: "focus, blur, pointerdown, pointerup, click, input and keyup events on the input elements the integration passes to Observe, reduced to booleans and identities",
+            group: "Input interaction",
+            origin: "observe-external",
+            fields: [
+              { path: "event.focus", label: "Field selected", exposure: "presence" },
+              {
+                path: "event.focus.relatedTarget",
+                label: "Whether focus moved between fields of the same group",
+                exposure: "computed",
+                transform: { note: "only whether focus moves within the group" }
+              },
+              { path: "event.blur", label: "Field left", exposure: "presence" },
+              { path: "event.pointerdown", label: "Pointer pressed on the field", exposure: "presence" },
+              { path: "event.pointerup", label: "Pointer released on the field", exposure: "presence" },
+              { path: "event.click", label: "Click on the field", exposure: "presence" },
+              { path: "event.input", label: "Typing in the field", exposure: "presence" },
+              {
+                path: "event.input.isComposing",
+                label: "Whether text is being composed with an input method",
+                exposure: "enum",
+                transform: { values: [true, false] }
+              },
+              {
+                path: "event.keyup.key",
+                label: "Escape key pressed",
+                exposure: "enum",
+                transform: { values: ["Escape", "other"] }
+              }
+            ]
+          },
+          input,
+          {
+            input: (composing, event) => {
+              if (this.paste.handlesInput(event)) return;
+              this.composing ||= composing;
+              if (this.changeTimer !== null) return;
+              this.changeTime = Date.now();
+              this.changeSeq = sink.reserveCaptureSeq?.();
+              this.changeTimer = setTimeout(() => this.safe(() => this.flushChanges()), 0);
+            },
+            focus: (relatedTarget) => {
+              if (this.contains(relatedTarget)) return;
+              this.emit("focus");
+            },
+            blur: (relatedTarget) => {
+              if (this.contains(relatedTarget)) return;
+              this.flushPending();
+              this.emit("blur");
+            },
+            click: () => this.emit("click"),
+            pointerdown: () => this.emit("pointerdown"),
+            pointerup: () => this.emit("pointerup"),
+            keyupEscape: () => this.emit("keyup-escape")
+          },
+          guard,
+          ["input", "focus", "blur", "click", "pointerdown", "pointerup", "keyup"]
+        )
+      );
     }
     if (typeof window !== "undefined")
-      this.listen(window, "pagehide", () => {
-        this.flushPending();
-        sink.flushKeepalive();
-      });
-    if (typeof document !== "undefined" && this.contains(document.activeElement)) {
+      this.listeners.push(
+        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 input low events on unload" }
+              }
+            ]
+          },
+          "pagehide",
+          (_event) => this.safe(() => {
+            this.flushPending();
+            sink.flushKeepalive();
+          })
+        )
+      );
+    if (typeof document !== "undefined" && readFocusedField(
+      {
+        key: "dom:input.focused",
+        title: "Whether a tracked input field has focus",
+        accessNote: "document.activeElement compared with the passed input elements",
+        group: "Input interaction",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "focused",
+            label: "Whether the field is selected",
+            exposure: "enum",
+            transform: { values: [true, false] }
+          }
+        ]
+      },
+      this.inputs
+    )) {
       this.emit("focus");
     }
   }
@@ -78,7 +181,24 @@ var LowEventGroupedInputTracker = class {
     return this.inputs.some((field) => field === target);
   }
   length() {
-    return this.inputs.reduce((total, field) => total + field.value.length, 0);
+    return readInputGroupValueLength(
+      {
+        key: "dom:input.content",
+        title: "Length of the text in tracked input fields",
+        accessNote: "input value length only; the value itself does not leave the reader",
+        group: "Input interaction",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "value.length",
+            label: "Length of the entered text",
+            exposure: "size",
+            transform: { note: "summed over the fields of a group" }
+          }
+        ]
+      },
+      this.inputs
+    );
   }
   safe(action) {
     try {
@@ -87,11 +207,6 @@ var LowEventGroupedInputTracker = class {
       this.logger.error("Failed to observe grouped input", error);
     }
   }
-  listen(target, type, handler) {
-    const wrapped = (event) => this.safe(() => handler(event));
-    target.addEventListener(type, wrapped);
-    this.listeners.push(() => target.removeEventListener(type, wrapped));
-  }
   cancelChange() {
     if (this.changeTimer !== null) clearTimeout(this.changeTimer);
     this.changeTimer = null;