@corbado/observe 1.8.0 → 1.9.1

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;

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

@@ -1,12 +1,31 @@
 // src/low-events/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, readInputContentLength } from "../readers/input.mjs";
+import { listenWindow } from "../readers/page.mjs";
 import { readPasswordManagerDomSignals } from "../readers/password-manager-dom.mjs";
 var MOUNT_PROBE_DELAY_MS = 500;
 var FOCUS_PROBE_DELAY_MS = 250;
 function fieldContentLength(field) {
-  if (field.type === "checkbox" || field.type === "radio") return field.checked ? 1 : 0;
-  return field.value.length;
+  return readInputContentLength(
+    {
+      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" },
+        {
+          path: "checked",
+          label: "Whether a checkbox or option is selected",
+          exposure: "enum",
+          transform: { values: [true, false], note: "checkbox and radio only" }
+        }
+      ]
+    },
+    field
+  );
 }
 var LowEventInputTracker = class {
   constructor(logger, inputField, sink) {
@@ -20,6 +39,27 @@ var LowEventInputTracker = class {
       sink.reserveCaptureSeq
     );
     this.pasteObserver = 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" }
+          }
+        ]
+      },
       [inputField],
       logger,
       (ts, _inserted, captureSeq) => {
@@ -36,27 +76,13 @@ var LowEventInputTracker = class {
       },
       sink.reserveCaptureSeq
     );
-    this.boundHandlers = {
-      focus: this.wrapHandler("focus", () => this.handleFocus()),
-      blur: this.wrapHandler("blur", () => this.handleBlur()),
-      pointerdown: this.wrapHandler("pointerdown", () => this.enqueueNonInputEvent("pointerdown")),
-      pointerup: this.wrapHandler("pointerup", () => this.enqueueNonInputEvent("pointerup")),
-      click: this.wrapHandler("click", () => this.enqueueNonInputEvent("click")),
-      input: (event) => {
-        try {
-          this.handleInput(event);
-        } catch (error) {
-          this.logger.error("Failed to observe input", error);
-        }
-      },
-      keyup: this.wrapKeyboardHandler("keyup", (event) => this.handleKeyUp(event)),
-      pageHide: this.wrapHandler("pagehide", () => this.flushForTeardown())
-    };
     this.unregisterInputs = sink.registerInputs?.([inputField], () => this.flushPending());
     this.capturePrefill();
     this.attach();
   }
   unregisterInputs;
+  removeFieldListeners;
+  removePageHide;
   changes;
   pasteObserver;
   emittedSignals = /* @__PURE__ */ new Set();
@@ -64,7 +90,6 @@ var LowEventInputTracker = class {
   mountProbeTimer = null;
   focusProbeTimer = null;
   destroyed = false;
-  boundHandlers;
   destroy() {
     if (this.destroyed) {
       return;
@@ -89,18 +114,93 @@ var LowEventInputTracker = class {
   }
   attach() {
     const input = this.inputField;
-    input.addEventListener("focus", this.boundHandlers.focus);
-    input.addEventListener("blur", this.boundHandlers.blur);
-    input.addEventListener("pointerdown", this.boundHandlers.pointerdown);
-    input.addEventListener("pointerup", this.boundHandlers.pointerup);
-    input.addEventListener("click", this.boundHandlers.click);
-    input.addEventListener("input", this.boundHandlers.input);
-    input.addEventListener("keyup", this.boundHandlers.keyup);
+    this.removeFieldListeners = 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.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,
+      {
+        focus: () => this.handleFocus(),
+        blur: () => this.handleBlur(),
+        pointerdown: () => this.enqueueNonInputEvent("pointerdown"),
+        pointerup: () => this.enqueueNonInputEvent("pointerup"),
+        click: () => this.enqueueNonInputEvent("click"),
+        input: (composing, event) => this.handleInput(event, composing),
+        keyupEscape: () => this.enqueueNonInputEvent("keyup-escape")
+      },
+      (name, run) => {
+        try {
+          run();
+        } catch (error) {
+          if (name === "input") this.logger.error("Failed to observe input", error);
+          else this.logger.error(`Failed to handle low event "${name}"`, error);
+        }
+      }
+    );
     if (typeof window !== "undefined") {
-      window.addEventListener("pagehide", this.boundHandlers.pageHide);
+      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 input low events on unload" }
+            }
+          ]
+        },
+        "pagehide",
+        this.wrapHandler("pagehide", () => this.flushForTeardown())
+      );
     }
     if (typeof document !== "undefined") {
-      if (document.activeElement === input) {
+      if (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] }
+            }
+          ]
+        },
+        [input]
+      )) {
         this.handleFocus();
       }
     }
@@ -109,16 +209,9 @@ var LowEventInputTracker = class {
     }
   }
   detach() {
-    const input = this.inputField;
-    input.removeEventListener("focus", this.boundHandlers.focus);
-    input.removeEventListener("blur", this.boundHandlers.blur);
-    input.removeEventListener("pointerdown", this.boundHandlers.pointerdown);
-    input.removeEventListener("pointerup", this.boundHandlers.pointerup);
-    input.removeEventListener("click", this.boundHandlers.click);
-    input.removeEventListener("input", this.boundHandlers.input);
-    input.removeEventListener("keyup", this.boundHandlers.keyup);
+    this.removeFieldListeners?.();
     if (typeof window !== "undefined") {
-      window.removeEventListener("pagehide", this.boundHandlers.pageHide);
+      this.removePageHide?.();
     }
   }
   pushLow = (low) => {
@@ -129,9 +222,14 @@ var LowEventInputTracker = class {
       if (typeof __CBO_DATA_PMD__ === "boolean" ? __CBO_DATA_PMD__ : this.sink.passwordManagerDomScan?.() !== false) {
         const matches = readPasswordManagerDomSignals({
           key: "dom:password-managers.dom-signals",
+          title: "Password manager traces in the page",
+          accessNote: "DOM markers that password manager extensions insert (attributes, elements, styles)",
+          group: "Password manager detection",
+          origin: "observe-external",
           fields: [
             {
               path: "signals[]",
+              label: "Password manager traces found",
               exposure: "enum",
               transform: { values: ["pa-1", "pa-2", "pa-3", "pa-4", "pa-5", "pa-6"] }
             }
@@ -179,19 +277,9 @@ var LowEventInputTracker = class {
     this.pasteObserver.flush();
     this.enqueueNonInputEvent("blur");
   }
-  handleInput(event) {
+  handleInput(event, composing) {
     if (this.pasteObserver.handlesInput(event)) return;
-    this.changes.record(
-      fieldContentLength(this.inputField),
-      Date.now(),
-      event.isComposing || event.inputType === "insertCompositionText"
-    );
-  }
-  handleKeyUp(event) {
-    if (event.key !== "Escape") {
-      return;
-    }
-    this.enqueueNonInputEvent("keyup-escape");
+    this.changes.record(fieldContentLength(this.inputField), Date.now(), composing);
   }
   flushForTeardown() {
     this.pasteObserver.flush();
@@ -207,15 +295,6 @@ var LowEventInputTracker = class {
       }
     };
   }
-  wrapKeyboardHandler(name, fn) {
-    return (event) => {
-      try {
-        fn(event);
-      } catch (error) {
-        this.logger.error(`Failed to handle low event "${name}"`, error);
-      }
-    };
-  }
 };
 export {
   LowEventInputTracker,