@corbado/observe 0.0.1-next.8 → 0.0.1-next.9

package/dist/index.d.mts

@@ -11,12 +11,16 @@ interface SdkInfo {
 }
 type EventType = "predefined" | "custom" | "error" | "identify";
 type LoginMethodType = "identifier-email" | "passkey" | "passkey-conditional-ui" | "password" | "email-otp" | "email-link" | "phone-otp" | "switch-method" | "reset-flow" | "social-google" | "social-apple" | "social-facebook" | "social-other";
+type FlowType = "login" | "signup" | "recovery" | "enrollment";
 type SocialLoginProviderType = "google" | "apple" | "facebook" | "github" | "microsoft" | "other";
 declare enum AuthEventName {
-    LoginVisible = "login_visible",
-    LoginReset = "login_reset",
-    LoginMethodsDecision = "login_method_decision_offered",
-    AuthDecisionVisible = "auth_decision_visible",
+    FlowStarted = "flow_started",
+    FlowDecided = "flow_decided",
+    FlowFinished = "flow_finished",
+    FlowReset = "flow_reset",
+    AuthMethodDecisionStarted = "auth_method_decision_started",
+    FlowAutoFinished = "flow_auto_finished",
+    AuthDecisionStarted = "auth_decision_started",
     AuthDecisionFinished = "auth_decision_finished",
     ProvideIdentifierStarted = "provide_identifier_started",
     ProvideIdentifierSubmitted = "provide_identifier_submitted",
@@ -41,19 +45,12 @@ declare enum AuthEventName {
     SocialLoginStarted = "social_login_started",
     SocialLoginFinished = "social_login_finished",
     SocialLoginError = "social_login_error",
-    LoginFinish = "login_finish",
-    SignupVisible = "signup_visible",
-    SignupFinish = "signup_finish",
-    SecurityEnrollmentStarted = "security_enrollment_started",
-    SecurityEnrollmentFinished = "security_enrollment_finished",
     PasskeyEnrollmentStartable = "passkey_enrollment_startable",
     PasskeyEnrollmentStarted = "passkey_enrollment_started",
     PasskeyEnrollmentSubmitted = "passkey_enrollment_submitted",
     PasskeyEnrollmentFinished = "passkey_enrollment_finished",
     PasskeyEnrollmentSkipped = "passkey_enrollment_skipped",
     PasskeyEnrollmentError = "passkey_enrollment_error",
-    AccountRecoveryStarted = "account_recovery_started",
-    AccountRecoveryFinished = "account_recovery_finished",
     EmailLinkStartable = "email_link_startable",
     EmailLinkSubmitted = "email_link_submitted",
     EmailLinkFinished = "email_link_finished",
@@ -79,9 +76,6 @@ interface BaseEvent {
     tags?: Record<string, string>;
     deviceInfo?: DeviceInfo;
 }
-type WithSubFlowId<T> = T & {
-    subFlowId?: string;
-};
 type UserReference = {
     userId?: string;
     identifier?: string;
@@ -95,16 +89,32 @@ type NormalizedError = {
     name?: string;
     message: string;
 };
-interface LoginVisible {
-    /**
-     * Where the login form is shown (e.g. `"account"`, `"checkout"`).
-     */
+type FlowStarted = {
+    flowName: FlowType;
+    touchpoint?: string;
+};
+type MultiFlowStarted = {
+    flowNames: FlowType[];
+    defaultFlowName?: FlowType;
     touchpoint?: string;
-    identifierPrefillingExisted?: boolean;
-}
-type IdentifierProvided = UserReference & {
-    availableMethods?: string[];
-    preferredMethod?: string | null;
+};
+type FlowDecided = {
+    flowName: FlowType;
+};
+type FlowFinished = {
+    flowName: FlowType;
+} & UserReference;
+type FlowReset = {
+    flowName: FlowType;
+};
+type FlowAutoFinished = {
+    flowName: FlowType;
+    finishedByFlowName: FlowType;
+} & UserReference;
+type AuthMethodDecisionStarted = {
+    decisionName: string;
+    options: LoginMethodType[];
+    explicitDecisionValue?: string;
 };
 type ProvideIdentifierStart = {};
 type ProvideIdentifierError = UserReference & {
@@ -131,7 +141,6 @@ type PasskeyLoginClientError = {
 };
 type PasskeyLoginStart = {
     explicitSpecType: "passkey-cui" | "passkey-identifier" | "passkey-button";
-    conditional: boolean;
 } & PasskeyLoginStartable;
 type PasskeyLoginStartable = {
     assertionOptions: string;
@@ -150,14 +159,7 @@ type SocialLoginFinish = UserReference & {
 type SocialLoginError = UserReference & {
     errorCode: string;
 };
-type LoginReset = {};
-type LoginFinish = UserReference & {};
-type LoginMethodDecision = {
-    decisionName: string;
-    availableMethods: LoginMethodType[];
-    explicitDecisionValue?: string;
-};
-type AuthDecisionVisible = {
+type AuthDecisionStarted = {
     decisionName: string;
     options: string[];
 };
@@ -166,10 +168,6 @@ type AuthDecisionFinished = {
     options: string[];
     explicitDecisionValue?: string;
 };
-type SignupVisible = {
-    touchpoint?: string;
-};
-type SignupFinish = UserReference & {};
 type PasskeyEnrollmentStartable = {};
 type PasskeyEnrollmentStarted = {
     conditional: boolean;
@@ -229,12 +227,6 @@ type ClientEnvHandleMeta = {
     source: ClientEnvHandleMetaSource;
 };
 type ClientEnvHandleMetaSource = "localstorage" | "cookie" | "native";
-type SecurityEnrollmentStarted = {
-    touchpoint: string;
-} & UserReference;
-type AccountRecoveryStarted = {
-    touchpoint: string;
-};
 type EmailOTPStartable = {};
 type EmailOTPStarted = {};
 type EmailOTPSubmitted = {};
@@ -398,22 +390,121 @@ declare class CorbadoTracker {
     /** @internal */
     track(name: AuthEventName, data: Record<string, any>, userReference?: UserReference, tags?: Record<string, string>, contexts?: Record<string, any>, explicitTimestamp?: number): Promise<void>;
     /**
-     * Track when the login UI becomes visible to the user.
+     * Track when an authentication flow (or flow selection screen) becomes visible.
      *
      * @remarks
-     * Trigger this event when your login form or login page is rendered and visible.
-     * Use the `touchpoint` field to distinguish where the login appears
-     * (e.g. a dedicated login page vs. an inline checkout login).
+     * Call this once when the user first enters an auth touchpoint (for example account login,
+     * checkout login, or account recovery). If users can choose between multiple flows
+     * (such as login vs signup), pass `flowNames` and optionally `defaultFlowName`.
      *
-     * @param data - Event payload.
+     * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
      * @param tags - Optional key-value tags for filtering and segmentation.
      *
      * @example
      * ```typescript
-     * tracker.loginVisible({ touchpoint: "account" });
+     * tracker.flowStarted({
+     *   flowNames: ["login", "signup"],
+     *   defaultFlowName: "login",
+     *   touchpoint: "account",
+     * });
      * ```
      */
-    loginVisible(data: LoginVisible, tags?: Record<string, string>): void;
+    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>): void;
+    /**
+     * Track when the user commits to a specific flow.
+     *
+     * @remarks
+     * Use this after presenting alternatives and once you know which path the user takes
+     * (for example when identifier checks route to login vs signup).
+     *
+     * @param data - Selected flow name.
+     * @param tags - Optional key-value tags for filtering and segmentation.
+     *
+     * @example
+     * ```typescript
+     * tracker.flowDecided({flowName: "signup"});
+     * ```
+     */
+    flowDecided(data: FlowDecided, tags?: Record<string, string>): void;
+    /**
+     * Track when a flow successfully completes.
+     *
+     * @remarks
+     * Fire this when the user has finished the target flow end-to-end, such as completed login,
+     * signup, or recovery. If available, include `userId` and/or `identifier` so the event is
+     * linked to a user reference.
+     *
+     * @param data - Finished flow name plus optional user reference fields.
+     * @param tags - Optional key-value tags for filtering and segmentation.
+     *
+     * @example
+     * ```typescript
+     * tracker.flowFinished({
+     *   flowName: "login",
+     *   userId: "usr_123",
+     *   identifier: "max@example.com",
+     * });
+     * ```
+     */
+    flowFinished(data: FlowFinished, tags?: Record<string, string>): void;
+    /**
+     * Track when an in-progress flow is reset and restarted.
+     *
+     * @remarks
+     * Use this when users abandon the current path and return to the beginning of the same flow,
+     * for example after switching account/identifier and reopening the first step.
+     *
+     * @param data - Flow name being reset.
+     * @param tags - Optional key-value tags for filtering and segmentation.
+     *
+     * @example
+     * ```typescript
+     * tracker.flowReset({flowName: "login"});
+     * ```
+     */
+    flowReset(data: FlowReset, tags?: Record<string, string>): void;
+    /**
+     * Track when a flow is considered finished because another flow finished it implicitly.
+     *
+     * @remarks
+     * Use this for automatic completions where no separate explicit finish action happens in the
+     * current flow. Set `flowName` to the auto-finished flow and `finishedByFlowName` to the flow
+     * that caused it.
+     *
+     * @param data - Auto-finished flow, finishing flow, and optional user reference fields.
+     * @param tags - Optional key-value tags for filtering and segmentation.
+     *
+     * @example
+     * ```typescript
+     * tracker.flowAutoFinished({
+     *   flowName: "signup",
+     *   finishedByFlowName: "login",
+     *   userId: "usr_123",
+     * });
+     * ```
+     */
+    flowAutoFinished(data: FlowAutoFinished, tags?: Record<string, string>): void;
+    /**
+     * Track when you present authentication method choices to the user.
+     *
+     * @remarks
+     * Use this whenever a decision point is shown with a concrete method set, such as
+     * identifier entry options (`d1`) or post-identifier options (`d3`). Set
+     * `explicitDecisionValue` when the options are re-offered after a user action and you want
+     * to capture what triggered that transition.
+     *
+     * @param data - Decision identifier, offered options, and optional transition reason.
+     * @param tags - Optional key-value tags for filtering and segmentation.
+     *
+     * @example
+     * ```typescript
+     * tracker.authMethodsDecisionStarted({
+     *   decisionName: "d3",
+     *   options: ["passkey", "social-google", "password", "reset-flow"],
+     * });
+     * ```
+     */
+    authMethodsDecisionStarted(data: AuthMethodDecisionStarted, tags?: Record<string, string>): void;
     /**
      * Create a trackable identifier-provision operation without immediately firing an event.
      *
@@ -511,24 +602,6 @@ declare class CorbadoTracker {
      * ```
      */
     provideIdentifierError(data: ProvideIdentifierError, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when the login flow is reset.
-     *
-     * @remarks
-     * Fire this event when the user navigates back to the beginning of the login flow,
-     * for example by clicking a "Back" button or choosing "Try another method".
-     * This signals that the current authentication attempt was abandoned.
-     *
-     * @param data - Event payload (currently empty, reserved for future fields).
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.loginReset();
-     * ```
-     */
-    loginReset(data?: LoginReset, tags?: Record<string, string>, contexts?: Record<string, any>): void;
     /**
      * Create a trackable password-login operation and mark it as startable.
      *
@@ -539,7 +612,7 @@ declare class CorbadoTracker {
      * interaction detection (e.g. paste, password-manager usage).
      *
      * @param inputHtmlField - Optional HTML input element to instrument.
-     * @param data
+     * @param data - Optional password-login startable metadata.
      * @param tags - Optional key-value tags for filtering and segmentation.
      * @param contexts - Optional contextual metadata attached to the event.
      * @returns A {@link PasswordOperationLogin} instance.
@@ -695,117 +768,8 @@ declare class CorbadoTracker {
      * ```
      */
     socialLoginFinish(data: SocialLoginFinish, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when the overall login flow finishes successfully.
-     *
-     * @remarks
-     * Fire this as the final event of a successful login, regardless of the
-     * authentication method used. This closes the login funnel that started
-     * with {@link loginVisible}.
-     *
-     * @param data - Event payload (currently empty, reserved for future fields).
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.loginFinish();
-     * ```
-     */
-    loginFinish(data?: LoginFinish, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when the signup UI becomes visible to the user.
-     *
-     * @remarks
-     * Trigger this event when your signup form or registration page is rendered
-     * and visible. Optionally use the `touchpoint` field to distinguish where the
-     * signup appears (e.g. a dedicated registration page vs. an inline checkout signup).
-     *
-     * @param data - Event payload with an optional `touchpoint`.
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.signupVisible({});
-     * ```
-     */
-    signupVisible(data: SignupVisible, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when the signup flow completes and associate the new user.
-     *
-     * @remarks
-     * Fire this after a new account has been created. If `userId` and/or
-     * `identifier` are provided they are extracted and attached as a
-     * {@link UserReference} so subsequent events can be correlated to this user.
-     *
-     * @param data - Event payload, optionally containing `userId` and/or `identifier`.
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.signupFinish({});
-     * ```
-     */
-    signupFinish(data: SignupFinish, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when the user is offered a choice between login methods.
-     *
-     * @remarks
-     * Fire this when your UI presents multiple authentication methods and the
-     * user must choose one. Record `availableMethods` using {@link LoginMethodType}
-     * values and, if applicable, the `explicitDecisionValue` the user selected.
-     *
-     * @param data - Event payload with `decisionName`, `availableMethods`, and optional `explicitDecisionValue`.
-     *
-     * @example
-     * ```typescript
-     * tracker.loginMethodsDecisionOffered({
-     *   decisionName: "d1",
-     *   availableMethods: ["passkey-conditional-ui", "identifier-email", "social-google"],
-     * });
-     * ```
-     */
-    loginMethodsDecisionOffered(data: LoginMethodDecision): void;
-    authDecisionVisible(data: AuthDecisionVisible): void;
+    authDecisionStarted(data: AuthDecisionStarted): void;
     authDecisionFinished(data: AuthDecisionFinished): void;
-    /**
-     * Track when a security enrollment flow starts.
-     *
-     * @remarks
-     * Fire this when the user begins enrolling a new security credential
-     * (e.g. passkey, MFA device). The `touchpoint` indicates where enrollment
-     * was triggered (e.g. `"post-account"`, `"settings"`), and the `userId`
-     * is extracted as a {@link UserReference}.
-     *
-     * @param data - Event payload with `touchpoint` and `userId`.
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.securityEnrollmentStarted({ touchpoint: "post-account", userId: "usr_123" });
-     * ```
-     */
-    securityEnrollmentStarted(data: SecurityEnrollmentStarted, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when a security enrollment completes successfully.
-     *
-     * @remarks
-     * Fire this after the new security credential has been registered
-     * and persisted.
-     *
-     * @param data - Event payload (currently empty, reserved for future fields).
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.securityEnrollmentFinished({});
-     * ```
-     */
-    securityEnrollmentFinished(data: {}, tags?: Record<string, string>, contexts?: Record<string, any>): void;
     /**
      * Create a trackable passkey enrollment operation and mark it as startable.
      *
@@ -825,40 +789,6 @@ declare class CorbadoTracker {
      * ```
      */
     passkeyEnrollmentStartable(data: PasskeyEnrollmentStartable, tags?: Record<string, string>, contexts?: Record<string, any>): PasskeyOperationEnrollment;
-    /**
-     * Track when an account recovery flow starts.
-     *
-     * @remarks
-     * Fire this when the user initiates account recovery (e.g. "Forgot password",
-     * "Can't sign in"). Use the `touchpoint` field to indicate where recovery was
-     * triggered.
-     *
-     * @param data - Event payload with `touchpoint`.
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.accountRecoveryStarted({ touchpoint: "login" });
-     * ```
-     */
-    accountRecoveryStarted(data: AccountRecoveryStarted, tags?: Record<string, string>, contexts?: Record<string, any>): void;
-    /**
-     * Track when an account recovery flow completes successfully.
-     *
-     * @remarks
-     * Fire this after the user has successfully recovered access to their account.
-     *
-     * @param data - Event payload (currently empty, reserved for future fields).
-     * @param tags - Optional key-value tags for filtering and segmentation.
-     * @param contexts - Optional contextual metadata attached to the event.
-     *
-     * @example
-     * ```typescript
-     * tracker.accountRecoveryFinished({});
-     * ```
-     */
-    accountRecoveryFinished(data: {}, tags?: Record<string, string>, contexts?: Record<string, any>): void;
     /**
      * Track when an email link flow starts.
      *
@@ -1065,4 +995,4 @@ declare function init(options: TrackerOptions): CorbadoTracker;
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
 
-export { type AccountRecoveryStarted, type AuthDecisionFinished, type AuthDecisionVisible, AuthEventName, type BaseEvent, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, CookieStorage, CorbadoTracker, type CustomEvent, type DeviceInfo, type DeviceInfoDataWeb, type DeviceType, type EmailLinkError, type EmailLinkFinished, EmailLinkOperation, type EmailLinkStartable, type EmailLinkSubmitted, type EmailOTPError, type EmailOTPFinished, EmailOTPOperation, type EmailOTPResent, type EmailOTPStartable, type EmailOTPStarted, type EmailOTPSubmitted, type Event, type EventBatch, type EventType, type IdentifierProvided, type JavaScriptHighEntropy, LocalStorage, type LoginFinish, type LoginMethodDecision, type LoginMethodType, type LoginReset, type LoginStepPasswordErrorCode, type LoginVisible, type NormalizedError, type PasskeyEnrollmentError, type PasskeyEnrollmentFinished, type PasskeyEnrollmentStartable, type PasskeyEnrollmentStarted, type PasskeyEnrollmentSubmitted, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, PasskeyOperationEnrollment, PasskeyOperationLogin, type PasswordLoginError, type PasswordLoginFinish, type PasswordLoginStartable, type PasswordLoginStarted, PasswordOperationLogin, type PredefinedEvent, type ProvideIdentifierError, type ProvideIdentifierFinish, ProvideIdentifierOperation, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SecurityEnrollmentStarted, SessionStorage, type SetPasswordError, type SetPasswordFinished, SetPasswordOperation, type SetPasswordStartable, type SetPasswordStarted, type SetPasswordSubmitted, type SignupFinish, type SignupVisible, type SocialLoginError, type SocialLoginFinish, type SocialLoginProviderType, type SocialLoginStart, SocialOperationLogin, type StorageEngine, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type User, type UserReference, type WithSubFlowId, getTracker, init, resetSession };
+export { type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionStarted, type BaseEvent, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, CookieStorage, CorbadoTracker, type CustomEvent, type DeviceInfo, type DeviceInfoDataWeb, type DeviceType, type EmailLinkError, type EmailLinkFinished, EmailLinkOperation, type EmailLinkStartable, type EmailLinkSubmitted, type EmailOTPError, type EmailOTPFinished, EmailOTPOperation, type EmailOTPResent, type EmailOTPStartable, type EmailOTPStarted, type EmailOTPSubmitted, type Event, type EventBatch, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type JavaScriptHighEntropy, LocalStorage, type LoginMethodType, type LoginStepPasswordErrorCode, type MultiFlowStarted, type NormalizedError, type PasskeyEnrollmentError, type PasskeyEnrollmentFinished, type PasskeyEnrollmentStartable, type PasskeyEnrollmentStarted, type PasskeyEnrollmentSubmitted, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, PasskeyOperationEnrollment, PasskeyOperationLogin, type PasswordLoginError, type PasswordLoginFinish, type PasswordLoginStartable, type PasswordLoginStarted, PasswordOperationLogin, type PredefinedEvent, type ProvideIdentifierError, type ProvideIdentifierFinish, ProvideIdentifierOperation, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, SessionStorage, type SetPasswordError, type SetPasswordFinished, SetPasswordOperation, type SetPasswordStartable, type SetPasswordStarted, type SetPasswordSubmitted, type SocialLoginError, type SocialLoginFinish, type SocialLoginProviderType, type SocialLoginStart, SocialOperationLogin, type StorageEngine, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type User, type UserReference, getTracker, init, resetSession };