@corbado/observe 0.12.0-next.94-3fd9bb7 → 0.13.0

package/dist/index.d.mts

@@ -24,8 +24,6 @@ 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 {
@@ -53,6 +51,7 @@ interface BaseEvent {
 type UserReference = {
     userId?: string;
     identifier?: string;
+    crossEnvironmentTransactionID?: string;
 };
 /**
  * Serializable error shape produced by {@link normalizeError}.
@@ -106,8 +105,7 @@ type AuthMethodDecisionStarted = {
 };
 type AuthMethodDecisionFinished = {
     decisionName: string;
-    /** Optional — when omitted, the backend completes the open decision of the same name using its declared options (classifier follow-up). */
-    options?: (AuthMethodType | (string & {}))[];
+    options: (AuthMethodType | (string & {}))[];
     explicitDecisionValue?: string;
 };
 type ProvideIdentifierStart = {};
@@ -146,6 +144,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";
@@ -477,17 +484,6 @@ declare class LowEventWindowTracker {
  * picker dismiss animations land shortly after the WebAuthn promise resolves/rejects.
  */
 declare const CEREMONY_LOW_EVENT_TAIL_MS = 1500;
-/**
- * Common constructor options shared by all operation helpers: every helper emits
- * `subflow_started` from its constructor unless opted out.
- */
-type OperationConfig = {
-    /**
-     * Emit `subflow_started` from the constructor (default `true`). Set to `false` to opt out and
-     * call {@link OperationFull.subflowStart} yourself.
-     */
-    autoStart?: boolean;
-};
 type StepHelper<TStart = {}, TFinished = {}, TTypedError = never> = {
     start: (data: TStart, options?: StepOptions) => void;
     finished: (data: TFinished, options?: StepOptions) => void;
@@ -499,11 +495,12 @@ declare abstract class OperationFull {
     private tracker;
     private operationName;
     constructor(tracker: CorbadoTracker, operationName: SubflowType);
-    /** Emit `subflow_started` for this operation. Only needed after opting out via `autoStart: false`. */
-    subflowStart(data: any, options?: StepOptions): void;
     /**
-     * @deprecated `subflow_trigger` will be removed in the next major version.
+     * Emits subflow_started. `data` supports the SubflowTrigger fields (`actor`,
+     * `explicitSpecType`, `ignoreAsInteraction`) plus free-form extras; see SubflowTrigger for when
+     * to set `ignoreAsInteraction` on programmatic starts.
      */
+    subflowStart(data: any, options?: StepOptions): void;
     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;
@@ -557,16 +554,12 @@ type PasskeyLoginPostResponseStart = {
      */
     assertionResponse?: string;
 };
-type PasskeyLoginOperationConfig = OperationConfig & {
-    /** 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, config?: PasskeyLoginOperationConfig);
+    constructor(tracker: CorbadoTracker);
     /**
      * @deprecated `subflow_trigger` is not supported for passkey-login and will be removed in the
      * next major version.
@@ -582,7 +575,7 @@ type EmailOTPOperationSendOTPStart = {
 type EmailOTPOperationPostResponseStart = {
     explicitSpecType?: EmailOTPOperationSpecType;
 };
-type EmailOTPOperationConfig = OperationConfig & {
+type EmailOTPOperationConfig = {
     explicitSpecType?: EmailOTPOperationSpecType;
 };
 declare class EmailOtpOperationFull extends OperationFull {
@@ -596,7 +589,7 @@ type SmsOTPOperationSpecType = "sms-otp-login" | "sms-otp-enrollment";
 type SmsOTPOperationPostResponseStart = {
     explicitSpecType?: SmsOTPOperationSpecType;
 };
-type SmsOTPOperationConfig = OperationConfig & {
+type SmsOTPOperationConfig = {
     explicitSpecType?: SmsOTPOperationSpecType;
 };
 declare class SmsOtpOperationFull extends OperationFull {
@@ -612,18 +605,25 @@ type EmailLinkOperationSendStart = {
 type EmailLinkOperationPostResponseStart = {
     explicitSpecType?: EmailLinkOperationSpecType;
 };
-type EmailLinkOperationConfig = OperationConfig & {
-    /** 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, config?: EmailLinkOperationConfig);
+    constructor(tracker: CorbadoTracker);
 }
 
-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;
 };
@@ -650,14 +650,15 @@ type PasskeyEnrollmentPostResponseStart = {
      */
     attestationResponse?: string;
 };
-type PasskeyEnrollmentOperationConfig = OperationConfig & {
-    /** 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. */
+type PasskeyEnrollmentOperationConfig = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
     /**
-     * Timestamp (epoch ms) for the subflow-started event. Set it when the enrollment began before the
-     * operation could be constructed.
+     * 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.
      */
-    explicitTimestamp?: number;
+    ignoreAsInteraction?: boolean;
 };
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
@@ -693,11 +694,14 @@ type PasswordLoginCUIGetOptionsFinished = {
 type PasswordLoginCUICeremonyStart = {
     explicitSpecType?: PasswordLoginCUISpecType;
 };
-type PasswordLoginExplicitSpecType = "password-known-identifier" | "password-with-identifier";
-type PasswordLoginAutoTrackConfig = OperationConfig & {
-    explicitSpecType?: PasswordLoginExplicitSpecType;
-    /** The password input field. When set, low-event input tracking is attached to it. */
-    inputHtmlField?: HTMLInputElement;
+type PasswordLoginAutoTrackConfig = {
+    explicitSpecType: "password-known-identifier";
+    /** The password input field. */
+    inputHtmlField: HTMLInputElement;
+} | {
+    explicitSpecType: "password-with-identifier";
+    /** The password input field. */
+    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.
@@ -732,10 +736,8 @@ type PasswordEnrollmentTypedError = {
 };
 type PasswordEnrollmentTypedErrorCode = "requirements_not_fulfilled";
 type PasswordEnrollmentExplicitSpecType = "password-set" | "password-reset";
-type PasswordEnrollmentAutoTrackConfig = OperationConfig & {
-    /** 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. */
+type PasswordEnrollmentAutoTrackConfig = {
     explicitSpecType?: PasswordEnrollmentExplicitSpecType;
-    /** The password input field. When set, low-event input tracking is attached to it. */
     inputHtmlField?: HTMLInputElement;
 };
 declare class PasswordEnrollmentOperationFull extends OperationFull {
@@ -765,16 +767,17 @@ type PasskeyLoginCUIGetOptionsFinished = {
     explicitSpecType?: ProvideIdentifierSpecType;
     assertionOptions: string;
 };
-type OperationFullProvideIdentifierWithCUIConfig = OperationConfig & {
-    /** When set, low event collection is enabled for the input field. */
+type OperationFullProvideIdentifierWithCUIConfig = {
     inputHtmlField?: HTMLInputElement;
     explicitSpecType?: ProvideIdentifierSpecType;
 };
-declare class OperationFullProvideIdentifierWithCUI extends OperationFull {
+declare class OperationFullProvideIdentifierWithCUI {
+    private tracker;
     private lowEventTracker?;
     readonly cui: {
         /**
-         * @deprecated `subflow_trigger` will be removed in the next major version.
+         * @deprecated `subflow_trigger` is not supported for the CUI part of provide-identifier and
+         * will be removed in the next major version.
          */
         trigger: (data: SubflowTrigger, options?: StepOptions) => void;
         getOptions: StepHelper<PasskeyLoginCUIGetOptionsStart, PasskeyLoginCUIGetOptionsFinished>;
@@ -783,34 +786,32 @@ declare class OperationFullProvideIdentifierWithCUI extends OperationFull {
     };
     readonly provideIdentifier: {
         /**
-         * @deprecated `subflow_trigger` will be removed in the next major version.
+         * @deprecated `subflow_trigger` is not supported for provide-identifier and 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 = OperationConfig & {
-    /** 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, config?: SocialLoginOperationConfig);
+    constructor(tracker: CorbadoTracker);
 }
 
 type AppConfirmationOperationSpecType = "qr-code";
@@ -822,14 +823,11 @@ type AppConfirmationOperationCeremonyTypedError = {
 };
 type AppConfirmationOperationCeremonyTypedErrorCode = "declined" | "expired";
 type AppConfirmationOperationRetryReason = AppConfirmationOperationCeremonyTypedErrorCode | "technical-error" | "manual";
-type AppConfirmationOperationConfig = OperationConfig & {
-    explicitSpecType?: AppConfirmationOperationSpecType;
-};
 declare class AppConfirmationOperationFull extends OperationFull {
     readonly ceremony: StepHelper<{}, {}, AppConfirmationOperationCeremonyTypedError>;
     readonly retry: StepHelper;
     readonly postResponse: StepHelper;
-    constructor(tracker: CorbadoTracker, config?: AppConfirmationOperationConfig);
+    constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
 }
 
 /**
@@ -838,7 +836,7 @@ declare class AppConfirmationOperationFull extends OperationFull {
  * - `invisible`: a widget that never presents UI and always solves itself.
  */
 type CaptchaOperationSpecType = "visible" | "invisible";
-type CaptchaOperationConfig = OperationConfig & {
+type CaptchaOperationConfig = {
     explicitSpecType?: CaptchaOperationSpecType;
 };
 declare class CaptchaOperationFull extends OperationFull {
@@ -853,10 +851,9 @@ 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 & OperationConfig & {
+type ProvideDataOperationConfig = ProvideDataOperationStart & {
     /** The input field whose low-level interaction signals should be collected. */
     inputHtmlField?: HTMLInputElement;
 };
@@ -873,6 +870,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;
@@ -903,8 +901,6 @@ interface TrackerOptions {
      * It will be removed in a future release.
      */
     flushInterval?: number;
-    /** Generates new Observe session ids; returned values must be UUID-compatible. Existing stored sessions are still reused. */
-    sessionIdGenerator?: () => string;
 }
 declare class CorbadoTracker {
     private options;
@@ -915,6 +911,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
@@ -997,19 +995,21 @@ declare class CorbadoTracker {
      */
     private resolveExperiments;
     private isTrackingBlocked;
-    private createSessionId;
     private resolveSessionId;
     /**
      * Resolve the session id from localStorage so it survives reloads and is shared across tabs of the
      * 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;
     /**
@@ -1017,6 +1017,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
@@ -1046,11 +1064,7 @@ 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;
-    /**
-     * @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.
-     */
+    trackSubflowFinished(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowError(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     /**
      * Error situations:
@@ -1070,6 +1084,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
@@ -1080,7 +1097,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.
      *
@@ -1178,22 +1195,6 @@ declare class CorbadoTracker {
      * ```
      */
     flowAutoFinished(data: FlowAutoFinished, tags?: Record<string, string>, experiments?: Record<string, string>): void;
-    /**
-     * Attach a cross-environment transaction id to the current flow.
-     *
-     * @remarks
-     * Use this when the flow continues in another environment (for example a native app or another
-     * device) and both sides report under the same transaction id. Emits a single `flow_enriched`
-     * event carrying the id in its user reference; call it once, as soon as the id is known.
-     *
-     * @param id - The cross-environment transaction id.
-     *
-     * @example
-     * ```typescript
-     * tracker.setCrossEnvironmentTransactionId("cet_123");
-     * ```
-     */
-    setCrossEnvironmentTransactionId(id: string): void;
     /**
      * Track when you present authentication method choices to the user.
      *
@@ -1218,15 +1219,7 @@ 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.
@@ -1285,17 +1278,17 @@ declare class CorbadoTracker {
      * @internal
      */
     lowEventFlushKeepalive(): void;
-    passkeyLoginFullOperation(config?: PasskeyLoginOperationConfig): PasskeyLoginOperationFull;
+    passkeyLoginFullOperation(): PasskeyLoginOperationFull;
     passkeyEnrollmentFullOperation(config?: PasskeyEnrollmentOperationConfig): PasskeyEnrollmentOperationFull;
     passwordLoginFullOperation(autoTrackConfig?: PasswordLoginAutoTrackConfig): PasswordLoginOperationFull;
     passwordEnrollmentFullOperation(autoTrackConfig?: PasswordEnrollmentAutoTrackConfig): PasswordEnrollmentOperationFull;
-    emailLinkOperationFull(config?: EmailLinkOperationConfig): EmailLinkOperationFull;
+    emailLinkOperationFull(): EmailLinkOperationFull;
     emailOtpOperationFull(config?: EmailOTPOperationConfig): EmailOtpOperationFull;
     smsOtpOperationFull(config?: SmsOTPOperationConfig): SmsOtpOperationFull;
     provideIdentifierOperationFull(config?: OperationFullProvideIdentifierWithCUIConfig): OperationFullProvideIdentifierWithCUI;
     provideDataOperationFull(config?: ProvideDataOperationConfig): ProvideDataOperationFull;
-    socialLoginOperationFull(config?: SocialLoginOperationConfig): SocialLoginOperationFull;
-    appConfirmationOperationFull(config?: AppConfirmationOperationConfig): AppConfirmationOperationFull;
+    socialLoginOperationFull(): SocialLoginOperationFull;
+    appConfirmationOperationFull(explicitSpecType?: AppConfirmationOperationSpecType): AppConfirmationOperationFull;
     captchaOperationFull(config?: CaptchaOperationConfig): CaptchaOperationFull;
     /**
      * Flush any pending events and release all resources (timers, event listeners).
@@ -1369,6 +1362,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);
@@ -1468,6 +1483,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`
@@ -1530,6 +1550,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
@@ -1762,7 +1784,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.
@@ -1773,10 +1795,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}. */
@@ -1794,7 +1828,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;
 /**
@@ -1802,11 +1842,6 @@ declare function resetSession(): string | undefined;
  * could be established. See {@link CorbadoTracker.getSessionId}.
  */
 declare function getSessionId(): string | undefined;
-/**
- * Attach a cross-environment transaction id to the current flow of the global tracker. See
- * {@link CorbadoTracker.setCrossEnvironmentTransactionId}.
- */
-declare function setCrossEnvironmentTransactionId(id: string): void;
 declare function setExperiment(key: string, variant: string): void;
 declare function setExperiments(assignments: Record<string, string>): void;
 declare function clearExperiment(key: string): void;
@@ -1817,4 +1852,4 @@ declare function logInfo(message: string): void;
 declare function logError(message: string): void;
 declare function destroy(): Promise<void>;
 
-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, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, type OperationConfig, 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 PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, 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, parseReliabilityConfig, resetSession, setCrossEnvironmentTransactionId, setExperiment, setExperiments, telemetry };
+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, 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, 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, namespacedKey, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };