@corbado/observe 0.9.1 → 0.10.0-next.84-492957c

package/dist/index.d.mts

@@ -3,8 +3,8 @@ interface SdkInfo {
     version: string;
 }
 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-known-identifier" | "password-login-with-identifier" | "password-enrollment" | "email-otp-login" | "email-otp-enrollment" | "email-link-login" | "email-link-enrollment" | "social-google" | "social-apple" | "social-facebook" | "social-other" | "reset-flow";
-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 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" | "captcha";
 type FlowType = "login" | "signup" | "recovery" | "enrollment" | (string & {});
 type SocialLoginProviderType = "google" | "apple" | "facebook" | "github" | "microsoft" | "other";
 declare enum AuthEventName {
@@ -175,9 +175,31 @@ interface TelemetryEntry {
     /** Capture time, unix ms. */
     ts: number;
 }
+/**
+ * Why a delivery attempt happened. Each value maps 1:1 to one flush trigger, so server-side
+ * analyses can tell which triggers actually carry the traffic and whether the trigger switches and
+ * opt-in flush features of the reliability config earn their keep.
+ *
+ * - `timer`: the flush interval elapsed (the ordinary cadence).
+ * - `backoff`: a retry whose backoff delay elapsed — a resend, not new work.
+ * - `recovery`: events recovered from the durable outbox at boot (previous load never delivered them).
+ * - `flow-finished`: a configured priority flow type completed (`flushOnFlowTypeFinished`).
+ * - `telemetry`: a telemetry entry escalated to an immediate flush (`flushOnTelemetry`).
+ * - `visibility-change`: the document became hidden (`tvc`).
+ * - `pagehide`: the page is going away (`tph`).
+ * - `low-event-teardown`: a low-event tracker's unload teardown handed over its batched lows (`tlf`).
+ * - `destroy`: the tracker was destroyed (`td`).
+ * - `manual`: the host app called `flushKeepalive()` itself.
+ */
+type FlushReason = "timer" | "backoff" | "recovery" | "flow-finished" | "telemetry" | "visibility-change" | "pagehide" | "low-event-teardown" | "destroy" | "manual";
 interface EventBatchMeta {
     sent: number;
     transport: "fetch" | "beacon";
+    /**
+     * What triggered the flush this batch was sent in. All batches of one flush (a backlog larger
+     * than `batchSize` is drained in several requests) carry the same reason.
+     */
+    flushReason?: FlushReason;
     /** Number of prior failed delivery attempts for this batch; omitted on the first attempt. */
     retryCount?: number;
     /**
@@ -219,6 +241,11 @@ interface DeviceInfoDataWeb {
     javaScriptHighEntropy?: JavaScriptHighEntropy;
     privateMode?: boolean;
     webdriver?: boolean;
+    /**
+     * `navigator.maxTouchPoints` — maximum simultaneous touch contact points. Reported raw so the
+     * backend can separate iPadOS (non-zero, but sends a macOS user agent) from real macOS devices (0).
+     */
+    maxTouchPoints?: number;
 }
 type DeviceInfoCollectionError = {
     field: keyof DeviceInfoDataWeb;
@@ -281,7 +308,14 @@ interface SdkReliabilityConfig {
      * relevant when `sessionContinuity` is enabled.
      */
     sessionInactivityMs: number;
-    /** Maximum time to wait for the cross-tab sequence Web Lock before allocating without it. */
+    /**
+     * Maximum time to wait for the cross-tab sequence Web Lock before allocating without it.
+     *
+     * `0` disables the lock: the counter is then allocated straight away, without ever requesting a
+     * lock. That gives up cross-tab atomicity — two tabs sharing a continuity session can allocate the
+     * same seq, which is what the unlocked fallback already does on every timeout — in exchange for
+     * removing a lock round-trip per tracked event.
+     */
     seqLockTimeoutMs: number;
     /**
      * Flush-trigger switch: flush pending events when the document becomes hidden
@@ -311,13 +345,31 @@ interface SdkReliabilityConfig {
      */
     flushOnTelemetry: boolean;
     /**
-     * Event names that trigger an immediate flush when enqueued (e.g. `flow_finished`,
-     * `conversion`), so high-value events go out via a normal fetch while the page is still alive
-     * instead of relying on unload delivery. Empty by default (no priority events). The whole
-     * pending queue is sent, and the immediate flush coexists with the interval timer without
-     * double-sending (the in-flight drain absorbs it).
+     * Flow types (e.g. `login`, `enrollment`) whose completion triggers an immediate flush when
+     * enqueued, so the highest-value events go out via a normal fetch while the page is still alive
+     * instead of relying on unload delivery. Both completion events count — `flow_finished` and
+     * `flow_auto_finished` — matched on their `flowName`; no other event name ever flushes early.
+     * Empty by default (no priority flows). The whole pending queue is sent, and the immediate flush
+     * coexists with the interval timer without double-sending (the in-flight drain absorbs it).
+     */
+    flushOnFlowTypeFinished: FlowType[];
+    /**
+     * Per-field timeout for device info collection, in milliseconds. A field whose browser API does
+     * not answer within this budget is recorded as a `TimeoutError` in `collectionErrors` and left
+     * undefined; the remaining fields are unaffected. Defaults to 1000ms.
+     *
+     * Read at collection time, so a config that arrives mid-load applies from the next device info
+     * refresh onward. The very first collection of a load booting on the built-in defaults (nothing
+     * cached) always runs on the default.
+     */
+    deviceInfoCollectorTimeoutMs: number;
+    /**
+     * When true (and `telemetry` is enabled), every device info collection emits an `info` telemetry
+     * entry with the total duration and the per-field durations in milliseconds. Defaults to false:
+     * this is a diagnostic stream to switch on while investigating slow collection, not something to
+     * run permanently.
      */
-    flushOnEventNames: string[];
+    deviceInfoTiming: boolean;
     /** Retry configuration for failed event flushes. */
     retry: SdkRetryConfig;
 }
@@ -449,10 +501,20 @@ type PasskeyLoginCeremonyStart = {
 type PasskeyLoginCeremonyFinished = {
     assertionResponse: string;
 };
+type PasskeyLoginPostResponseStart = {
+    /**
+     * Fallback carrier for the WebAuthn assertion, same JSON shape the ceremony step reports. Set it
+     * only when the ceremony itself could not be observed — e.g. an extension holds
+     * `navigator.credentials` in a form the integration declines to patch — and the submitted
+     * credential is the only remaining copy. Leave it unset whenever a ceremony step carried the
+     * assertion, so consumers never see two sources for one login.
+     */
+    assertionResponse?: string;
+};
 declare class PasskeyLoginOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyLoginGetOptionsStart, PasskeyLoginGetOptionsFinished>;
     readonly ceremony: StepHelper<PasskeyLoginCeremonyStart, PasskeyLoginCeremonyFinished>;
-    readonly postResponse: StepHelper;
+    readonly postResponse: StepHelper<PasskeyLoginPostResponseStart>;
     private lowEventTracker;
     constructor(tracker: CorbadoTracker);
     /**
@@ -470,21 +532,27 @@ type EmailOTPOperationSendOTPStart = {
 type EmailOTPOperationPostResponseStart = {
     explicitSpecType?: EmailOTPOperationSpecType;
 };
+type EmailOTPOperationConfig = {
+    explicitSpecType?: EmailOTPOperationSpecType;
+};
 declare class EmailOtpOperationFull extends OperationFull {
     readonly send: StepHelper<EmailOTPOperationSendOTPStart>;
     readonly postResponse: StepHelper<EmailOTPOperationPostResponseStart>;
     readonly resend: StepHelper;
-    constructor(tracker: CorbadoTracker);
+    constructor(tracker: CorbadoTracker, config?: EmailOTPOperationConfig);
 }
 
 type SmsOTPOperationSpecType = "sms-otp-login" | "sms-otp-enrollment";
 type SmsOTPOperationPostResponseStart = {
     explicitSpecType?: SmsOTPOperationSpecType;
 };
+type SmsOTPOperationConfig = {
+    explicitSpecType?: SmsOTPOperationSpecType;
+};
 declare class SmsOtpOperationFull extends OperationFull {
     readonly postResponse: StepHelper<SmsOTPOperationPostResponseStart>;
     readonly resend: StepHelper;
-    constructor(tracker: CorbadoTracker);
+    constructor(tracker: CorbadoTracker, config?: SmsOTPOperationConfig);
 }
 
 type EmailLinkOperationSpecType = "email-link-login" | "email-link-enrollment";
@@ -517,12 +585,26 @@ type PasskeyEnrollmentCeremonyStart = {
 type PasskeyEnrollmentCeremonyFinished = {
     attestationResponse: string;
 };
+type PasskeyEnrollmentPostResponseStart = {
+    /**
+     * Fallback carrier for the WebAuthn attestation, mirroring the passkey-login contract. Set it only
+     * when the ceremony itself could not be observed — e.g. an extension holds `navigator.credentials`
+     * in a form the integration declines to patch — and the submitted credential is the only remaining
+     * copy. Leave it unset whenever a ceremony step carried the attestation, so consumers never see two
+     * sources for one enrollment. A credential recovered from the submission may carry more members
+     * than the ceremony reports; consumers must tolerate unknown keys.
+     */
+    attestationResponse?: string;
+};
+type PasskeyEnrollmentOperationConfig = {
+    explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
+};
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
     readonly ceremony: StepHelper<PasskeyEnrollmentCeremonyStart, PasskeyEnrollmentCeremonyFinished>;
-    readonly postResponse: StepHelper;
+    readonly postResponse: StepHelper<PasskeyEnrollmentPostResponseStart>;
     private lowEventTracker;
-    constructor(tracker: CorbadoTracker);
+    constructor(tracker: CorbadoTracker, config?: PasskeyEnrollmentOperationConfig);
     destroy(): void;
 }
 
@@ -609,7 +691,7 @@ type PasskeyLoginCUITypedError = {
     code: PasskeyLoginCUITypedErrorCode;
 };
 type PasskeyLoginCUITypedErrorCode = "cancel_detected";
-type ProvideIdentifierSpecType = "email";
+type ProvideIdentifierSpecType = "email" | "phone";
 type ProvideIdentifierPostResponseStart = {
     explicitSpecType?: ProvideIdentifierSpecType;
 };
@@ -624,6 +706,10 @@ type PasskeyLoginCUIGetOptionsFinished = {
     explicitSpecType?: ProvideIdentifierSpecType;
     assertionOptions: string;
 };
+type OperationFullProvideIdentifierWithCUIConfig = {
+    inputHtmlField?: HTMLInputElement;
+    explicitSpecType?: ProvideIdentifierSpecType;
+};
 declare class OperationFullProvideIdentifierWithCUI {
     private tracker;
     private lowEventTracker?;
@@ -635,7 +721,7 @@ declare class OperationFullProvideIdentifierWithCUI {
         trigger: (data: SubflowTrigger, options?: StepOptions) => void;
         getOptions: StepHelper<PasskeyLoginCUIGetOptionsStart, PasskeyLoginCUIGetOptionsFinished>;
         ceremony: StepHelper<CUICeremonyStart, PasskeyLoginCeremonyFinished, PasskeyLoginCUITypedError>;
-        postResponse: StepHelper;
+        postResponse: StepHelper<PasskeyLoginPostResponseStart>;
     };
     readonly provideIdentifier: {
         /**
@@ -646,7 +732,7 @@ declare class OperationFullProvideIdentifierWithCUI {
         clientValidation: StepHelper;
         postResponse: StepHelper<ProvideIdentifierPostResponseStart>;
     };
-    constructor(tracker: CorbadoTracker, inputHtmlField?: HTMLInputElement);
+    constructor(tracker: CorbadoTracker, config?: OperationFullProvideIdentifierWithCUIConfig);
     private createStep;
     destroy(): void;
 }
@@ -683,6 +769,29 @@ declare class AppConfirmationOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
 }
 
+/**
+ * Which captcha widget the integration observed. The tier is decided server-side per request, so it
+ * is a property of the rendered challenge, not of the integration:
+ * - `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 {
+    /**
+     * Challenge shown (`start`) until a captcha token exists (`finished`) or the challenge failed.
+     *
+     * The ceremony carries no actor: a widget that self-solves and one awaiting a click are the same
+     * observation from the page, and nothing in a vendor's frame reports which of the two happened.
+     */
+    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. */
@@ -715,7 +824,12 @@ interface TrackerOptions {
     logger?: Logger;
     /** Minimum time between attaching cached device info to events. */
     deviceInfoDebounceTime?: number;
-    /** Per-field collection timeout. Defaults to 200ms. */
+    /**
+     * @deprecated The device info collection timeout is server-controlled via the SDK reliability
+     * config (`deviceInfoCollectorTimeoutMs`). This option only applies as long as no server config
+     * has been received (i.e. before the first config response is cached); once a server config is
+     * cached it wins. It will be removed in a future release.
+     */
     deviceInfoCollectorTimeout?: number;
     defaultTags?: Record<string, string>;
     /**
@@ -731,6 +845,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;
@@ -749,6 +865,12 @@ declare class CorbadoTracker {
     private config;
     private deviceInfoManager;
     private seq;
+    /**
+     * When the continuity record's `lastActiveAt` was last persisted. Throttles that write inside the
+     * seq critical section (see {@link SESSION_ACTIVITY_WRITE_INTERVAL_MS}). 0 = not written yet on
+     * this load, so the first allocation always persists.
+     */
+    private lastActivityWriteAt;
     /** Persistent experiment assignments (experiment key → variant), attached to every produced event. */
     private experiments;
     /** Self-instrumentation state: re-entrancy guard, readiness, per-load dedupe, and pre-queue buffer. */
@@ -805,24 +927,42 @@ declare class CorbadoTracker {
      */
     private resolveExperiments;
     private isTrackingBlocked;
+    private createSessionId;
     private getSessionId;
     /**
      * 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.
      */
     private getContinuitySessionId;
+    /**
+     * Persist the continuity record and remember when, so the throttled refresh in the seq critical
+     * section measures from the last write that actually happened — whoever made it.
+     */
+    private persistContinuitySession;
     /**
      * 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
      * ({@link SEQ_LOCK_NAME}) so two tabs sharing the session cannot allocate the same seq (where Web
      * Locks are unavailable or exceed the configured timeout it degrades to the historical best-effort merge).
-     * Lock grants are FIFO, so seq order matches `track()` call order within a tab. Every tracked event also bumps the
-     * continuity session's `lastActiveAt`, so the inactivity window measures real user inactivity
-     * instead of time-since-page-load (a long-lived active tab must not rotate the session on the next
-     * reload). An empty store while this load already has a session id means persistence is failing
-     * (or was cleared); the in-memory id is reused then — never re-minted — so a broken store degrades
-     * to one session per page load instead of one session per event.
+     * Lock grants are FIFO, so seq order matches `track()` call order within a tab. Tracking also keeps the
+     * continuity session's `lastActiveAt` fresh (throttled, see {@link SESSION_ACTIVITY_WRITE_INTERVAL_MS}),
+     * so the window the NEXT boot evaluates measures real user
+     * inactivity instead of time-since-page-load (a long-lived active tab must not rotate the session
+     * on the next reload). It never rotates the session itself: the inactivity window is evaluated at
+     * boot only ({@link getContinuitySessionId} documents why). Consequence: while a page is never
+     * reloaded — foreground idle, bfcache restore, long-lived SPA tab — a session can outlive
+     * `sessionInactivityMs`. That inflates flow durations but keeps flow counts correct, which is the
+     * better half of the trade. An empty store while this load already has a session id means
+     * persistence is failing (or was cleared); the in-memory id is reused then — never re-minted — so
+     * a broken store degrades to one session per page load instead of one session per event.
      */
     private nextSeq;
     private resolveTrackingSourcePath;
@@ -1028,9 +1168,12 @@ declare class CorbadoTracker {
      * Synchronously flush any pending events and low events via beacon. Use during page-unload
      * style teardown where async flushing is unreliable.
      *
+     * @param reason What triggered the flush; recorded as `meta.flushReason` on the batch. Defaults
+     * to a direct call by the host app.
+     *
      * @internal
      */
-    flushKeepalive(): void;
+    flushKeepalive(reason?: FlushReason): void;
     /**
      * Keepalive flush requested by a low-event tracker's `pagehide` teardown. Gated by the
      * server-controlled trigger switch `tlf` (boot-snapshot, default true = historical behavior):
@@ -1040,16 +1183,17 @@ declare class CorbadoTracker {
      */
     lowEventFlushKeepalive(): void;
     passkeyLoginFullOperation(): PasskeyLoginOperationFull;
-    passkeyEnrollmentFullOperation(): PasskeyEnrollmentOperationFull;
+    passkeyEnrollmentFullOperation(config?: PasskeyEnrollmentOperationConfig): PasskeyEnrollmentOperationFull;
     passwordLoginFullOperation(autoTrackConfig?: PasswordLoginAutoTrackConfig): PasswordLoginOperationFull;
     passwordEnrollmentFullOperation(autoTrackConfig?: PasswordEnrollmentAutoTrackConfig): PasswordEnrollmentOperationFull;
     emailLinkOperationFull(): EmailLinkOperationFull;
-    emailOtpOperationFull(): EmailOtpOperationFull;
-    smsOtpOperationFull(): SmsOtpOperationFull;
-    provideIdentifierOperationFull(inputHtmlField?: HTMLInputElement): OperationFullProvideIdentifierWithCUI;
+    emailOtpOperationFull(config?: EmailOTPOperationConfig): EmailOtpOperationFull;
+    smsOtpOperationFull(config?: SmsOTPOperationConfig): SmsOtpOperationFull;
+    provideIdentifierOperationFull(config?: OperationFullProvideIdentifierWithCUIConfig): OperationFullProvideIdentifierWithCUI;
     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).
      *
@@ -1206,6 +1350,9 @@ interface QueueOptions {
  *
  * Flushing is timer-driven only (the flush interval); `batchSize` caps the events per request, and a
  * flush drains all due work in sequential capped batches, stopping at the first failed send.
+ *
+ * Every flush carries a {@link FlushReason} that names its trigger; it is stamped onto the batch as
+ * `meta.flushReason` so the server can see which triggers actually deliver.
  */
 declare class RequestQueue {
     private readonly logger;
@@ -1243,8 +1390,11 @@ declare class RequestQueue {
      * config (see {@link handleConfigResponse}).
      */
     private config;
-    /** Event names that trigger an immediate flush at enqueue time (config.flushOnEventNames). */
-    private priorityNames;
+    /**
+     * Flow types whose completion triggers an immediate flush at enqueue time
+     * (config.flushOnFlowTypeFinished).
+     */
+    private priorityFlowTypes;
     private store?;
     /**
      * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
@@ -1279,20 +1429,35 @@ declare class RequestQueue {
      */
     enqueueTelemetry(entry: TelemetryEntry): void;
     private scheduleAfterEnqueue;
+    /**
+     * Whether this event completes one of the configured priority flow types. Only the two flow
+     * completion events qualify — `flow_finished` and `flow_auto_finished`, both carrying the
+     * finished flow in `data.flowName`. Custom events never match, even when named like one of them.
+     */
+    private isPriorityEvent;
+    /**
+     * Arm the flush timer. The `reason` travels with the timer into the flush it triggers; an
+     * already-armed timer keeps the reason it was armed with (the flush it fires is that flush, and
+     * it takes whatever accumulated in the meantime with it).
+     */
     private scheduleFlush;
     private clearTimer;
     /**
+     * @param reason What triggered this flush; stamped onto every batch it sends as
+     * `meta.flushReason`. Defaults to the ordinary interval cadence.
+     *
      * Error situations:
      *  - Queue is empty: return without calling transport.send
      *  - A flush is already in progress: return without calling transport.send again
      *  - transport.send rejects or throws, or any other error in the try block: log "Unexpected error in queue flush"
      */
-    flush(): Promise<void>;
+    flush(reason?: FlushReason): Promise<void>;
     /**
-     * Stamps delivery metadata onto the batch: the config version this load runs under (omitted on
-     * built-in defaults) and the number of prior failed delivery attempts (the max across its entries,
-     * only when at least one entry is a retry). `entry.attempts` is incremented on each failed flush,
-     * so it equals the retry count at send time. The transport later merges in `sent`/`transport`.
+     * Stamps delivery metadata onto the batch: the trigger that caused this flush, the config version
+     * this load runs under (omitted on built-in defaults) and the number of prior failed delivery
+     * attempts (the max across its entries, only when at least one entry is a retry). `entry.attempts`
+     * is incremented on each failed flush, so it equals the retry count at send time. The transport
+     * later merges in `sent`/`transport`.
      */
     private attachBatchMeta;
     private getDuePending;
@@ -1311,7 +1476,7 @@ declare class RequestQueue {
     /**
      * Switch this load from the built-in defaults to the first server config (defaults boot only).
      * Most fields are read at use time, so replacing the reference is enough; only the derived state
-     * (priority-name set, durable outbox store) needs rebuilding.
+     * (priority flow type set, durable outbox store) needs rebuilding.
      */
     private applyConfigLive;
     /** Returns true when the batch was acknowledged with a 2xx (safe to keep draining). */
@@ -1339,9 +1504,13 @@ declare class RequestQueue {
      * with the host app). With `config.durableOutbox` enabled, entries are NOT removed (they are
      * resent on the next load and deduped server-side); otherwise the sent chunk is removed
      * best-effort and a remainder keeps the next lifecycle signal flush-worthy.
-     * Deduplicated: a call with nothing newly enqueued since the last sync flush is a no-op.
+     * Deduplicated: a call with nothing newly enqueued since the last sync flush is a no-op — so of
+     * several unload signals in one navigation only the first one that finds something to send is
+     * recorded as the flush reason.
+     *
+     * @param reason What triggered the unload flush; defaults to a direct call by the host app.
      */
-    flushKeepalive(): void;
+    flushKeepalive(reason?: FlushReason): void;
     private flushSync;
     /**
      * Error situations:
@@ -1361,6 +1530,12 @@ declare const CONFIG_REQUEST_HEADER = "X-Corbado-Observe-Config";
 /** Built-in flush interval used until the server provides one. Matches the historical default. */
 declare const DEFAULT_FLUSH_INTERVAL_MS = 500;
 declare const DEFAULT_SEQ_LOCK_TIMEOUT_MS = 50;
+/**
+ * Built-in per-field device info collection timeout. Also the timeout of the very first collection
+ * of a load that booted without a cached config, since collection starts before the first server
+ * response can arrive — generous enough that a slow-but-working browser API still answers.
+ */
+declare const DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS = 1000;
 /**
  * Clamping bounds for server-provided config values. They protect the client from a dangerous
  * server-side config mistake (e.g. a 0ms flush interval would busy-loop); the server clamps with
@@ -1384,10 +1559,14 @@ declare const CONFIG_BOUNDS: {
         readonly max: 86400000;
     };
     readonly seqLockTimeoutMs: {
-        readonly min: 1;
+        readonly min: 0;
         readonly max: 250;
     };
-    readonly flushOnEventNames: {
+    readonly deviceInfoCollectorTimeoutMs: {
+        readonly min: 10;
+        readonly max: 10000;
+    };
+    readonly flushOnFlowTypeFinished: {
         readonly maxEntries: 20;
         readonly maxNameLength: 100;
     };
@@ -1493,4 +1672,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_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 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 JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, OperationFull, OperationFullProvideIdentifierWithCUI, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentOperationFull, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, 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 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, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };