@corbado/observe 1.7.2 → 1.9.0

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

@@ -0,0 +1,302 @@
+// src/low-events/input-tracker.ts
+import { InputChangeRecorder } from "./input-change-recorder.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) {
+  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) {
+    this.logger = logger;
+    this.inputField = inputField;
+    this.sink = sink;
+    this.changes = new InputChangeRecorder(
+      fieldContentLength(inputField),
+      this.pushLow,
+      logger,
+      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) => {
+        this.changes.flush();
+        this.changes.markInputObserved();
+        const oldLength = this.changes.previousLength;
+        this.changes.previousLength = fieldContentLength(inputField);
+        this.pushLow({
+          ...captureSeq === void 0 ? {} : { captureSeq },
+          lowType: "input-paste",
+          ts,
+          inputEffect: fieldContentLength(inputField) === 0 ? "clear" : oldLength === 0 ? "fill" : "modify"
+        });
+      },
+      sink.reserveCaptureSeq
+    );
+    this.unregisterInputs = sink.registerInputs?.([inputField], () => this.flushPending());
+    this.capturePrefill();
+    this.attach();
+  }
+  unregisterInputs;
+  removeFieldListeners;
+  removePageHide;
+  changes;
+  pasteObserver;
+  emittedSignals = /* @__PURE__ */ new Set();
+  firstFocusHandled = false;
+  mountProbeTimer = null;
+  focusProbeTimer = null;
+  destroyed = false;
+  destroy() {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroyed = true;
+    try {
+      if (this.mountProbeTimer !== null) {
+        clearTimeout(this.mountProbeTimer);
+        this.mountProbeTimer = null;
+      }
+      if (this.focusProbeTimer !== null) {
+        clearTimeout(this.focusProbeTimer);
+        this.focusProbeTimer = null;
+      }
+      this.changes.flush();
+      this.unregisterInputs?.();
+      this.pasteObserver.destroy();
+      this.detach();
+    } catch (error) {
+      this.logger.error("Failed to destroy LowEventInputTracker", error);
+    }
+  }
+  attach() {
+    const input = this.inputField;
+    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") {
+      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 (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();
+      }
+    }
+    if (typeof window !== "undefined") {
+      this.mountProbeTimer = setTimeout(() => this.runEnvProbe(), MOUNT_PROBE_DELAY_MS);
+    }
+  }
+  detach() {
+    this.removeFieldListeners?.();
+    if (typeof window !== "undefined") {
+      this.removePageHide?.();
+    }
+  }
+  pushLow = (low) => {
+    this.sink.enqueueLowEvent(low);
+  };
+  runEnvProbe() {
+    try {
+      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"] }
+            }
+          ],
+          dataConfig: "pmd"
+        });
+        const now = Date.now();
+        for (const eventType of matches) {
+          if (this.emittedSignals.has(eventType)) {
+            continue;
+          }
+          this.emittedSignals.add(eventType);
+          this.pushLow({ lowType: eventType, ts: now });
+        }
+      }
+    } catch (error) {
+      this.logger.error("Failed to run input env probe", error);
+    }
+  }
+  scheduleFocusProbe() {
+    if (this.firstFocusHandled) {
+      return;
+    }
+    this.firstFocusHandled = true;
+    this.focusProbeTimer = setTimeout(() => this.runEnvProbe(), FOCUS_PROBE_DELAY_MS);
+  }
+  capturePrefill(newCapture = false) {
+    if (this.destroyed) return;
+    this.flushPending();
+    this.changes.capturePrefill(fieldContentLength(this.inputField), newCapture);
+  }
+  flushPending() {
+    this.pasteObserver.flush();
+    this.changes.flush();
+  }
+  enqueueNonInputEvent(eventType) {
+    this.changes.flush();
+    this.pushLow({ lowType: eventType, ts: Date.now() });
+  }
+  handleFocus() {
+    this.scheduleFocusProbe();
+    this.enqueueNonInputEvent("focus");
+  }
+  handleBlur() {
+    this.pasteObserver.flush();
+    this.enqueueNonInputEvent("blur");
+  }
+  handleInput(event, composing) {
+    if (this.pasteObserver.handlesInput(event)) return;
+    this.changes.record(fieldContentLength(this.inputField), Date.now(), composing);
+  }
+  flushForTeardown() {
+    this.pasteObserver.flush();
+    this.changes.flush();
+    this.sink.flushKeepalive();
+  }
+  wrapHandler(name, fn) {
+    return () => {
+      try {
+        fn();
+      } catch (error) {
+        this.logger.error(`Failed to handle low event "${name}"`, error);
+      }
+    };
+  }
+};
+export {
+  LowEventInputTracker,
+  fieldContentLength
+};

