@corbado/observe 0.14.0 → 0.15.1

package/dist/index.d.mts

@@ -148,6 +148,12 @@ type AuthDecisionFinished = {
     explicitDecisionValue?: string;
 };
 type StepOptions = {
+    /** Optional initiator override. Passkey ceremonies infer it from the operation/step spec when omitted. */
+    initiator?: LowEventInitiator;
+    /** @internal Session captured with the operation start; never sent as event metadata. */
+    captureSessionId?: string;
+    /** @internal Capture anchor supplied by operation helpers. */
+    subflowStartEventId?: string;
     /** @deprecated Use tracker.setUser() within the active flow instead. */
     userReference?: UserReference;
     explicitTimestamp?: number;
@@ -178,7 +184,22 @@ interface CustomEvent extends BaseEvent {
     data?: Record<string, unknown>;
 }
 type Event = PredefinedEvent | CustomEvent;
+type LowEventSourceKind = "input" | "input-group" | "ceremony" | "window";
+type LowEventFieldRole = "password" | "identifier" | "otp" | "data";
+type LowEventInitiator = `input-${LowEventFieldRole}` | "passkey-button" | "automatic" | "unknown";
+type LowEventInputEffect = "fill" | "modify" | "clear";
 interface LowEvent {
+    /** Per-page uint32 observation order; reserved before batching and retained on retry. */
+    captureSeq?: number;
+    captureVersion?: number;
+    pageId?: string;
+    initiator?: LowEventInitiator;
+    inputEffect?: LowEventInputEffect;
+    /** Immutable delivery identity; absent on legacy records. */
+    id?: string;
+    subflowStartEventId?: string;
+    sourceKind?: LowEventSourceKind;
+    fieldRole?: LowEventFieldRole;
     lowType: string;
     ts: number;
     durationMs?: number;
@@ -233,6 +254,10 @@ interface EventBatchMeta {
     configVersion?: string;
 }
 interface EventMeta {
+    initiator?: LowEventInitiator;
+    captureVersion?: number;
+    pageId?: string;
+    subflowStartEventId?: string;
     trackingSourcePath: string;
     /**
      * Per-tab id (uuidv7, `sessionStorage`-scoped) of the tab that CREATED this event, stamped at
@@ -242,6 +267,8 @@ interface EventMeta {
     tabId?: string;
 }
 interface EventBatch {
+    /** Request durable acceptance for replayable lows. */
+    deliveryAck?: boolean;
     sessionId: string;
     events: Event[];
     sdk: SdkInfo;
@@ -316,30 +343,24 @@ type ObserveSdkConfigSnapshot = {
     readonly aap: string;
 };
 /**
- * SDK reliability configuration returned by the events endpoint (opt-in via the
- * `X-Corbado-Observe-Config` header). Mirrors the server `observeEventCreateRes` schema.
- * All delivery-reliability features default OFF until the server returns config.
- *
- * @remarks
- * Boot-snapshot model: the config resolved at construction (from the localStorage cache) is the
- * config for the entire page load. A config received from the server during the load is only
- * cached for the NEXT load, never applied live — this keeps session identity, seq source and
- * outbox mode coherent within one load.
+ * Resolved browser SDK reliability policy. Init overrides take precedence over server policy and defaults.
+ * Session continuity and durable outbox can activate on any refresh and stay enabled for the rest of the document.
  */
 interface SdkReliabilityConfig {
     /**
-     * Content-derived version (hash) assigned by the server. Echoed in the config request header so
-     * the server can answer 204 when nothing changed, and stamped into every batch's
-     * `meta.configVersion`. Empty string for the built-in defaults (nothing cached yet).
+     * Content-derived version assigned by the server, or a non-empty identifier for injected config.
+     * Stamped into every batch's meta.configVersion. Empty when neither the server nor init overrides supply a version.
      */
     version: string;
     /** How often the SDK flushes its event queue, in milliseconds. */
     flushIntervalMs: number;
-    /** Persist queued events to a durable outbox so they survive reloads, redirects and context switches. */
+    /** Persist queued events across reloads, redirects and context switches. Can activate on any refresh; deactivation takes effect on the next initialization. */
     durableOutbox: boolean;
+    /** Persist lows in a separate bounded outbox; defaults to disabled for older configs. */
+    durableLowOutbox?: boolean;
     /** Use keepalive/sendBeacon transport for flushes triggered during page unload. */
     beaconKeepalive: boolean;
-    /** Maintain session continuity across reloads/tabs by persisting the session id in localStorage. */
+    /** Maintain session continuity across reloads/tabs. Can activate on any refresh; deactivation takes effect on the next initialization. */
     sessionContinuity: boolean;
     /**
      * Inactivity threshold for continuity sessions, in milliseconds. When more time than this has
@@ -373,8 +394,8 @@ interface SdkReliabilityConfig {
     tlf: boolean;
     /**
      * Master switch for the diagnostic telemetry stream. When true the SDK sends buffered telemetry
-     * entries piggybacked on normal event requests; when false it collects and sends nothing. Defaults
-     * to true (telemetry is on out of the box) and can be turned off server-side without a redeploy.
+     * entries piggybacked on normal event requests. When false it stops collection, but already buffered
+     * entries can still be sent. Defaults to true and can be turned off server-side without a redeploy.
      */
     telemetry: boolean;
     /**
@@ -417,6 +438,10 @@ interface SdkReliabilityConfig {
     /** Retry configuration for failed event flushes. */
     retry: SdkRetryConfig;
 }
+/** Optional init overrides; omitted fields (including nested retry fields) inherit server policy or defaults. */
+type SdkReliabilityConfigOverrides = Partial<Omit<SdkReliabilityConfig, "retry">> & {
+    retry?: Partial<SdkRetryConfig>;
+};
 
 /** Sink that escalates a diagnostic message to the telemetry stream. */
 type TelemetrySink = (level: TelemetryLevel, message: string) => void;
@@ -440,6 +465,41 @@ interface CreateLoggerOptions {
 }
 declare function createLogger(options: CreateLoggerOptions): Logger;
 
+type WindowCaptureContext = Pick<LowEvent, "subflowStartEventId" | "fieldRole" | "initiator"> & {
+    sessionId?: string;
+};
+/** One passive observer per tracker. Field/ceremony collectors register context, not DOM listeners. */
+declare class SharedWindowObserver {
+    private logger;
+    private enqueue;
+    private flushKeepalive;
+    private inputs;
+    private ceremonies;
+    private removers;
+    private lastBlur?;
+    private bracket?;
+    private unrelatedPointerAt;
+    private destroyed;
+    private viewportContext;
+    private resize;
+    private scroll;
+    constructor(logger: Logger, enqueue: (low: LowEvent, sessionId?: string) => void, flushKeepalive: () => void);
+    registerInputs(fields: readonly HTMLInputElement[], context: () => WindowCaptureContext, flush: () => void): () => void;
+    beginCeremony(context: WindowCaptureContext): {
+        settle: (tailMs: number) => void;
+        destroy: () => void;
+    };
+    private context;
+    private findInput;
+    /** Flush all registered input batches before a high-level lifecycle boundary. */
+    flushInputs(): void;
+    private emit;
+    private listen;
+    private extendViewport;
+    private observeNavigation;
+    destroy(): void;
+}
+
 /**
  * Where low events go. `flushKeepalive` is requested on `pagehide` teardown so lows batched after
  * the queue's own lifecycle flush still get out; operations wire it to the client's
@@ -447,49 +507,27 @@ declare function createLogger(options: CreateLoggerOptions): Logger;
  * (default true = historical behavior, can be disabled remotely).
  */
 interface LowEventSink {
+    reserveCaptureSeq?(): number;
     enqueueLowEvent(low: LowEvent): void;
     flushKeepalive(): void;
+    registerInputs?(fields: readonly HTMLInputElement[], flush: () => void): () => void;
+    beginCeremony?(initiator?: LowEventInitiator): {
+        settle(tailMs: number): void;
+        destroy(): void;
+    };
 }
 
-/**
- * Collects window-scoped "low" events around a WebAuthn ceremony: window focus/blur, document
- * visibility changes and visualviewport resize/scroll (batched). The listener set mirrors
- * connect-react's `installLowEventWindowListeners`; the event names match
- * {@link LowEventInputTracker}'s vocabulary.
- *
- * Unlike {@link LowEventInputTracker} (anchored to an input field, active for the owning
- * operation's lifetime), this tracker is armed only for the ceremony window: the owning operation
- * arms it on `ceremony.start()` and schedules disarming shortly after the ceremony settles, so
- * signals from the picker closing (focus return, dismiss animations) are still captured.
- *
- * Never triggers a flush — low events ride along on the queue's existing flush triggers.
- */
+/** Ceremony context lease on the shared observer. Never installs its own window listeners. */
 declare class LowEventWindowTracker {
     private logger;
     private sink;
-    private armed;
+    private lease?;
     private destroyed;
-    private disarmTimer;
-    private resizeBatcher;
-    private scrollBatcher;
-    private boundHandlers;
     constructor(logger: Logger, sink: LowEventSink);
-    /** Start listening. Idempotent; cancels a pending scheduled disarm (ceremony retry). */
-    arm(): void;
-    /**
-     * Disarm after `delayMs`. The tail keeps the listeners alive briefly after the ceremony settles:
-     * focus return and picker dismiss animations land after the WebAuthn promise resolves/rejects.
-     */
+    arm(initiator?: LowEventInitiator, conditional?: boolean): void;
     scheduleDisarm(delayMs: number): void;
-    /** Stop listening and flush the viewport batchers into the queue. Idempotent. */
     disarm(): void;
-    /** Disarm and refuse any further arming; for the owning operation's destroy(). */
     destroy(): void;
-    private cancelScheduledDisarm;
-    private pushLow;
-    private handleVisibilityChange;
-    private flushBatchers;
-    private wrapHandler;
 }
 
 /**
@@ -507,6 +545,17 @@ type StepHelper<TStart = {}, TFinished = {}, TTypedError = never> = {
 declare abstract class OperationFull {
     private tracker;
     private operationName;
+    private startReference?;
+    private captureSpecType?;
+    private captureSessionId?;
+    private readonly lowFlushers;
+    private readonly lowPrefillCapturers;
+    protected lowEventSink(sourceKind: LowEventSourceKind, fieldRole?: LowEventFieldRole): LowEventSink;
+    protected createLowCollector<T extends {
+        capturePrefill(newCapture?: boolean): void;
+    }>(create: () => T): T | undefined;
+    protected registerLowFlusher(flush: () => void): void;
+    private captureOptions;
     constructor(tracker: CorbadoTracker, operationName: SubflowType);
     /**
      * Emits an additional subflow_started; construction already emits the initial start.
@@ -514,6 +563,13 @@ declare abstract class OperationFull {
      * plus free-form extras; see SubflowTrigger for programmatic interaction suppression.
      */
     subflowStart(data: any, options?: StepOptions): void;
+    /**
+     * Capture values initialized by the application after constructing this operation, without
+     * dispatching DOM input events. Call immediately after initialization, before user editing.
+     * Each field/group emits at most one prefill per subflow start; values are never recorded.
+     */
+    capturePrefill(): void;
+    private captureInputPrefills;
     /**
      * @deprecated `subflow_trigger` will be removed in the next major version.
      */
@@ -596,13 +652,22 @@ type EmailOTPOperationPostResponseStart = {
     explicitSpecType?: EmailOTPOperationSpecType;
 };
 type EmailOTPOperationConfig = {
+    /** Email domain only, no full address. */
+    emailDomain?: string;
+    /** One real input, or an ordered group representing one OTP. */
+    inputHtmlField?: HTMLInputElement;
+    inputHtmlFields?: HTMLInputElement[];
     explicitSpecType?: EmailOTPOperationSpecType;
 };
 declare class EmailOtpOperationFull extends OperationFull {
+    private lowEventTracker?;
     readonly send: StepHelper<EmailOTPOperationSendOTPStart>;
     readonly postResponse: StepHelper<EmailOTPOperationPostResponseStart>;
     readonly resend: StepHelper;
     constructor(tracker: CorbadoTracker, config?: EmailOTPOperationConfig);
+    /** Rebind the ordered OTP group without starting a new subflow. An empty list detaches it. */
+    setInputFields(fields: readonly HTMLInputElement[]): void;
+    destroy(): void;
 }
 
 type SmsOTPOperationSpecType = "sms-otp-login" | "sms-otp-enrollment";
@@ -610,12 +675,19 @@ type SmsOTPOperationPostResponseStart = {
     explicitSpecType?: SmsOTPOperationSpecType;
 };
 type SmsOTPOperationConfig = {
+    /** One real input, or an ordered group representing one OTP. */
+    inputHtmlField?: HTMLInputElement;
+    inputHtmlFields?: HTMLInputElement[];
     explicitSpecType?: SmsOTPOperationSpecType;
 };
 declare class SmsOtpOperationFull extends OperationFull {
+    private lowEventTracker?;
     readonly postResponse: StepHelper<SmsOTPOperationPostResponseStart>;
     readonly resend: StepHelper;
     constructor(tracker: CorbadoTracker, config?: SmsOTPOperationConfig);
+    /** Rebind the ordered OTP group without starting a new subflow. An empty list detaches it. */
+    setInputFields(fields: readonly HTMLInputElement[]): void;
+    destroy(): void;
 }
 
 type EmailLinkOperationSpecType = "email-link-login" | "email-link-enrollment";
@@ -725,8 +797,7 @@ type PasswordLoginConfig = {
     /** The password input field. When set, low-event input tracking is attached to it. */
     inputHtmlField?: HTMLInputElement;
     /**
-     * The identifier (e.g. email) input field. Accepted but not tracked yet — low-event
-     * tracking for a second field lands together with per-field attribution.
+     * The identifier (e.g. email) input field. Tracked separately from the password field.
      */
     identifierInputHtmlField?: HTMLInputElement;
 };
@@ -744,6 +815,7 @@ declare class PasswordLoginOperationFull extends OperationFull {
         postResponse: StepHelper;
     };
     private lowEventTracker?;
+    private identifierLowEventTracker?;
     constructor(tracker: CorbadoTracker, config?: PasswordLoginConfig);
     /**
      * @deprecated `subflow_trigger` is not supported for password-login and will be removed in the
@@ -903,6 +975,10 @@ interface TrackerOptions {
     projectId: string;
     apiBaseUrl: string;
     apiEventPath?: string;
+    /** Per-field overrides over server config and defaults. A complete policy disables remote fetching. */
+    sdkConfig?: SdkReliabilityConfigOverrides;
+    /** Config endpoint override for integrations that proxy Observe under a different path. */
+    apiConfigPath?: string;
     storage?: "cookie" | "local";
     cookieDomain?: string;
     debug?: boolean;
@@ -942,12 +1018,10 @@ declare class CorbadoTracker {
     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
-     * (see {@link handleConfig}).
-     */
+    /** Current resolved policy. Continuity and persistence stay enabled once activated within a document. */
     private config;
+    private readonly configManager?;
+    private readonly configOverrides;
     private deviceInfoManager;
     private deviceCollector;
     /**
@@ -969,14 +1043,11 @@ declare class CorbadoTracker {
     private telemetryReady;
     private readonly reportedTelemetryKeys;
     private pendingSelfTelemetry;
+    private windowObserver?;
+    /** @internal Shared passive page observation and per-operation context registration. */
+    getWindowObserver(): SharedWindowObserver;
     constructor(options: TrackerOptions);
-    /**
-     * Cache fresh server config as last-known so the next page load boots with it. When this load
-     * booted on the built-in defaults (no cached config), the config is additionally applied live:
-     * every field is read at use time, and a mid-load `sessionContinuity` flip is safe because
-     * `nextSeq` adopts the in-memory session id into the empty continuity store instead of minting
-     * (no session split). A load that booted on a cached config keeps its snapshot untouched.
-     */
+    /** Apply init overrides on every refresh; continuity and persistence only activate within a document. */
     private handleConfig;
     /**
      * Returns the logger used by this tracker.
@@ -1009,7 +1080,7 @@ declare class CorbadoTracker {
     /** Returns a copy of the currently active experiment assignments. */
     getExperiments(): Record<string, string>;
     /**
-     * Returns the public SDK configuration for this page load.
+     * Returns the currently active public SDK configuration, including live updates.
      *
      * @returns A frozen snapshot, created fresh on every call.
      */
@@ -1028,7 +1099,7 @@ declare class CorbadoTracker {
     /**
      * 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.
+     * evaluated at boot), resetting the seq counter.
      *
      * 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
@@ -1057,12 +1128,11 @@ declare class CorbadoTracker {
      * 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.
+     * An explicit timeout override or server config stamps the window. Otherwise carry forward what
+     * the tab already knows, so a defaults boot does not replace a previously configured threshold.
      */
     private persistPerTabSession;
-    /** The window this tab measures against: what a configured load recorded, else this load's own. */
+    /** Explicit init timeout wins; otherwise retain the window a prior configured load recorded. */
     private perTabInactivityMs;
     /**
      * Return the next sequence number. With session continuity the counter is persisted so ordering
@@ -1088,7 +1158,7 @@ declare class CorbadoTracker {
      * sessionStorage-backed and stable for the whole page lifetime.
      */
     private resolveEventTabId;
-    trackSubflowStarted(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
+    trackSubflowStarted(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions, eventId?: string): 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;
     trackSubflowStepFinished(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions): void;
@@ -1106,7 +1176,12 @@ declare class CorbadoTracker {
      *
      * @internal
      */
-    track(name: AuthEventName, data: Record<string, any>, userReference?: UserReference, tags?: Record<string, string>, contexts?: Record<string, any>, explicitTimestamp?: number, experiments?: Record<string, string>): Promise<void>;
+    track(name: AuthEventName, data: Record<string, any>, userReference?: UserReference, tags?: Record<string, string>, contexts?: Record<string, any>, explicitTimestamp?: number, experiments?: Record<string, string>, capture?: {
+        id?: string;
+        subflowStartEventId?: string;
+        sessionId?: string;
+        initiator?: StepOptions["initiator"];
+    }): Promise<void>;
     /**
      * Track when an authentication flow (or flow selection screen) becomes visible.
      *
@@ -1296,7 +1371,7 @@ declare class CorbadoTracker {
      *
      * @internal
      */
-    enqueueLowEvent(low: LowEvent): void;
+    enqueueLowEvent(low: LowEvent, capturedSessionId?: string): void;
     /**
      * Record a diagnostic telemetry entry (a `level` + free-form `message`) for the current session.
      *
@@ -1407,6 +1482,7 @@ declare const SDK_NAME = "@corbado/observe";
 declare const SDK_VERSION: string;
 
 interface TransportMakeRequestResponse {
+    deliveryAccepted?: boolean;
     statusCode?: number;
     headers?: Record<string, string | null>;
     /** Parsed SDK reliability config, present only when the server returns it (HTTP 200). */
@@ -1538,16 +1614,11 @@ interface QueueOptions {
      */
     flushInterval?: number;
     debug?: boolean;
-    /**
-     * Reliability config for this page load; defaults to all-features-OFF. Boot-snapshot model: with
-     * a cached config the queue never changes its behavior mid-load — a fresh config returned by the
-     * server is only handed to {@link QueueOptions.onConfigReceived} for caching and applies on the
-     * next load. Only a defaults boot (no cached config) applies the first server config live.
-     */
+    /** Initial delivery policy. The tracker applies later updates with updateConfig(). */
     config?: SdkReliabilityConfig;
     /** Called when the server returns a fresh config, so the client can cache it for the next load. */
     onConfigReceived?: (config: SdkReliabilityConfig) => void;
-    /** Whether to send the opt-in config header on the first flush of this load. Defaults to true. */
+    /** Legacy standalone queue handshake. Trackers set false and use the independent config manager. */
     requestConfig?: boolean;
     /**
      * Web Lock name for the durable outbox, scoped alongside the storage engine's keys (see
@@ -1567,7 +1638,7 @@ interface QueueOptions {
  * Pending events are held as {@link OutboxEntry} records. When `config.durableOutbox` is enabled they are
  * additionally persisted to a localStorage-backed {@link EventStore} and recovered on the next load.
  * Delivery removes an entry only on a 2xx response; retryable failures back off (honoring `Retry-After`)
- * up to `config.retry.maxAttempts`. Low events are best-effort and never persisted.
+ * up to `config.retry.maxAttempts`. Low events have a separately bounded outbox when durableLowOutbox is enabled.
  *
  * 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.
@@ -1583,14 +1654,16 @@ declare class RequestQueue {
     private readonly storage?;
     private pending;
     private lowsQueue;
+    private lowPending;
+    private lowStore?;
     /**
-     * Diagnostic telemetry buffered for the current session. Best-effort and never persisted (like
-     * lows). Attached to the next outgoing batch for this session; a telemetry entry alone never arms
+     * Diagnostic telemetry buffered for the current session. Best-effort and never persisted. Attached to the next outgoing batch for this session; a telemetry entry alone never arms
      * the flush timer (it piggybacks), unless `config.flushOnTelemetry` escalates to an immediate flush.
      */
     private telemetryQueue;
     private timer;
     private isFlushing;
+    private flushingDone?;
     private destroyed;
     /**
      * True when something was enqueued (or recovered) since the last sync flush. visibilitychange,
@@ -1605,11 +1678,7 @@ declare class RequestQueue {
     private readonly debug;
     private readonly requestConfig;
     private readonly onConfigReceived?;
-    /**
-     * Reliability config for this load. A boot with a cached server config is a snapshot that never
-     * changes mid-load; a boot on the built-in defaults upgrades once to the first server-returned
-     * config (see {@link handleConfigResponse}).
-     */
+    /** Current delivery policy, including live updates. */
     private config;
     /**
      * Flow types whose completion triggers an immediate flush at enqueue time
@@ -1632,17 +1701,17 @@ declare class RequestQueue {
      * Error situations:
      *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue event"
      */
-    enqueue(event: Event): void;
+    enqueue(event: Event, capturedSessionId?: string): void;
     /**
      * Error situations:
      *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue low event"
      */
-    enqueueLow(low: LowEvent): void;
+    enqueueLow(low: LowEvent, capturedSessionId?: string): void;
     /**
      * Buffer a diagnostic telemetry entry for delivery with the next event batch.
      *
      * @remarks
-     * The master switch `config.telemetry` gates collection: when off, nothing is buffered or sent.
+     * The switch `config.telemetry` gates collection. Entries buffered while on remain eligible for delivery.
      * By default a telemetry entry does NOT arm the flush timer — it piggybacks the next flush caused
      * by events or a lifecycle signal (it is marked dirty so the unload flush picks it up). When
      * `config.flushOnTelemetry` is on it escalates to an immediate flush.
@@ -1685,6 +1754,10 @@ declare class RequestQueue {
     private attachBatchMeta;
     private getDuePending;
     private takeLows;
+    private validPendingLow;
+    private removeLowEntries;
+    private handleLowSendResult;
+    private deferLowEntries;
     private takeTelemetry;
     private shouldRequestConfig;
     /**
@@ -1696,13 +1769,8 @@ declare class RequestQueue {
      * reliability features.
      */
     private handleConfigResponse;
-    /**
-     * 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 flow type set, durable outbox store) needs rebuilding.
-     */
-    private applyConfigLive;
-    /** Returns true when the batch was acknowledged with a 2xx (safe to keep draining). */
+    /** Applies live delivery policy, retaining pending events, retry deadlines, and activated persistence. */
+    updateConfig(config: SdkReliabilityConfig): void;
     private handleSendResult;
     private isRetryable;
     /**
@@ -1742,7 +1810,7 @@ declare class RequestQueue {
     destroy(): void;
 }
 
-/** localStorage key under which the last-known server config is cached. */
+/** Last-known server config shared by batch-based and independently fetching SDK versions. */
 declare const CONFIG_STORAGE_KEY = "cbo_sdk_config";
 /**
  * Opt-in request header that asks the events endpoint to return the SDK reliability config. Its value
@@ -1797,11 +1865,9 @@ declare const CONFIG_BOUNDS: {
 /** Built-in continuity-session inactivity threshold (30 minutes); matches the historical default. */
 declare const DEFAULT_SESSION_INACTIVITY_MS: number;
 /**
- * Default config: every delivery-reliability feature is OFF. The SDK behaves like a plain async
- * fetch-keepalive flusher until the server returns config, which is cached as last-known for the
- * next load AND applied live to the current load (a defaults boot has no prior config to stay
- * coherent with; loads booting on a cached config keep their snapshot — boot-snapshot model). The
- * empty version means "nothing cached"; the config request header sends "1" in that case.
+ * Defaults used until a valid injected, cached, or fetched config is available.
+ * Delivery-reliability features start OFF. Last-known remote config never expires.
+ * Init overrides win per field; a complete override bypasses remote fetching and caching.
  */
 declare const DEFAULT_RELIABILITY_CONFIG: SdkReliabilityConfig;
 /**
@@ -1814,13 +1880,15 @@ declare const DEFAULT_RELIABILITY_CONFIG: SdkReliabilityConfig;
  * server value cannot harm the client.
  */
 declare function parseReliabilityConfig(raw: unknown): SdkReliabilityConfig | null;
+/** Resolve init overrides over validated server policy, then defaults, including individual retry fields. */
+declare function resolveReliabilityConfig(serverConfig: SdkReliabilityConfig | undefined, overrides?: SdkReliabilityConfigOverrides): SdkReliabilityConfig;
 /** Read the cached config from storage, or `null` if absent/invalid. */
 declare function loadCachedConfig(storage: StorageEngine): SdkReliabilityConfig | null;
 /** Persist the config as last-known so the next page load starts with these features enabled. */
 declare function cacheConfig(storage: StorageEngine, config: SdkReliabilityConfig): void;
 
 /** A persisted, not-yet-acknowledged event awaiting delivery. */
-interface OutboxEntry {
+interface OutboxEntry<T = Event> {
     /** Event idempotency id; primary key of the entry. */
     id: string;
     /** Session id snapshot taken at enqueue time (so session rotation never relabels old entries). */
@@ -1830,7 +1898,7 @@ interface OutboxEntry {
     /** Number of completed send attempts so far. */
     attempts: number;
     /** The event payload. */
-    event: Event;
+    event: T;
 }
 /** localStorage key under which the durable outbox is persisted. */
 declare const OUTBOX_STORAGE_KEY = "cbo_outbox";
@@ -1856,7 +1924,7 @@ declare const DEFAULT_MAX_SERIALIZED_LENGTH: number;
  * behavior. Mutations never reject; failures are logged.
  * The store is size-capped; overflow evicts the oldest entries and logs the count.
  */
-declare class EventStore {
+declare class EventStore<T = Event> {
     private readonly storage;
     private readonly logger;
     private readonly maxEntries;
@@ -1867,6 +1935,7 @@ declare class EventStore {
      * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
      */
     private readonly lockName;
+    private readonly storageKey;
     private entries;
     /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
     private reportedMalformed;
@@ -1876,21 +1945,21 @@ declare class EventStore {
      * 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);
+    lockName?: string, storageKey?: string);
     private read;
     private mutate;
     /** Evict oldest entries until the serialized outbox fits {@link maxSerializedLength}. */
     private enforceSizeBudget;
     /** Append an entry. No-op if an entry with the same id already exists. */
-    add(entry: OutboxEntry): Promise<void>;
+    add(entry: OutboxEntry<T>): Promise<void>;
     /** Re-read from storage and return all entries (memory mirror refreshed). */
-    all(): OutboxEntry[];
+    all(): OutboxEntry<T>[];
     /** Entries whose `flushAfter` has elapsed, in insertion order. */
-    getDue(now: number): OutboxEntry[];
+    getDue(now: number): OutboxEntry<T>[];
     /** Remove entries by id (acknowledged or permanently dropped). */
     remove(ids: string[]): Promise<void>;
     /** Replace existing entries (matched by id) with updated copies, e.g. after bumping backoff. */
-    update(updated: OutboxEntry[]): Promise<void>;
+    update(updated: OutboxEntry<T>[]): Promise<void>;
     size(): number;
 }
 
@@ -1924,4 +1993,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, NamespacedStorage, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, type PasskeyLoginOperationConfig, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, type PasswordLoginConfig, type PasswordLoginExplicitSpecType, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, type SocialLoginOperationConfig, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, namespacedKey, parseReliabilityConfig, resetSession, setExperiment, setExperiments, setUser, telemetry };
+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 LowEventFieldRole, type LowEventInitiator, type LowEventInputEffect, type LowEventSourceKind, type MultiFlowReset, type MultiFlowStarted, NamespacedStorage, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, type PasskeyLoginOperationConfig, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, type PasswordLoginConfig, type PasswordLoginExplicitSpecType, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkReliabilityConfigOverrides, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, type SocialLoginOperationConfig, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, namespacedKey, parseReliabilityConfig, resetSession, resolveReliabilityConfig, setExperiment, setExperiments, setUser, telemetry };