@corbado/observe 0.10.0 → 0.11.0-next.90-2fe1389

package/dist/index.d.mts

@@ -4,7 +4,7 @@ interface SdkInfo {
 }
 type EventType = "predefined" | "custom" | "error" | "identify";
 type AuthMethodType = "identifier-email" | "passkey-login-known-identifier" | "passkey-login-no-identifier" | "passkey-login-cui" | "passkey-login-immediate" | "passkey-enrollment" | "password-login" | "password-login-known-identifier" | "password-login-with-identifier" | "password-enrollment" | "email-otp" | "email-otp-login" | "email-otp-enrollment" | "email-link" | "email-link-login" | "email-link-enrollment" | "sms-otp" | "sms-otp-login" | "sms-otp-enrollment" | "social-google" | "social-apple" | "social-facebook" | "social-other" | "reset-flow" | "provide-data";
-type SubflowType = "passkey-enrollment" | "passkey-login" | "email-otp" | "email-link" | "social-login" | "sms-otp" | "provide-identifier" | "provide-data" | "password-login" | "password-enrollment" | "totp" | "app-confirmation";
+type SubflowType = "passkey-enrollment" | "passkey-login" | "email-otp" | "email-link" | "social-login" | "sms-otp" | "provide-identifier" | "provide-data" | "password-login" | "password-enrollment" | "totp" | "app-confirmation" | "captcha";
 type FlowType = "login" | "signup" | "recovery" | "enrollment" | (string & {});
 type SocialLoginProviderType = "google" | "apple" | "facebook" | "github" | "microsoft" | "other";
 declare enum AuthEventName {
@@ -59,7 +59,8 @@ type UserReference = {
  */
 type NormalizedError = {
     name?: string;
-    message: string;
+    code?: string;
+    message?: string;
 };
 type FlowStarted = {
     flowName: FlowType;
@@ -211,6 +212,12 @@ interface EventBatchMeta {
 }
 interface EventMeta {
     trackingSourcePath: string;
+    /**
+     * Per-tab id (uuidv7, `sessionStorage`-scoped) of the tab that CREATED this event, stamped at
+     * `track()` time. Late-flushed events keep the tab they originated in regardless of which page
+     * delivers them; the backend uses this to split interleaved multi-tab streams per session.
+     */
+    tabId?: string;
 }
 interface EventBatch {
     sessionId: string;
@@ -481,6 +488,13 @@ declare abstract class OperationFull {
 }
 
 type PasskeyOperationLoginExplicitSpecType = "passkey-cui" | "passkey-known-identifier" | "passkey-no-identifier"
+/**
+ * The `-auto` variants are the same two ceremonies started by the integration rather than by a
+ * user gesture — `navigator.credentials.get()` called without user activation, so the passkey
+ * prompt appears on its own. Unlike `passkey-immediate` they still run after the auth-method
+ * decision is rendered and attribute to the same decision option as their manual counterpart.
+ */
+ | "passkey-known-identifier-auto" | "passkey-no-identifier-auto"
 /**
  * WebAuthn immediate mediation (`navigator.credentials.get({ uiMode: "immediate" })`, Chrome 149+):
  * button-triggered, discoverable credentials only (empty allowList). Shows the account picker when
@@ -598,6 +612,11 @@ type PasskeyEnrollmentPostResponseStart = {
 };
 type PasskeyEnrollmentOperationConfig = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
+    /**
+     * Timestamp (epoch ms) for the subflow-started event. Set it when the enrollment began before the
+     * operation could be constructed.
+     */
+    explicitTimestamp?: number;
 };
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
@@ -769,6 +788,23 @@ declare class AppConfirmationOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
 }
 
+/**
+ * Which captcha widget the integration observed.
+ * - `visible`: a widget presenting UI to the user. Can require interaction.
+ * - `invisible`: a widget that never presents UI and always solves itself.
+ */
+type CaptchaOperationSpecType = "visible" | "invisible";
+type CaptchaOperationConfig = {
+    explicitSpecType?: CaptchaOperationSpecType;
+};
+declare class CaptchaOperationFull extends OperationFull {
+    /** Step representing the captcha challenge ceremony. */
+    readonly ceremony: StepHelper;
+    /** Submission of the captcha token and the server's verdict on it. */
+    readonly postResponse: StepHelper;
+    constructor(tracker: CorbadoTracker, config?: CaptchaOperationConfig);
+}
+
 type ProvideDataOperationSpecType = "signup" | "login" | "recovery" | "enrollment";
 type ProvideDataOperationStart = {
     /** Stable name of the data field collected by this subflow, when known. */
@@ -822,6 +858,8 @@ 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;
@@ -839,6 +877,12 @@ declare class CorbadoTracker {
      */
     private config;
     private deviceInfoManager;
+    private deviceCollector;
+    /**
+     * Cached per-tab id stamped onto every event's meta (see {@link EventMeta.tabId}). Resolved
+     * lazily from the collector's sessionStorage-backed id; stable for the whole page lifetime.
+     */
+    private eventTabId?;
     private seq;
     /**
      * When the continuity record's `lastActiveAt` was last persisted. Throttles that write inside the
@@ -902,7 +946,8 @@ declare class CorbadoTracker {
      */
     private resolveExperiments;
     private isTrackingBlocked;
-    private getSessionId;
+    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,
@@ -940,6 +985,11 @@ declare class CorbadoTracker {
      */
     private nextSeq;
     private resolveTrackingSourcePath;
+    /**
+     * Per-tab id for event meta, cached after the first successful resolution: the id is
+     * sessionStorage-backed and stable for the whole page lifetime.
+     */
+    private resolveEventTabId;
     trackSubflowStarted(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowTrigger(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowStepStarted(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions, ignoreAsInteraction?: boolean): void;
@@ -1167,6 +1217,7 @@ declare class CorbadoTracker {
     provideDataOperationFull(config?: ProvideDataOperationConfig): ProvideDataOperationFull;
     socialLoginOperationFull(): SocialLoginOperationFull;
     appConfirmationOperationFull(explicitSpecType?: AppConfirmationOperationSpecType): AppConfirmationOperationFull;
+    captchaOperationFull(config?: CaptchaOperationConfig): CaptchaOperationFull;
     /**
      * Flush any pending events and release all resources (timers, event listeners).
      *
@@ -1178,6 +1229,38 @@ declare class CorbadoTracker {
      * resources are released either way.
      */
     destroy(): Promise<void>;
+    /**
+     * Return the Observe session id this tracker is currently reporting under.
+     *
+     * @remarks
+     * Use this to route a server-side event into the same session the browser reports to: read the id,
+     * pass it to your own backend, and let the backend use it as the `sessionID` of its ingest call.
+     * Reading it here is the supported path — the storage layout behind it is an implementation detail
+     * that has already changed once (per-tab `sessionStorage` to the cross-tab continuity record).
+     *
+     * The value is **not stable for the lifetime of the page**. It changes on
+     * {@link CorbadoTracker.resetSession}, when this tab adopts a continuity session another tab
+     * rotated to, and when a failed bootstrap recovers. Read it at the moment you need it; never cache
+     * it across a request.
+     *
+     * `undefined` means no session id could be established at all — an environment without Web Crypto,
+     * where tracking is not working either. Skip the server-side event instead of sending an empty id:
+     * the ingest API requires a UUID and would reject the batch.
+     *
+     * @returns The current session id, or `undefined` if none could be established.
+     *
+     * @example
+     * ```typescript
+     * const sessionId = tracker.getSessionId();
+     * if (sessionId) {
+     *   await fetch("/api/checkout", {
+     *     method: "POST",
+     *     body: JSON.stringify({ ...payload, observeSessionId: sessionId }),
+     *   });
+     * }
+     * ```
+     */
+    getSessionId(): string | undefined;
     /** @internal */
     resetSession(): string;
 }
@@ -1635,6 +1718,11 @@ declare class EventStore {
 declare function init(options: TrackerOptions): CorbadoTracker;
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
+/**
+ * Session id of the global tracker, or `undefined` when no tracker was initialized or no session
+ * could be established. See {@link CorbadoTracker.getSessionId}.
+ */
+declare function getSessionId(): string | undefined;
 declare function setExperiment(key: string, variant: string): void;
 declare function setExperiments(assignments: Record<string, string>): void;
 declare function clearExperiment(key: string): void;
@@ -1645,4 +1733,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 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, 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, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, 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, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, 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 };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ interface SdkInfo {
 }
 type EventType = "predefined" | "custom" | "error" | "identify";
 type AuthMethodType = "identifier-email" | "passkey-login-known-identifier" | "passkey-login-no-identifier" | "passkey-login-cui" | "passkey-login-immediate" | "passkey-enrollment" | "password-login" | "password-login-known-identifier" | "password-login-with-identifier" | "password-enrollment" | "email-otp" | "email-otp-login" | "email-otp-enrollment" | "email-link" | "email-link-login" | "email-link-enrollment" | "sms-otp" | "sms-otp-login" | "sms-otp-enrollment" | "social-google" | "social-apple" | "social-facebook" | "social-other" | "reset-flow" | "provide-data";
-type SubflowType = "passkey-enrollment" | "passkey-login" | "email-otp" | "email-link" | "social-login" | "sms-otp" | "provide-identifier" | "provide-data" | "password-login" | "password-enrollment" | "totp" | "app-confirmation";
+type SubflowType = "passkey-enrollment" | "passkey-login" | "email-otp" | "email-link" | "social-login" | "sms-otp" | "provide-identifier" | "provide-data" | "password-login" | "password-enrollment" | "totp" | "app-confirmation" | "captcha";
 type FlowType = "login" | "signup" | "recovery" | "enrollment" | (string & {});
 type SocialLoginProviderType = "google" | "apple" | "facebook" | "github" | "microsoft" | "other";
 declare enum AuthEventName {
@@ -59,7 +59,8 @@ type UserReference = {
  */
 type NormalizedError = {
     name?: string;
-    message: string;
+    code?: string;
+    message?: string;
 };
 type FlowStarted = {
     flowName: FlowType;
@@ -211,6 +212,12 @@ interface EventBatchMeta {
 }
 interface EventMeta {
     trackingSourcePath: string;
+    /**
+     * Per-tab id (uuidv7, `sessionStorage`-scoped) of the tab that CREATED this event, stamped at
+     * `track()` time. Late-flushed events keep the tab they originated in regardless of which page
+     * delivers them; the backend uses this to split interleaved multi-tab streams per session.
+     */
+    tabId?: string;
 }
 interface EventBatch {
     sessionId: string;
@@ -481,6 +488,13 @@ declare abstract class OperationFull {
 }
 
 type PasskeyOperationLoginExplicitSpecType = "passkey-cui" | "passkey-known-identifier" | "passkey-no-identifier"
+/**
+ * The `-auto` variants are the same two ceremonies started by the integration rather than by a
+ * user gesture — `navigator.credentials.get()` called without user activation, so the passkey
+ * prompt appears on its own. Unlike `passkey-immediate` they still run after the auth-method
+ * decision is rendered and attribute to the same decision option as their manual counterpart.
+ */
+ | "passkey-known-identifier-auto" | "passkey-no-identifier-auto"
 /**
  * WebAuthn immediate mediation (`navigator.credentials.get({ uiMode: "immediate" })`, Chrome 149+):
  * button-triggered, discoverable credentials only (empty allowList). Shows the account picker when
@@ -598,6 +612,11 @@ type PasskeyEnrollmentPostResponseStart = {
 };
 type PasskeyEnrollmentOperationConfig = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
+    /**
+     * Timestamp (epoch ms) for the subflow-started event. Set it when the enrollment began before the
+     * operation could be constructed.
+     */
+    explicitTimestamp?: number;
 };
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
@@ -769,6 +788,23 @@ declare class AppConfirmationOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
 }
 
+/**
+ * Which captcha widget the integration observed.
+ * - `visible`: a widget presenting UI to the user. Can require interaction.
+ * - `invisible`: a widget that never presents UI and always solves itself.
+ */
+type CaptchaOperationSpecType = "visible" | "invisible";
+type CaptchaOperationConfig = {
+    explicitSpecType?: CaptchaOperationSpecType;
+};
+declare class CaptchaOperationFull extends OperationFull {
+    /** Step representing the captcha challenge ceremony. */
+    readonly ceremony: StepHelper;
+    /** Submission of the captcha token and the server's verdict on it. */
+    readonly postResponse: StepHelper;
+    constructor(tracker: CorbadoTracker, config?: CaptchaOperationConfig);
+}
+
 type ProvideDataOperationSpecType = "signup" | "login" | "recovery" | "enrollment";
 type ProvideDataOperationStart = {
     /** Stable name of the data field collected by this subflow, when known. */
@@ -822,6 +858,8 @@ 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;
@@ -839,6 +877,12 @@ declare class CorbadoTracker {
      */
     private config;
     private deviceInfoManager;
+    private deviceCollector;
+    /**
+     * Cached per-tab id stamped onto every event's meta (see {@link EventMeta.tabId}). Resolved
+     * lazily from the collector's sessionStorage-backed id; stable for the whole page lifetime.
+     */
+    private eventTabId?;
     private seq;
     /**
      * When the continuity record's `lastActiveAt` was last persisted. Throttles that write inside the
@@ -902,7 +946,8 @@ declare class CorbadoTracker {
      */
     private resolveExperiments;
     private isTrackingBlocked;
-    private getSessionId;
+    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,
@@ -940,6 +985,11 @@ declare class CorbadoTracker {
      */
     private nextSeq;
     private resolveTrackingSourcePath;
+    /**
+     * Per-tab id for event meta, cached after the first successful resolution: the id is
+     * sessionStorage-backed and stable for the whole page lifetime.
+     */
+    private resolveEventTabId;
     trackSubflowStarted(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowTrigger(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowStepStarted(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions, ignoreAsInteraction?: boolean): void;
@@ -1167,6 +1217,7 @@ declare class CorbadoTracker {
     provideDataOperationFull(config?: ProvideDataOperationConfig): ProvideDataOperationFull;
     socialLoginOperationFull(): SocialLoginOperationFull;
     appConfirmationOperationFull(explicitSpecType?: AppConfirmationOperationSpecType): AppConfirmationOperationFull;
+    captchaOperationFull(config?: CaptchaOperationConfig): CaptchaOperationFull;
     /**
      * Flush any pending events and release all resources (timers, event listeners).
      *
@@ -1178,6 +1229,38 @@ declare class CorbadoTracker {
      * resources are released either way.
      */
     destroy(): Promise<void>;
+    /**
+     * Return the Observe session id this tracker is currently reporting under.
+     *
+     * @remarks
+     * Use this to route a server-side event into the same session the browser reports to: read the id,
+     * pass it to your own backend, and let the backend use it as the `sessionID` of its ingest call.
+     * Reading it here is the supported path — the storage layout behind it is an implementation detail
+     * that has already changed once (per-tab `sessionStorage` to the cross-tab continuity record).
+     *
+     * The value is **not stable for the lifetime of the page**. It changes on
+     * {@link CorbadoTracker.resetSession}, when this tab adopts a continuity session another tab
+     * rotated to, and when a failed bootstrap recovers. Read it at the moment you need it; never cache
+     * it across a request.
+     *
+     * `undefined` means no session id could be established at all — an environment without Web Crypto,
+     * where tracking is not working either. Skip the server-side event instead of sending an empty id:
+     * the ingest API requires a UUID and would reject the batch.
+     *
+     * @returns The current session id, or `undefined` if none could be established.
+     *
+     * @example
+     * ```typescript
+     * const sessionId = tracker.getSessionId();
+     * if (sessionId) {
+     *   await fetch("/api/checkout", {
+     *     method: "POST",
+     *     body: JSON.stringify({ ...payload, observeSessionId: sessionId }),
+     *   });
+     * }
+     * ```
+     */
+    getSessionId(): string | undefined;
     /** @internal */
     resetSession(): string;
 }
@@ -1635,6 +1718,11 @@ declare class EventStore {
 declare function init(options: TrackerOptions): CorbadoTracker;
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
+/**
+ * Session id of the global tracker, or `undefined` when no tracker was initialized or no session
+ * could be established. See {@link CorbadoTracker.getSessionId}.
+ */
+declare function getSessionId(): string | undefined;
 declare function setExperiment(key: string, variant: string): void;
 declare function setExperiments(assignments: Record<string, string>): void;
 declare function clearExperiment(key: string): void;
@@ -1645,4 +1733,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 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, 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, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, 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, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, 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 };