package/dist/analysis/low-events/otp-input-binding.mjs

@@ -0,0 +1,67 @@
+// src/low-events/otp-input-binding.ts
+import { LowEventInputTracker } from "./input-tracker.mjs";
+import { LowEventGroupedInputTracker } from "./grouped-input-tracker.mjs";
+var OTPInputBinding = class {
+  constructor(logger, inputSink, groupSink) {
+    this.logger = logger;
+    this.inputSink = inputSink;
+    this.groupSink = groupSink;
+  }
+  collector;
+  fields = [];
+  grouped = false;
+  destroyed = false;
+  prefillClaimed = false;
+  setFields(fields, grouped = true) {
+    try {
+      if (this.destroyed) return;
+      const next = [...new Set(fields)];
+      if (grouped === this.grouped && next.length === this.fields.length && next.every((field, i) => field === this.fields[i]))
+        return;
+      this.collector?.destroy();
+      this.collector = void 0;
+      this.fields = [];
+      this.grouped = grouped;
+      if (next.length === 0) return;
+      const sink = grouped ? this.groupSink : this.inputSink;
+      const filteredSink = { ...sink, enqueueLowEvent: (low) => this.enqueue(sink, low) };
+      this.collector = grouped ? new LowEventGroupedInputTracker(this.logger, next, filteredSink) : new LowEventInputTracker(this.logger, next[0], filteredSink);
+      this.fields = next;
+    } catch (error) {
+      this.logger.error("Failed to bind OTP inputs", error);
+    }
+  }
+  enqueue(sink, low) {
+    if (low.lowType === "input-prefill") {
+      if (this.prefillClaimed) return;
+      this.prefillClaimed = true;
+    } else if ([
+      "input",
+      "input-idle",
+      "input-clear",
+      "input-paste",
+      "big-input-paste",
+      "big-input-add",
+      "big-input-rem"
+    ].includes(low.lowType)) {
+      this.prefillClaimed = true;
+    }
+    sink.enqueueLowEvent(low);
+  }
+  capturePrefill(newCapture = false) {
+    if (newCapture) this.prefillClaimed = false;
+    this.collector?.capturePrefill(newCapture);
+  }
+  flushPending() {
+    this.collector?.flushPending();
+  }
+  destroy() {
+    this.destroyed = true;
+    this.collector?.destroy();
+    this.collector = void 0;
+    this.fields = [];
+  }
+};
+export {
+  OTPInputBinding
+};

package/dist/analysis/low-events/shared-window-observer.mjs

