@corbado/observe 0.12.0 → 0.14.0

package/dist/index.d.mts

@@ -24,6 +24,8 @@ declare enum AuthEventName {
     SubflowError = "subflow_error",
     SubflowStarted = "subflow_started",
     SubflowFinished = "subflow_finished",
+    /** Client-side flow enrichment (the server accepts `session_enriched` as a legacy alias). */
+    FlowEnriched = "flow_enriched",
     Conversion = "conversion"
 }
 interface BaseEvent {
@@ -51,6 +53,15 @@ interface BaseEvent {
 type UserReference = {
     userId?: string;
     identifier?: string;
+    /** Shared UUID used to link sessions across environments. */
+    crossEnvironmentTransactionID?: string;
+};
+type LegacyUserReference = {
+    /** @deprecated Use tracker.setUser() within the active flow instead. */
+    userId?: string;
+    /** @deprecated Use tracker.setUser() within the active flow instead. */
+    identifier?: string;
+    /** @deprecated Use tracker.setUser() within the active flow instead. */
     crossEnvironmentTransactionID?: string;
 };
 /**
@@ -83,11 +94,11 @@ type Conversion = {
     name: string;
     /** Where the conversion happened, e.g. `"checkout"` or `"product-page"`. */
     touchpoint?: string;
-} & UserReference;
+} & LegacyUserReference;
 type FlowFinished = {
     flowName: FlowType;
     explicitOutcome?: "skipped" | "visible-auto-skip" | "invisible";
-} & UserReference;
+} & LegacyUserReference;
 type FlowReset = {
     flowName?: FlowType;
 };
