@corbado/observe 1.7.2 → 1.8.0

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

@@ -0,0 +1,81 @@
+// src/utils/form-operation-full.ts
+import { FormInputBinding } from "../low-events/form-input-binding.mjs";
+import { OperationFull } from "./operation-full.mjs";
+var FORM_FIELDS_MAX_COUNT = 50;
+var FORM_STARTED_AT_MAX_AGE_MS = 6e4;
+var FORM_FIELD_NAME_MAX_LENGTH = 40;
+var FORM_FIELD_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+var FormOperationFull = class extends OperationFull {
+  /** The application accepts the submitted form. */
+  submit;
+  /** The user leaves the form forward without submitting it. */
+  skip;
+  inputBinding;
+  constructor(tracker, config) {
+    super(tracker, "form");
+    this.submit = this.defineStep("submit");
+    this.skip = this.defineStep("skip");
+    void this.subflowStart(formStartData(tracker, config), formStartOptions(tracker, config));
+    this.inputBinding = this.createLowCollector(
+      () => new FormInputBinding(tracker.getLogger(), () => this.lowEventSink("input", "data"))
+    );
+    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);
+  }
+  destroy() {
+    this.inputBinding?.destroy();
+  }
+};
+function formStartOptions(tracker, config) {
+  const startedAt = config?.startedAt;
+  if (startedAt === void 0) return void 0;
+  const now = Date.now();
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt) || startedAt > now || now - startedAt > FORM_STARTED_AT_MAX_AGE_MS) {
+    warn(tracker, "Form: implausible startedAt ignored; using the current time");
+    return void 0;
+  }
+  return { explicitTimestamp: startedAt };
+}
+function formStartData(tracker, config) {
+  const data = {};
+  const name = config?.name;
+  if (typeof name === "string" && name.trim() !== "") {
+    data.name = name;
+  } else {
+    warn(tracker, "Form: missing name; the form will not be counted");
+  }
+  const fields = config?.fields;
+  if (fields === void 0) {
+    return data;
+  }
+  if (!Array.isArray(fields)) {
+    warn(tracker, "Form: fields must be an array of field names; omitted from telemetry");
+    return data;
+  }
+  const valid = fields.filter(
+    (field) => typeof field === "string" && field.length <= FORM_FIELD_NAME_MAX_LENGTH && FORM_FIELD_NAME_PATTERN.test(field)
+  );
+  if (valid.length < fields.length) {
+    warn(tracker, "Form: unsupported field names omitted from telemetry");
+  }
+  if (valid.length > FORM_FIELDS_MAX_COUNT) {
+    warn(tracker, `Form: more than ${FORM_FIELDS_MAX_COUNT} field names; the rest is omitted from telemetry`);
+  }
+  if (valid.length > 0) {
+    data.fields = valid.slice(0, FORM_FIELDS_MAX_COUNT);
+  }
+  return data;
+}
+function warn(tracker, message) {
+  try {
+    tracker.getLogger().warn(message);
+  } catch {
+  }
+}
+export {
+  FormOperationFull
+};

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

@@ -0,0 +1,38 @@
+// src/utils/key-operation-full.ts
+import { OperationFull } from "./operation-full.mjs";
+function specType(tracker, config) {
+  if (config.explicitSpecType === void 0) return void 0;
+  try {
+    tracker.getLogger().warn("Unsupported key operation spec type; omitting it");
+  } catch {
+  }
+  return void 0;
+}
+var KeySigningOperationFull = class extends OperationFull {
+  /** Resolve an eligible key and prepare the input for an actual signing attempt. */
+  prepare;
+  /** Sign and assemble the usable signed artifact. Does not include submitting it. */
+  sign;
+  constructor(tracker, config = {}) {
+    super(tracker, "key-signing");
+    this.prepare = this.defineStep("prepare");
+    this.sign = this.defineStep("sign");
+    void this.subflowStart({ actor: "system", explicitSpecType: specType(tracker, config) });
+  }
+};
+var KeyRegistrationOperationFull = class extends OperationFull {
+  /** Build the request that will establish the key's authority. */
+  prepare;
+  /** Submit and await acceptance: finish only when the key is authorized and usable. */
+  postResponse;
+  constructor(tracker, config = {}) {
+    super(tracker, "key-registration");
+    this.prepare = this.defineStep("prepare");
+    this.postResponse = this.defineStep("post-response");
+    void this.subflowStart({ actor: "system", explicitSpecType: specType(tracker, config) });
+  }
+};
+export {
+  KeyRegistrationOperationFull,
+  KeySigningOperationFull
+};

package/dist/analysis/utils/normalize-error.mjs

@@ -0,0 +1,29 @@
+// src/utils/normalize-error.ts
+function normalizeError(error) {
+  if (error === void 0 || error === null) {
+    return void 0;
+  }
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message
+    };
+  }
+  if (typeof error === "string") {
+    return { message: error };
+  }
+  if (typeof error === "object") {
+    const obj = error;
+    if (typeof obj.message === "string" || typeof obj.code === "string") {
+      return {
+        name: typeof obj.name === "string" ? obj.name : void 0,
+        message: typeof obj.message === "string" ? obj.message : void 0,
+        code: typeof obj.code === "string" ? obj.code : void 0
+      };
+    }
+  }
+  return { message: String(error) };
+}
+export {
+  normalizeError
+};

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

@@ -0,0 +1,46 @@
+// src/utils/operation-full-provide-identifier-with-cui.ts
+import { LowEventInputTracker } from "../low-events/input-tracker.mjs";
+import { OperationFull } from "./operation-full.mjs";
+var OperationFullProvideIdentifierWithCUI = class extends OperationFull {
+  lowEventTracker;
+  cui;
+  provideIdentifier;
+  constructor(tracker, config) {
+    super(tracker, "provide-identifier");
+    this.cui = {
+      trigger: (data, options) => {
+        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
+      ),
+      ceremony: this.defineStep(
+        "cui-ceremony"
+      ),
+      postResponse: this.defineStep("cui-post-response")
+    };
+    this.provideIdentifier = {
+      trigger: (data, options) => {
+        this.trigger(data, options);
+      },
+      clientValidation: this.defineStep("pi-client-validation"),
+      postResponse: this.defineStep("pi-post-response")
+    };
+    void this.subflowStart({ explicitSpecType: config?.explicitSpecType });
+    if (!config?.inputHtmlField) {
+      return;
+    }
+    this.lowEventTracker = this.createLowCollector(
+      () => new LowEventInputTracker(tracker.getLogger(), config.inputHtmlField, this.lowEventSink("input", "identifier"))
+    );
+    this.registerLowFlusher(() => this.lowEventTracker?.flushPending());
+  }
+  destroy() {
+    this.lowEventTracker?.destroy();
+  }
+};
+export {
+  OperationFullProvideIdentifierWithCUI
+};

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