@@ -0,0 +1,296 @@
+// src/low-events/shared-window-observer.ts
+import { reserveCaptureSeq } from "./capture-sequence.mjs";
+import { v7 as uuidv7 } from "uuid";
+import { createViewportBatcher } from "./viewport-batcher.mjs";
+import { observeWindowLowEvents, readActiveFocus, readFocusedChain } from "../readers/window-events.mjs";
+var documentPageId;
+var getCapturePageId = () => documentPageId ??= uuidv7();
+var SharedWindowObserver = class {
+  constructor(logger, enqueue, flushKeepalive) {
+    this.logger = logger;
+    this.enqueue = enqueue;
+    this.flushKeepalive = flushKeepalive;
+    if (typeof window === "undefined" || typeof document === "undefined") return;
+    this.removers = observeWindowLowEvents(
+      {
+        key: "page:window.low-events",
+        title: "Window focus, visibility, size and back navigation",
+        accessNote: "window blur/focus, document visibilitychange/focusin/focusout/pointerdown, visualViewport resize/scroll, pagehide, Navigation API currententrychange (traverse)",
+        group: "Window interaction",
+        origin: "observe-external",
+        fields: [
+          { path: "event.blur", label: "Window left", exposure: "presence" },
+          { path: "event.focus", label: "Window selected", exposure: "presence" },
+          {
+            path: "event.visibilitychange",
+            label: "Page hidden or shown again",
+            exposure: "enum",
+            transform: { values: ["hidden", "visible"] }
+          },
+          {
+            path: "event.focusout",
+            label: "Whether a tracked field lost focus",
+            exposure: "computed",
+            transform: { note: "only whether a handed-over input lost focus to nothing" }
+          },
+          {
+            path: "event.focusin",
+            label: "Which tracked field gained focus",
+            exposure: "computed",
+            transform: { note: "only which handed-over input gained focus" }
+          },
+          {
+            path: "event.pointerdown",
+            label: "Whether a tracked field was pressed",
+            exposure: "computed",
+            transform: { note: "only whether the pointer went to a handed-over input" }
+          },
+          {
+            path: "event.visualviewport.resize",
+            label: "Duration of zooming or resizing",
+            exposure: "size",
+            transform: { note: "batched duration only" }
+          },
+          {
+            path: "event.visualviewport.scroll",
+            label: "Duration of scrolling",
+            exposure: "size",
+            transform: { note: "batched duration only" }
+          },
+          { path: "event.pagehide", label: "Leaving the page", exposure: "presence" },
+          {
+            path: "event.navigation.back",
+            label: "Going back within the page",
+            exposure: "enum",
+            transform: { values: [true, false], note: "committed same-document traverse to an earlier entry" }
+          }
+        ]
+      },
+      {
+        blur: () => {
+          this.flushInputs();
+          this.bracket = this.context();
+          this.emit({ lowType: "window-blur", ts: Date.now() }, this.bracket);
+        },
+        focus: () => {
+          this.flushInputs();
+          this.emit({ lowType: "window-focus", ts: Date.now() }, this.bracket ?? this.context());
+          this.bracket = void 0;
+        },
+        visibilityChange: (hidden) => {
+          this.flushInputs();
+          this.emit({
+            lowType: `document-visibilitychange-${hidden ? "hidden" : "visible"}`,
+            ts: Date.now()
+          });
+        },
+        focusOut: (target, hasRelatedTarget) => {
+          const registration = this.findInput(target);
+          this.lastBlur = registration && !hasRelatedTarget && Date.now() - this.unrelatedPointerAt > 250 ? { registration, ts: Date.now() } : void 0;
+        },
+        focusIn: (composedPath) => {
+          this.lastBlur = void 0;
+          const field = this.inputFocusListeners.size > 0 && composedPath().find((target) => this.findInput(target));
+          if (field) this.notifyInputFocus(field);
+        },
+        pointerDown: (target) => {
+          if (!this.findInput(target)) {
+            this.lastBlur = void 0;
+            this.unrelatedPointerAt = Date.now();
+          } else this.unrelatedPointerAt = -Infinity;
+        },
+        viewportResize: () => this.extendViewport("resize"),
+        viewportScroll: () => this.extendViewport("scroll"),
+        pageHide: () => {
+          this.flushInputs();
+          this.resize.flush();
+          this.scroll.flush();
+          this.flushKeepalive();
+        },
+        navigateBack: () => {
+          this.flushInputs();
+          this.emit({ lowType: "window-navigate-back", ts: Date.now() });
+        }
+      },
+      (name, run) => {
+        try {
+          run();
+        } catch (error) {
+          this.logger.error(`Failed to observe window ${name}`, error);
+        }
+      }
+    );
+  }
+  inputs = /* @__PURE__ */ new Set();
+  inputFocusListeners = /* @__PURE__ */ new Set();
+  ceremonies = /* @__PURE__ */ new Set();
+  removers = [];
+  lastBlur;
+  bracket;
+  unrelatedPointerAt = -Infinity;
+  destroyed = false;
+  viewportContext = {};
+  resize = createViewportBatcher(
+    (low) => this.emit(low, this.viewportContext.resize),
+    "visualviewport-resize",
+    reserveCaptureSeq
+  );
+  scroll = createViewportBatcher(
+    (low) => this.emit(low, this.viewportContext.scroll),
+    "visualviewport-scroll",
+    reserveCaptureSeq
+  );
+  registerInputs(fields, context, flush) {
+    if (this.destroyed) return () => {
+    };
+    const registration = { fields, context, flush };
+    this.inputs.add(registration);
+    if (this.inputFocusListeners.size > 0 && typeof document !== "undefined") {
+      const focused = readFocusedChain({
+        key: "dom:window.focused-element",
+        title: "Which tracked input field has focus",
+        accessNote: "document.activeElement and the focus event path, matched against the passed input elements",
+        group: "Window interaction",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "activeElement",
+            label: "Which tracked field is selected",
+            exposure: "computed",
+            transform: { note: "identity compared against handed-over inputs only" }
+          }
+        ]
+      });
+      const field = fields.find((candidate) => focused.includes(candidate));
+      if (field) this.notifyInputFocus(field);
+    }
+    return () => {
+      this.inputs.delete(registration);
+      if (this.lastBlur?.registration === registration) this.lastBlur = void 0;
+    };
+  }
+  beginCeremony(context) {
+    const registration = { context, settled: false };
+    if (!this.destroyed) {
+      this.flushInputs();
+      this.ceremonies.add(registration);
+    }
+    const destroy = () => {
+      if (registration.timer) clearTimeout(registration.timer);
+      this.ceremonies.delete(registration);
+      if (this.bracket === registration.context) this.bracket = void 0;
+    };
+    return {
+      settle: (tailMs) => {
+        registration.settled = true;
+        if (registration.timer) clearTimeout(registration.timer);
+        registration.timer = setTimeout(destroy, tailMs);
+      },
+      destroy
+    };
+  }
+  /**
+   * Calls `listener` with the field whenever a registered input gains focus, including one already focused when
+   * registered.
+   */
+  onInputFocus(listener) {
+    if (this.destroyed) return () => {
+    };
+    this.inputFocusListeners.add(listener);
+    return () => this.inputFocusListeners.delete(listener);
+  }
+  notifyInputFocus(field) {
+    for (const listener of this.inputFocusListeners) {
+      try {
+        listener(field);
+      } catch (error) {
+        this.logger.error("Failed to notify registered input focus", error);
+      }
+    }
+  }
+  context() {
+    const active = [...this.ceremonies].filter((item) => !item.settled);
+    if (active.length === 1) return active[0].context;
+    if (active.length > 1) return void 0;
+    const focus = readActiveFocus({
+      key: "dom:window.focused-element",
+      title: "Which tracked input field has focus",
+      accessNote: "document.activeElement and the focus event path, matched against the passed input elements",
+      group: "Window interaction",
+      origin: "observe-external",
+      fields: [
+        {
+          path: "activeElement",
+          label: "Which tracked field is selected",
+          exposure: "computed",
+          transform: { note: "identity compared against handed-over inputs only" }
+        },
+        {
+          path: "activeElement.idle",
+          label: "Whether nothing is selected",
+          exposure: "enum",
+          transform: { values: [true, false], note: "nothing focused (body or none)" }
+        }
+      ]
+    });
+    const input = this.findInput(focus.active);
+    if (input) return input.context();
+    const previous = this.lastBlur;
+    if (previous && Date.now() - previous.ts <= 250 && focus.idle) {
+      return previous.registration.context();
+    }
+    return void 0;
+  }
+  findInput(target) {
+    return [...this.inputs].find((registration) => registration.fields.some((field) => field === target));
+  }
+  /** Flush all registered input batches before a high-level lifecycle boundary. */
+  flushInputs() {
+    for (const input of this.inputs) {
+      try {
+        input.flush();
+      } catch (error) {
+        this.logger.error("Failed to flush window input context", error);
+      }
+    }
+  }
+  emit(low, context) {
+    if (this.destroyed) return;
+    const { sessionId, ...capture } = context ?? {};
+    this.enqueue(
+      {
+        ...low,
+        ...capture,
+        captureSeq: low.captureSeq ?? reserveCaptureSeq(),
+        sourceKind: "window",
+        captureVersion: 1,
+        pageId: getCapturePageId()
+      },
+      sessionId
+    );
+  }
+  extendViewport(kind) {
+    const context = this.context();
+    const previous = this.viewportContext[kind];
+    if (previous?.subflowStartEventId !== context?.subflowStartEventId || previous?.fieldRole !== context?.fieldRole || previous?.sessionId !== context?.sessionId)
+      this[kind].flush();
+    this.viewportContext[kind] = context;
+    this[kind].extend();
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.flushInputs();
+    this.resize.flush();
+    this.scroll.flush();
+    this.destroyed = true;
+    for (const remove of this.removers) remove();
+    for (const ceremony of this.ceremonies) if (ceremony.timer) clearTimeout(ceremony.timer);
+    this.ceremonies.clear();
+    this.inputs.clear();
+    this.inputFocusListeners.clear();
+  }
+};
+export {
+  SharedWindowObserver,
+  getCapturePageId
+};