@@ -97,7 +108,7 @@ type MultiFlowReset = {
 type FlowAutoFinished = {
     flowName: FlowType;
     finishedByFlowName: FlowType;
-} & UserReference;
+} & LegacyUserReference;
 type AuthMethodDecisionStarted = {
     decisionName: string;
     options: (AuthMethodType | (string & {}))[];
@@ -105,15 +116,16 @@ type AuthMethodDecisionStarted = {
 };
 type AuthMethodDecisionFinished = {
     decisionName: string;
-    options: (AuthMethodType | (string & {}))[];
+    /** Optional — when omitted, the backend completes the open decision of the same name using its declared options (classifier follow-up). */
+    options?: (AuthMethodType | (string & {}))[];
     explicitDecisionValue?: string;
 };
 type ProvideIdentifierStart = {};
-type ProvideIdentifierError = UserReference & {
+type ProvideIdentifierError = LegacyUserReference & {
     errorCode?: string;
     error?: any;
 };
-type ProvideIdentifierFinish = UserReference & {
+type ProvideIdentifierFinish = LegacyUserReference & {
     identifierPrefillingCreated?: boolean;
 };
 type PasskeyLoginClientError = {
@@ -125,7 +137,7 @@ type PasskeyLoginStartable = {
 type PasskeyLoginSubmitted = {
     assertionResponse: string;
 };
-type PasskeyLoginFinish = UserReference & {};
+type PasskeyLoginFinish = LegacyUserReference & {};
 type AuthDecisionStarted = {
     decisionName: string;
     options: string[];
@@ -136,6 +148,7 @@ type AuthDecisionFinished = {
     explicitDecisionValue?: string;
 };
 type StepOptions = {
+    /** @deprecated Use tracker.setUser() within the active flow instead. */
     userReference?: UserReference;
     explicitTimestamp?: number;
     /** Per-call experiment override (experiment key → variant), merged over the persistent assignments. */
@@ -144,6 +157,15 @@ type StepOptions = {
 type SubflowTrigger = {
     actor: "system" | "user";
     explicitSpecType?: string;
+    /**
+     * Declares this subflow_started / subflow_trigger as not user-driven, excluding it from
+     * interaction-evidence calculations on the backend: a started subflow that produces no step
+     * afterwards is classified as a "no-followup" error unless this flag is set. Set it when the
+     * integration fires the start programmatically (e.g. an automatic passkey attempt after
+     * identifier lookup) and an abandoned attempt is expected rather than an error signal.
+     * Optional; absent/false means the event counts (legacy behavior).
+     */
+    ignoreAsInteraction?: boolean;
 };
 interface PredefinedEvent extends BaseEvent {
     type: "predefined";
@@ -486,7 +508,15 @@ declare abstract class OperationFull {
     private tracker;
     private operationName;
     constructor(tracker: CorbadoTracker, operationName: SubflowType);
+    /**
+     * 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: any, options?: StepOptions): void;
+    /**
+     * @deprecated `subflow_trigger` will be removed in the next major version.
+     */
     trigger(data: SubflowTrigger, options?: StepOptions): void;
     customStep<TStart = {}, TFinished = {}>(stepName: string): StepHelper<TStart, TFinished>;
     protected subflowStepStarted(stepName: string, data: any, options?: StepOptions, ignoreAsInteraction?: boolean): void;
@@ -540,12 +570,16 @@ type PasskeyLoginPostResponseStart = {
      */
     assertionResponse?: string;
 };
+type PasskeyLoginOperationConfig = {
+    /** The classifier drops the attempt if no spec type arrives on any of its events — supply it here or on a step's start data as soon as known. */
+    explicitSpecType?: PasskeyOperationLoginExplicitSpecType;
+};
 declare class PasskeyLoginOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyLoginGetOptionsStart, PasskeyLoginGetOptionsFinished>;
     readonly ceremony: StepHelper<PasskeyLoginCeremonyStart, PasskeyLoginCeremonyFinished>;
     readonly postResponse: StepHelper<PasskeyLoginPostResponseStart>;
     private lowEventTracker;
-    constructor(tracker: CorbadoTracker);
+    constructor(tracker: CorbadoTracker, config?: PasskeyLoginOperationConfig);
     /**
      * @deprecated `subflow_trigger` is not supported for passkey-login and will be removed in the
      * next major version.
@@ -591,14 +625,29 @@ type EmailLinkOperationSendStart = {
 type EmailLinkOperationPostResponseStart = {
     explicitSpecType?: EmailLinkOperationSpecType;
 };
+type EmailLinkOperationConfig = {
+    /** The classifier drops the attempt if no spec type arrives on any of its events — supply it here or on a step's start data as soon as known. */
+    explicitSpecType?: EmailLinkOperationSpecType;
+};
 declare class EmailLinkOperationFull extends OperationFull {
     readonly send: StepHelper<EmailLinkOperationSendStart>;
     readonly postResponse: StepHelper<EmailLinkOperationPostResponseStart>;
     readonly resend: StepHelper;
-    constructor(tracker: CorbadoTracker);
+    constructor(tracker: CorbadoTracker, config?: EmailLinkOperationConfig);
 }
 
-type PasskeyOperationEnrollmentExplicitSpecType = "conditional-auto-manual" | "auto-manual" | "manual";
+/**
+ * Passkey-enrollment spec types. Two vocabularies coexist:
+ *
+ * - ATTEMPT-scoped (preferred): one subflow per attempt KIND — `"conditional"` (silent conditional
+ *   create), `"auto"` (automatic required-mediation prompt fired by the integration) or `"manual"`
+ *   (fired by the user's button). Create a NEW operation for every attempt; the backend opens a new
+ *   subflow whenever the spec changes, so "auto prompt dismissed, then completed via the button" is two
+ *   subflows and stays distinguishable from "completed by the auto prompt".
+ * - OFFER-scoped (legacy): one subflow per offer — `"conditional-auto-manual"` / `"auto-manual"` name
+ *   the offer mode, and the completing ceremony's `mediation` tells the completion variants apart.
+ */
+type PasskeyOperationEnrollmentExplicitSpecType = "conditional" | "auto" | "manual" | "conditional-auto-manual" | "auto-manual";
 type PasskeyEnrollmentGetOptionsStart = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
 };
@@ -626,7 +675,15 @@ type PasskeyEnrollmentPostResponseStart = {
     attestationResponse?: string;
 };
 type PasskeyEnrollmentOperationConfig = {
+    /** The classifier drops the attempt if no spec type arrives on any of its events — supply it here or on a step's start data as soon as known. */
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
+    /**
+     * Marks the auto-emitted `subflow_started` as not user-driven (see SubflowTrigger.ignoreAsInteraction).
+     * Set it for attempts the integration fires without a user gesture and without a visible surface —
+     * e.g. a `"conditional"` attempt — so a start that never produced a step is not read as a user asking
+     * to enroll.
+     */
+    ignoreAsInteraction?: boolean;
 };
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
@@ -662,14 +719,11 @@ type PasswordLoginCUIGetOptionsFinished = {
 type PasswordLoginCUICeremonyStart = {
     explicitSpecType?: PasswordLoginCUISpecType;
 };
-type PasswordLoginAutoTrackConfig = {
-    explicitSpecType: "password-known-identifier";
-    /** The password input field. */
-    inputHtmlField: HTMLInputElement;
-} | {
-    explicitSpecType: "password-with-identifier";
-    /** The password input field. */
-    inputHtmlField: HTMLInputElement;
+type PasswordLoginExplicitSpecType = "password-known-identifier" | "password-with-identifier";
+type PasswordLoginConfig = {
+    explicitSpecType?: PasswordLoginExplicitSpecType;
+    /** The password input field. When set, low-event input tracking is attached to it. */
+    inputHtmlField?: HTMLInputElement;
     /**
      * The identifier (e.g. email) input field. Accepted but not tracked yet — low-event
      * tracking for a second field lands together with per-field attribution.
@@ -690,7 +744,7 @@ declare class PasswordLoginOperationFull extends OperationFull {
         postResponse: StepHelper;
     };
     private lowEventTracker?;
-    constructor(tracker: CorbadoTracker, autoTrackConfig?: PasswordLoginAutoTrackConfig);
+    constructor(tracker: CorbadoTracker, config?: PasswordLoginConfig);
     /**
      * @deprecated `subflow_trigger` is not supported for password-login and will be removed in the
      * next major version.
@@ -704,15 +758,17 @@ type PasswordEnrollmentTypedError = {
 };
 type PasswordEnrollmentTypedErrorCode = "requirements_not_fulfilled";
 type PasswordEnrollmentExplicitSpecType = "password-set" | "password-reset";
-type PasswordEnrollmentAutoTrackConfig = {
+type PasswordEnrollmentConfig = {
+    /** The classifier drops the attempt if no spec type arrives on any of its events — supply it here or on a step's start data as soon as known. */
     explicitSpecType?: PasswordEnrollmentExplicitSpecType;
+    /** The password input field. When set, low-event input tracking is attached to it. */
     inputHtmlField?: HTMLInputElement;
 };
 declare class PasswordEnrollmentOperationFull extends OperationFull {
     readonly clientValidation: StepHelper;
     readonly postResponse: StepHelper<{}, {}, PasswordEnrollmentTypedError>;
     private lowEventTracker?;
-    constructor(tracker: CorbadoTracker, autoTrackConfig?: PasswordEnrollmentAutoTrackConfig);
+    constructor(tracker: CorbadoTracker, config?: PasswordEnrollmentConfig);
     destroy(): void;
 }
 
@@ -736,16 +792,15 @@ type PasskeyLoginCUIGetOptionsFinished = {
     assertionOptions: string;
 };
 type OperationFullProvideIdentifierWithCUIConfig = {
+    /** When set, low event collection is enabled for the input field. */
     inputHtmlField?: HTMLInputElement;
     explicitSpecType?: ProvideIdentifierSpecType;
 };
-declare class OperationFullProvideIdentifierWithCUI {
-    private tracker;
+declare class OperationFullProvideIdentifierWithCUI extends OperationFull {
     private lowEventTracker?;
     readonly cui: {
         /**
-         * @deprecated `subflow_trigger` is not supported for the CUI part of provide-identifier and
-         * will be removed in the next major version.
+         * @deprecated `subflow_trigger` will be removed in the next major version.
          */
         trigger: (data: SubflowTrigger, options?: StepOptions) => void;
         getOptions: StepHelper<PasskeyLoginCUIGetOptionsStart, PasskeyLoginCUIGetOptionsFinished>;
@@ -754,32 +809,34 @@ declare class OperationFullProvideIdentifierWithCUI {
     };
     readonly provideIdentifier: {
         /**
-         * @deprecated `subflow_trigger` is not supported for provide-identifier and will be removed
-         * in the next major version.
+         * @deprecated `subflow_trigger` will be removed in the next major version.
          */
         trigger: (data: SubflowTrigger, options?: StepOptions) => void;
         clientValidation: StepHelper;
         postResponse: StepHelper<ProvideIdentifierPostResponseStart>;
     };
     constructor(tracker: CorbadoTracker, config?: OperationFullProvideIdentifierWithCUIConfig);
-    private createStep;
     destroy(): void;
 }
 
 type SocialLoginSpecType = "pre-identifier" | "post-identifier";
 type SocialLoginGetRedirectUrlStart = {
     provider?: SocialLoginProviderType;
-    explicitSpecType: SocialLoginSpecType;
+    explicitSpecType?: SocialLoginSpecType;
 };
 type SocialLoginGetRedirectUrlFinished = {};
 type SocialLoginExchangeCodeStart = {
     provider?: SocialLoginProviderType;
 };
 type SocialLoginExchangeCodeFinished = {};
+type SocialLoginOperationConfig = {
+    /** The classifier drops the attempt if no spec type arrives on any of its events — supply it here or on a step's start data as soon as known. */
+    explicitSpecType?: SocialLoginSpecType;
+};
 declare class SocialLoginOperationFull extends OperationFull {
     readonly getRedirectUrl: StepHelper<SocialLoginGetRedirectUrlStart, SocialLoginGetRedirectUrlFinished>;
     readonly exchangeCode: StepHelper<SocialLoginExchangeCodeStart, SocialLoginExchangeCodeFinished>;
-    constructor(tracker: CorbadoTracker);
+    constructor(tracker: CorbadoTracker, config?: SocialLoginOperationConfig);
 }
 
 type AppConfirmationOperationSpecType = "qr-code";
@@ -791,11 +848,14 @@ type AppConfirmationOperationCeremonyTypedError = {
 };
 type AppConfirmationOperationCeremonyTypedErrorCode = "declined" | "expired";
 type AppConfirmationOperationRetryReason = AppConfirmationOperationCeremonyTypedErrorCode | "technical-error" | "manual";
+type AppConfirmationOperationConfig = {
+    explicitSpecType?: AppConfirmationOperationSpecType;
+};
 declare class AppConfirmationOperationFull extends OperationFull {
     readonly ceremony: StepHelper<{}, {}, AppConfirmationOperationCeremonyTypedError>;
     readonly retry: StepHelper;
     readonly postResponse: StepHelper;
-    constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
+    constructor(tracker: CorbadoTracker, config?: AppConfirmationOperationConfig);
 }
 
 /**
@@ -819,6 +879,7 @@ type ProvideDataOperationSpecType = "signup" | "login" | "recovery" | "enrollmen
 type ProvideDataOperationStart = {
     /** Stable name of the data field collected by this subflow, when known. */
     fieldName?: string;
+    /** The classifier drops the attempt if no spec type arrives on any of its events — supply it here or on a step's start data as soon as known. */
     explicitSpecType?: ProvideDataOperationSpecType;
 };
 type ProvideDataOperationConfig = ProvideDataOperationStart & {
@@ -838,6 +899,7 @@ declare class ProvideDataOperationFull extends OperationFull {
 }
 
 interface TrackerOptions {
+    /** All persisted SDK state and cross-tab locks are isolated by this project id. */
     projectId: string;
     apiBaseUrl: string;
     apiEventPath?: string;
@@ -878,6 +940,8 @@ declare class CorbadoTracker {
     private sessionStorage;
     /** Dedicated localStorage engine for reliability state (config cache, outbox, continuity session, seq). */
     private persistentStorage;
+    /** Seq/continuity Web Lock name; project-scoped together with the storage keys it guards. */
+    private readonly seqLockName;
     /**
      * Reliability config for this load. A boot with a cached server config is a snapshot (immutable
      * mid-load); a boot on the built-in defaults upgrades once to the first server-returned config
@@ -966,12 +1030,15 @@ declare class CorbadoTracker {
      * same browser. Rotates after `config.sessionInactivityMs` of inactivity (server-controlled,
      * boot-snapshot like the rest of the config), resetting the seq counter.
      *
-     * This is the ONLY place an inactivity rotation happens. Rotating here is safe because the load
-     * that triggers it also re-announces its flow (an integration emits `flow_started` on page load),
-     * so the fresh session id gets a classifiable flow. Mid-page there is no such re-announcement:
-     * rotating between two tracked events would leave the started flow unfinished in the old session
-     * and the remaining events without a flow start in the new one — one gap counted as a drop-off,
-     * one completion counted as nothing. `nextSeq` therefore never rotates on inactivity.
+     * Inactivity rotation happens at boot only, here and on the per-tab path {@link resolveSessionId}
+     * takes without continuity. Boot is chosen on an assumption, not a guarantee: that a load
+     * re-announces its flow, so the fresh session id gets a classifiable flow. That holds where a
+     * flow is opened per load. Where one is opened once and carried across loads it does not, and a
+     * boot rotation splits that flow — such a project needs a window long enough to span the journey.
+     * Mid-page the assumption is not even available: nothing re-announces between two tracked events,
+     * so rotating there would leave the started flow unfinished in the old session and the remaining
+     * events without a flow start in the new one — one gap counted as a drop-off, one completion
+     * counted as nothing. `nextSeq` therefore never rotates on inactivity, on either path.
      */
     private getContinuitySessionId;
     /**
@@ -979,6 +1046,24 @@ declare class CorbadoTracker {
      * section measures from the last write that actually happened — whoever made it.
      */
     private persistContinuitySession;
+    /**
+     * Read the per-tab session record. A bare string is the format that predates dating: it carries no
+     * `lastActiveAt`, so its window can only start on the load that reads it. That load rewrites it in
+     * the dated shape, so a tab converts once and ages normally from then on, and the case drains as
+     * the rollout replaces the bundles that write it.
+     */
+    private readPerTabSession;
+    /**
+     * Persist the per-tab record and remember when, sharing the throttle bookkeeping with the
+     * continuity record — a load resolves its session on one path or the other, never both.
+     *
+     * Only a load that received a server config stamps the window; any other carries forward what the
+     * tab already knows. So a defaults boot never downgrades a tab that has already learned the
+     * project's threshold to the built-in one, and the window survives a rotation within the tab.
+     */
+    private persistPerTabSession;
+    /** The window this tab measures against: what a configured load recorded, else this load's own. */
+    private perTabInactivityMs;
     /**
      * Return the next sequence number. With session continuity the counter is persisted so ordering
      * survives reloads/redirects; the read-increment-write runs under a cross-tab Web Lock
@@ -1008,7 +1093,11 @@ declare class CorbadoTracker {
     trackSubflowStepStarted(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions, ignoreAsInteraction?: boolean): void;
     trackSubflowStepFinished(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowStepError(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions): void;
-    trackSubflowFinished(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
+    /**
+     * @remarks
+     * Records an additional error occurrence against the subflow. Carries no outcome semantics —
+     * step errors are the intended channel; not part of a normal integration.
+     */
     trackSubflowError(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     /**
      * Error situations:
@@ -1028,6 +1117,9 @@ declare class CorbadoTracker {
      *
      * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
      * @param tags - Optional key-value tags for filtering and segmentation.
+     * @param experiments - Optional per-call experiment overrides.
+     * @param contexts - Optional structured event context (e.g. technical metadata that is not an
+     *   analytical dimension). Written to the event's `contexts` field verbatim.
      *
      * @example
      * ```typescript
@@ -1038,7 +1130,7 @@ declare class CorbadoTracker {
      * });
      * ```
      */
-    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>, experiments?: Record<string, string>, contexts?: Record<string, unknown>): void;
     /**
      * Track when the user commits to a specific flow.
      *
@@ -1062,10 +1154,12 @@ declare class CorbadoTracker {
      * Use this for outcomes you care about beyond auth, such as a completed purchase,
      * a started subscription, or a newsletter signup. Provide a stable `name` for the
      * conversion and (optionally) the `touchpoint` where it happened so it can be
-     * segmented in the same way as flows. If available, include `userId` and/or
-     * `identifier` to link the conversion to a user.
+     * segmented in the same way as flows. Record identity separately with `setUser()`
+     * while the relevant flow is still active.
      *
-     * @param data - Conversion name, optional touchpoint, and optional user reference.
+     * Legacy identity fields in `data` remain supported but are deprecated.
+     *
+     * @param data - Conversion name, optional touchpoint, and deprecated user reference fields.
      * @param tags - Optional key-value tags for filtering and segmentation.
      *
      * @example
@@ -1073,7 +1167,6 @@ declare class CorbadoTracker {
      * tracker.conversion({
      *   name: "purchase",
      *   touchpoint: "checkout",
-     *   userId: "usr_123",
      * });
      * ```
      */
@@ -1083,18 +1176,18 @@ declare class CorbadoTracker {
      *
      * @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.
+     * signup, or recovery. Record identity separately with `setUser()` while the flow
+     * is still active, before calling `flowFinished()`.
+     *
+     * Legacy identity fields in `data` remain supported but are deprecated.
      *
-     * @param data - Finished flow name plus optional user reference fields.
+     * @param data - Finished flow name, optional explicit outcome, and deprecated 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",
      * });
      * ```
      */
@@ -1121,9 +1214,12 @@ declare class CorbadoTracker {
      * @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.
+     * that caused it. Record identity with `setUser()` while the intended flow is still
+     * current, before it is auto-finished.
      *
-     * @param data - Auto-finished flow, finishing flow, and optional user reference fields.
+     * Legacy identity fields in `data` remain supported but are deprecated.
+     *
+     * @param data - Auto-finished flow, finishing flow, and deprecated user reference fields.
      * @param tags - Optional key-value tags for filtering and segmentation.
      *
      * @example
@@ -1131,11 +1227,32 @@ declare class CorbadoTracker {
      * tracker.flowAutoFinished({
      *   flowName: "signup",
      *   finishedByFlowName: "login",
-     *   userId: "usr_123",
      * });
      * ```
      */
     flowAutoFinished(data: FlowAutoFinished, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    /**
+     * Record a newly known user reference for the current active flow.
+     *
+     * @remarks
+     * Emits one `flow_enriched` with `match: { flowType: "*", at: "during" }` and `expFol: true` in its data.
+     * Call only after the flow starts and before it finishes. The enrichment belongs
+     * to the current flow at emission time.
+     * Calling after `flowFinished()` cannot enrich that finished flow. If a parent or another
+     * flow is current then, the enrichment belongs to that flow instead.
+     * An empty reference does not clear identity. Cross-environment transaction IDs must be UUIDs;
+     * both environments must report the shared ID while their respective flows are active.
+     *
+     * @param user - User ID, identifier, and/or cross-environment transaction UUID.
+     *
+     * @example
+     * ```typescript
+     * tracker.flowStarted({ flowName: "login" });
+     * tracker.setUser({ userId: "usr_123", identifier: "max@example.com" });
+     * tracker.flowFinished({ flowName: "login" });
+     * ```
+     */
+    setUser(user: UserReference): void;
     /**
      * Track when you present authentication method choices to the user.
      *
@@ -1160,7 +1277,15 @@ declare class CorbadoTracker {
      */
     authMethodsDecisionStarted(data: AuthMethodDecisionStarted, tags?: Record<string, string>, experiments?: Record<string, string>, options?: Pick<StepOptions, "explicitTimestamp">): void;
     authMethodsDecisionFinished(data: AuthMethodDecisionFinished, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    /**
+     * @deprecated Use {@link CorbadoTracker.authMethodsDecisionStarted} instead (its `options`
+     * already accept free-form strings).
+     */
     authDecisionStarted(data: AuthDecisionStarted, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    /**
+     * @deprecated Use {@link CorbadoTracker.authMethodsDecisionFinished} instead (its `options`
+     * already accept free-form strings).
+     */
     authDecisionFinished(data: AuthDecisionFinished, tags?: Record<string, string>, experiments?: Record<string, string>): void;
     /**
      * Enqueue a "low" event (granular DOM/window/visualviewport/PWM signal) for the current session.
@@ -1219,17 +1344,17 @@ declare class CorbadoTracker {
      * @internal
      */
     lowEventFlushKeepalive(): void;
-    passkeyLoginFullOperation(): PasskeyLoginOperationFull;
+    passkeyLoginFullOperation(config?: PasskeyLoginOperationConfig): PasskeyLoginOperationFull;
     passkeyEnrollmentFullOperation(config?: PasskeyEnrollmentOperationConfig): PasskeyEnrollmentOperationFull;
-    passwordLoginFullOperation(autoTrackConfig?: PasswordLoginAutoTrackConfig): PasswordLoginOperationFull;
-    passwordEnrollmentFullOperation(autoTrackConfig?: PasswordEnrollmentAutoTrackConfig): PasswordEnrollmentOperationFull;
-    emailLinkOperationFull(): EmailLinkOperationFull;
+    passwordLoginFullOperation(autoTrackConfig?: PasswordLoginConfig): PasswordLoginOperationFull;
+    passwordEnrollmentFullOperation(autoTrackConfig?: PasswordEnrollmentConfig): PasswordEnrollmentOperationFull;
+    emailLinkOperationFull(config?: EmailLinkOperationConfig): EmailLinkOperationFull;
     emailOtpOperationFull(config?: EmailOTPOperationConfig): EmailOtpOperationFull;
     smsOtpOperationFull(config?: SmsOTPOperationConfig): SmsOtpOperationFull;
     provideIdentifierOperationFull(config?: OperationFullProvideIdentifierWithCUIConfig): OperationFullProvideIdentifierWithCUI;
     provideDataOperationFull(config?: ProvideDataOperationConfig): ProvideDataOperationFull;
-    socialLoginOperationFull(): SocialLoginOperationFull;
-    appConfirmationOperationFull(explicitSpecType?: AppConfirmationOperationSpecType): AppConfirmationOperationFull;
+    socialLoginOperationFull(config?: SocialLoginOperationConfig): SocialLoginOperationFull;
+    appConfirmationOperationFull(config?: AppConfirmationOperationConfig): AppConfirmationOperationFull;
     captchaOperationFull(config?: CaptchaOperationConfig): CaptchaOperationFull;
     /**
      * Flush any pending events and release all resources (timers, event listeners).
@@ -1303,6 +1428,28 @@ interface StorageEngine {
     setItem<T>(key: string, value: T): void;
     removeItem(key: string): void;
 }
+/**
+ * Suffix a storage key or cross-tab lock name with a namespace. One shared helper so keys and the
+ * Web Lock names guarding them can never disagree on the derived name.
+ */
+declare function namespacedKey(key: string, namespace: string): string;
+/**
+ * Wraps a storage engine so every key is suffixed with a fixed namespace (see {@link namespacedKey}).
+ *
+ * @remarks
+ * All trackers use their project id as the namespace: all SDK state flows through the engines
+ * created in the tracker constructor, so wrapping them scopes every persisted key (session, seq,
+ * outbox, config cache, experiments, tab id, client-env handle, debug dumps) in one place. Lock
+ * names are not storage keys and must be scoped separately by the call sites that own them.
+ */
+declare class NamespacedStorage implements StorageEngine {
+    private readonly engine;
+    private readonly namespace;
+    constructor(engine: StorageEngine, namespace: string);
+    getItem<T>(key: string): T | null;
+    setItem<T>(key: string, value: T): void;
+    removeItem(key: string): void;
+}
 declare class LocalStorage implements StorageEngine {
     private logger;
     constructor(logger: Logger);
@@ -1402,6 +1549,11 @@ interface QueueOptions {
     onConfigReceived?: (config: SdkReliabilityConfig) => void;
     /** Whether to send the opt-in config header on the first flush of this load. Defaults to true. */
     requestConfig?: boolean;
+    /**
+     * Web Lock name for the durable outbox, scoped alongside the storage engine's keys (see
+     * {@link EventStore}). Defaults to the shared {@link OUTBOX_LOCK_NAME}.
+     */
+    outboxLockName?: string;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -1464,6 +1616,8 @@ declare class RequestQueue {
      * (config.flushOnFlowTypeFinished).
      */
     private priorityFlowTypes;
+    /** Scoped Web Lock name for the durable outbox; undefined = EventStore's shared default. */
+    private outboxLockName?;
     private store?;
     /**
      * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
@@ -1696,7 +1850,7 @@ declare const DEFAULT_MAX_SERIALIZED_LENGTH: number;
  *
  * @remarks
  * Every mutation is a read-merge-write against storage, executed under a cross-tab Web Lock
- * ({@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
+ * (default {@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
  * between the read and the write (which would silently drop the other tab's entries). Where the
  * Web Locks API is unavailable the mutation runs unlocked, matching the historical best-effort
  * behavior. Mutations never reject; failures are logged.
@@ -1707,10 +1861,22 @@ declare class EventStore {
     private readonly logger;
     private readonly maxEntries;
     private readonly maxSerializedLength;
+    /**
+     * Web Lock name guarding mutations. Must be scoped together with the storage the engine writes
+     * to: a project-scoped outbox key guarded by the shared lock would serialize unrelated trackers,
+     * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
+     */
+    private readonly lockName;
     private entries;
     /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
     private reportedMalformed;
-    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number);
+    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number, 
+    /**
+     * Web Lock name guarding mutations. Must be scoped together with the storage the engine writes
+     * to: a project-scoped outbox key guarded by the shared lock would serialize unrelated trackers,
+     * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
+     */
+    lockName?: string);
     private read;
     private mutate;
     /** Evict oldest entries until the serialized outbox fits {@link maxSerializedLength}. */
@@ -1728,7 +1894,13 @@ declare class EventStore {
     size(): number;
 }
 
+/**
+ * Create a tracker and make it the default for all package-level helpers.
+ * Each call replaces the default. For multiple projects, retain the returned instances and call
+ * their methods, or construct {@link CorbadoTracker} instances directly without changing the default.
+ */
 declare function init(options: TrackerOptions): CorbadoTracker;
+/** Return the default tracker from the most recent {@link init} call. */
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
 /**
@@ -1736,6 +1908,12 @@ declare function resetSession(): string | undefined;
  * could be established. See {@link CorbadoTracker.getSessionId}.
  */
 declare function getSessionId(): string | undefined;
+/**
+ * Record a user reference for the global tracker's current active flow.
+ * Call after the flow starts and before it finishes; matching has no grace period.
+ * See {@link CorbadoTracker.setUser}.
+ */
+declare function setUser(user: UserReference): void;
 declare function setExperiment(key: string, variant: string): void;
 declare function setExperiments(assignments: Record<string, string>): void;
 declare function clearExperiment(key: string): void;
@@ -1746,4 +1924,4 @@ declare function logInfo(message: string): void;
 declare function logError(message: string): void;
 declare function destroy(): Promise<void>;
 
-export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type CaptchaOperationConfig, CaptchaOperationFull, type CaptchaOperationSpecType, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SEQ_LOCK_TIMEOUT_MS, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationConfig, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type FlushReason, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };
+export { type AppConfirmationOperationCeremonyTypedError, type AppConfirmationOperationConfig, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type CaptchaOperationConfig, CaptchaOperationFull, type CaptchaOperationSpecType, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SEQ_LOCK_TIMEOUT_MS, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, type EmailLinkOperationConfig, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationConfig, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type FlushReason, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, NamespacedStorage, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, type PasskeyLoginOperationConfig, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, type PasswordLoginConfig, type PasswordLoginExplicitSpecType, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, type SocialLoginOperationConfig, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, namespacedKey, parseReliabilityConfig, resetSession, setExperiment, setExperiments, setUser, telemetry };