@@ -0,0 +1,235 @@
+// src/utils/operation-full.ts
+import { reserveCaptureSeq } from "../low-events/capture-sequence.mjs";
+import { inferCeremonyInitiator } from "../low-events/ceremony-initiator.mjs";
+import { v7 as uuidv7 } from "uuid";
+import { normalizeError } from "./normalize-error.mjs";
+import { serializeRawError } from "./serialize-raw-error.mjs";
+var CEREMONY_LOW_EVENT_TAIL_MS = 1500;
+var OperationFull = class {
+  constructor(tracker, operationName) {
+    this.tracker = tracker;
+    this.operationName = operationName;
+  }
+  startReference;
+  captureSpecType;
+  captureSessionId;
+  lowFlushers = [];
+  lowPrefillCapturers = [];
+  lowEventSink(sourceKind, fieldRole) {
+    return {
+      reserveCaptureSeq,
+      enqueueLowEvent: (low) => this.tracker.enqueueLowEvent(
+        {
+          ...low,
+          captureSeq: low.captureSeq ?? reserveCaptureSeq(),
+          subflowStartEventId: this.startReference,
+          sourceKind,
+          fieldRole,
+          initiator: low.initiator ?? (fieldRole ? `input-${fieldRole}` : "unknown")
+        },
+        this.captureSessionId
+      ),
+      flushKeepalive: () => this.tracker.lowEventFlushKeepalive(),
+      passwordManagerDomScan: () => this.tracker.isPasswordManagerDomScanEnabled(),
+      registerInputs: (fields, flush) => this.tracker.getWindowObserver().registerInputs(
+        fields,
+        () => ({
+          subflowStartEventId: this.startReference,
+          fieldRole,
+          initiator: fieldRole ? `input-${fieldRole}` : "unknown",
+          sessionId: this.captureSessionId
+        }),
+        flush
+      ),
+      beginCeremony: (initiator) => this.tracker.getWindowObserver().beginCeremony({
+        subflowStartEventId: this.startReference,
+        initiator: initiator ?? "unknown",
+        sessionId: this.captureSessionId
+      })
+    };
+  }
+  createLowCollector(create) {
+    try {
+      const collector = create();
+      this.lowPrefillCapturers.push((newCapture) => collector.capturePrefill(newCapture));
+      return collector;
+    } catch (error) {
+      this.tracker.getLogger().error("Failed to attach low-event collector", error);
+      return void 0;
+    }
+  }
+  registerLowFlusher(flush) {
+    this.lowFlushers.push(flush);
+  }
+  captureOptions(options, reference = this.startReference, sessionId = this.captureSessionId, initiator) {
+    if (!reference && !initiator) return options;
+    const context = {};
+    if (reference) {
+      context.subflowStartEventId = options?.subflowStartEventId ?? reference;
+      context.captureSessionId = options?.captureSessionId ?? sessionId;
+    }
+    if (initiator) context.initiator = options?.initiator ?? initiator;
+    return Object.defineProperties(
+      {},
+      {
+        ...Object.getOwnPropertyDescriptors(options ?? {}),
+        ...Object.getOwnPropertyDescriptors(context)
+      }
+    );
+  }
+  /** Anchor (subflowStartEventId) of the current start; undefined before the first start. */
+  get captureReference() {
+    return this.startReference;
+  }
+  /** Session the current start was tracked under. */
+  get captureSession() {
+    return this.captureSessionId;
+  }
+  /**
+   * Continue an attempt started elsewhere (e.g. on another page of the same session) without
+   * emitting a subflow_started: later steps and low events carry the given anchor and session.
+   */
+  adoptCapture(reference, sessionId, specType) {
+    this.startReference = reference;
+    this.captureSessionId = sessionId;
+    this.captureSpecType = specType;
+  }
+  /**
+   * Emits an additional subflow_started; construction already emits the initial start.
+   * `data` supports SubflowTrigger fields (`actor`, `explicitSpecType`, `ignoreAsInteraction`)
+   * plus free-form extras; see SubflowTrigger for programmatic interaction suppression.
+   */
+  subflowStart(data, options) {
+    try {
+      for (const flush of this.lowFlushers) {
+        try {
+          flush();
+        } catch (error) {
+          this.tracker.getLogger().error("Failed to flush previous low-event context", error);
+        }
+      }
+      this.captureSpecType = data?.explicitSpecType;
+      this.startReference = uuidv7();
+      this.captureSessionId = this.tracker.getSessionId();
+      this.tracker.trackSubflowStarted(this.operationName, data, this.captureOptions(options), this.startReference);
+      this.captureInputPrefills(true);
+    } catch (error) {
+      this.tracker.getLogger().error("Failed to start low-event capture context", error);
+    }
+  }
+  /**
+   * Capture values initialized by the application after constructing this operation, without
+   * dispatching DOM input events. Call immediately after initialization, before user editing.
+   * Each field/group emits at most one prefill per subflow start; values are never recorded.
+   */
+  capturePrefill() {
+    this.captureInputPrefills(false);
+  }
+  captureInputPrefills(newCapture) {
+    for (const capture of this.lowPrefillCapturers) {
+      try {
+        capture(newCapture);
+      } catch (error) {
+        this.tracker.getLogger().error("Failed to capture input prefill", error);
+      }
+    }
+  }
+  /**
+   * @deprecated `subflow_trigger` will be removed in the next major version.
+   */
+  trigger(data, options) {
+    void this.tracker.trackSubflowTrigger(this.operationName, data, this.captureOptions(options));
+  }
+  customStep(stepName) {
+    return this.defineStep(stepName);
+  }
+  subflowStepStarted(stepName, data, options, ignoreAsInteraction) {
+    this.captureSpecType = data?.explicitSpecType ?? this.captureSpecType;
+    void this.tracker.trackSubflowStepStarted(
+      this.operationName,
+      stepName,
+      data,
+      this.captureOptions(options),
+      ignoreAsInteraction
+    );
+  }
+  subflowStepFinished(stepName, data, options) {
+    if (!options?.subflowStartEventId || options.subflowStartEventId === this.startReference) {
+      this.captureSpecType = data?.explicitSpecType ?? this.captureSpecType;
+    }
+    void this.tracker.trackSubflowStepFinished(this.operationName, stepName, data, this.captureOptions(options));
+  }
+  subflowStepError(stepName, data, options) {
+    let payload = data;
+    try {
+      const rawError = this.tracker.getSdkConfig().rawErrors ? options?.rawError : void 0;
+      if (rawError !== void 0) payload = { ...data, rawError: serializeRawError(rawError, options?.rawErrorLimits) };
+    } catch {
+    }
+    void this.tracker.trackSubflowStepError(this.operationName, stepName, payload, this.captureOptions(options));
+  }
+  /**
+   * Decorate a (ceremony) step so window low-event collection follows its lifecycle: `start` arms
+   * the tracker, `finished`/`error`/`errorTyped` schedule disarming after
+   * {@link CEREMONY_LOW_EVENT_TAIL_MS}. A `start` during the tail (ceremony retry) keeps the
+   * tracker armed.
+   */
+  withWindowLowEvents(step, windowTracker) {
+    let ceremonyReference;
+    const settle = (options) => {
+      if (options?.subflowStartEventId && options.subflowStartEventId !== ceremonyReference) return;
+      windowTracker.scheduleDisarm(CEREMONY_LOW_EVENT_TAIL_MS);
+    };
+    const inner = step;
+    return {
+      ...step,
+      start: (data, options) => {
+        ceremonyReference = options?.subflowStartEventId ?? this.startReference;
+        const spec = data?.explicitSpecType ?? this.captureSpecType;
+        const initiator = options?.initiator ?? inferCeremonyInitiator(this.operationName, spec);
+        windowTracker.arm(initiator, spec === "passkey-cui");
+        inner.start(data, initiator ? { ...options, initiator } : options);
+      },
+      finished: (data, options) => {
+        inner.finished(data, options);
+        settle(options);
+      },
+      error: (error, options) => {
+        inner.error(error, options);
+        settle(options);
+      },
+      errorTyped: (error, options) => {
+        inner.errorTyped?.(error, options);
+        settle(options);
+      }
+    };
+  }
+  defineStep(stepName, ignoreAsInteractionOnStart) {
+    let stepReference;
+    let stepSessionId;
+    let stepInitiator;
+    const stepOptions = (options) => this.captureOptions(options, stepReference, stepSessionId, stepInitiator);
+    const step = {
+      start: (data, options) => {
+        stepReference = this.startReference;
+        stepSessionId = this.captureSessionId;
+        stepInitiator = options?.initiator;
+        this.subflowStepStarted(stepName, data, stepOptions(options), ignoreAsInteractionOnStart);
+      },
+      finished: (data, options) => {
+        this.subflowStepFinished(stepName, data, stepOptions(options));
+      },
+      error: (error, options) => {
+        this.subflowStepError(stepName, { error: normalizeError(error) }, stepOptions(options));
+      },
+      errorTyped: (error, options) => {
+        this.subflowStepError(stepName, error, stepOptions(options));
+      }
+    };
+    return step;
+  }
+};
+export {
+  CEREMONY_LOW_EVENT_TAIL_MS,
+  OperationFull
+};

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

@@ -0,0 +1,17 @@
+// src/utils/passkey-deletion-operation-full.ts
+import { OperationFull } from "./operation-full.mjs";
+var PasskeyDeletionOperationFull = class extends OperationFull {
+  /** Optional confirmation dialog: start when it opens, finish when the user confirms. */
+  userConfirmation;
+  /** The deletion request: finish only when the passkey was actually deleted. */
+  deletion;
+  constructor(tracker, _config = {}) {
+    super(tracker, "passkey-deletion");
+    this.userConfirmation = this.defineStep("user-confirmation");
+    this.deletion = this.defineStep("deletion");
+    void this.subflowStart({});
+  }
+};
+export {
+  PasskeyDeletionOperationFull
+};

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

@@ -0,0 +1,32 @@
+// src/utils/passkey-enrollment-operation-full.ts
+import { LowEventWindowTracker } from "../low-events/window-tracker.mjs";
+import { OperationFull } from "./operation-full.mjs";
+var PasskeyEnrollmentOperationFull = class extends OperationFull {
+  getOptions;
+  ceremony;
+  postResponse;
+  lowEventTracker;
+  constructor(tracker, config) {
+    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.ceremony = this.withWindowLowEvents(
+      this.defineStep("ceremony"),
+      this.lowEventTracker
+    );
+    this.postResponse = this.defineStep("post-response");
+    void this.subflowStart({
+      explicitSpecType: config?.explicitSpecType,
+      ...config?.ignoreAsInteraction ? { ignoreAsInteraction: true } : {}
+    });
+  }
+  destroy() {
+    this.lowEventTracker.destroy();
+  }
+};
+export {
+  PasskeyEnrollmentOperationFull
+};

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

@@ -0,0 +1,34 @@
+// src/utils/passkey-login-operation-full.ts
+import { LowEventWindowTracker } from "../low-events/window-tracker.mjs";
+import { OperationFull } from "./operation-full.mjs";
+var PasskeyLoginOperationFull = class extends OperationFull {
+  getOptions;
+  ceremony;
+  postResponse;
+  lowEventTracker;
+  constructor(tracker, config) {
+    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.postResponse = this.defineStep("post-response");
+    void this.subflowStart({ explicitSpecType: config?.explicitSpecType });
+  }
+  /**
+   * @deprecated `subflow_trigger` is not supported for passkey-login and will be removed in the
+   * next major version.
+   */
+  trigger(data, options) {
+    super.trigger(data, options);
+  }
+  destroy() {
+    this.lowEventTracker.destroy();
+  }
+};
+export {
+  PasskeyLoginOperationFull
+};

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

@@ -0,0 +1,27 @@
+// src/utils/password-enrollment-operation-full.ts
+import { LowEventInputTracker } from "../low-events/input-tracker.mjs";
+import { OperationFull } from "./operation-full.mjs";
+var PasswordEnrollmentOperationFull = class extends OperationFull {
+  clientValidation;
+  postResponse;
+  lowEventTracker;
+  constructor(tracker, config) {
+    super(tracker, "password-enrollment");
+    this.clientValidation = this.defineStep("client-validation");
+    this.postResponse = this.defineStep("post-response");
+    void this.subflowStart({ explicitSpecType: config?.explicitSpecType });
+    if (!config?.inputHtmlField) {
+      return;
+    }
+    this.lowEventTracker = this.createLowCollector(
+      () => new LowEventInputTracker(tracker.getLogger(), config.inputHtmlField, this.lowEventSink("input", "password"))
+    );
+    this.registerLowFlusher(() => this.lowEventTracker?.flushPending());
+  }
+  destroy() {
+    this.lowEventTracker?.destroy();
+  }
+};
+export {
+  PasswordEnrollmentOperationFull
+};

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

@@ -0,0 +1,61 @@
+// src/utils/password-login-operation-full.ts
+import { LowEventInputTracker } from "../low-events/input-tracker.mjs";
+import { OperationFull } from "./operation-full.mjs";
+var PasswordLoginOperationFull = class extends OperationFull {
+  clientValidation;
+  postResponse;
+  /**
+   * Conditional-UI passkey ceremony that runs while the password form is mounted. The three steps
+   * are emitted under the same `password-login` subflow so a CUI passkey login on this screen is
+   * attributed to password-login rather than a separate subflow.
+   */
+  cui;
+  lowEventTracker;
+  identifierLowEventTracker;
+  constructor(tracker, config) {
+    super(tracker, "password-login");
+    this.clientValidation = this.defineStep("client-validation");
+    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
+      ),
+      ceremony: this.defineStep("cui-ceremony"),
+      postResponse: this.defineStep("cui-post-response")
+    };
+    void this.subflowStart({ explicitSpecType: config?.explicitSpecType });
+    if (config?.identifierInputHtmlField) {
+      this.identifierLowEventTracker = this.createLowCollector(
+        () => new LowEventInputTracker(
+          tracker.getLogger(),
+          config.identifierInputHtmlField,
+          this.lowEventSink("input", "identifier")
+        )
+      );
+      this.registerLowFlusher(() => this.identifierLowEventTracker?.flushPending());
+    }
+    if (!config?.inputHtmlField) {
+      return;
+    }
+    this.lowEventTracker = this.createLowCollector(
+      () => new LowEventInputTracker(tracker.getLogger(), config.inputHtmlField, this.lowEventSink("input", "password"))
+    );
+    this.registerLowFlusher(() => this.lowEventTracker?.flushPending());
+  }
+  /**
+   * @deprecated `subflow_trigger` is not supported for password-login and will be removed in the
+   * next major version.
+   */
+  trigger(data, options) {
+    super.trigger(data, options);
+  }
+  destroy() {
+    this.lowEventTracker?.destroy();
+    this.identifierLowEventTracker?.destroy();
+  }
+};
+export {
+  PasswordLoginOperationFull
+};