@corbado/observe 0.15.0 → 0.15.1

package/dist/index.d.mts

@@ -148,7 +148,7 @@ type AuthDecisionFinished = {
     explicitDecisionValue?: string;
 };
 type StepOptions = {
-    /** Semantic control that explicitly initiated this step; omitted when unknown. */
+    /** 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;
@@ -343,32 +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
@@ -402,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;
     /**
@@ -446,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;
@@ -979,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;
@@ -1018,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;
     /**
@@ -1049,13 +1047,7 @@ declare class CorbadoTracker {
     /** @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.
@@ -1088,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.
      */
@@ -1107,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
@@ -1136,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
@@ -1623,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
@@ -1692,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
@@ -1729,7 +1711,7 @@ declare class RequestQueue {
      * 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.
@@ -1787,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;
     /**
@@ -1833,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
@@ -1888,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;
 /**
@@ -1905,6 +1880,8 @@ 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. */
@@ -2016,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 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 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 };

package/dist/index.d.ts

@@ -148,7 +148,7 @@ type AuthDecisionFinished = {
     explicitDecisionValue?: string;
 };
 type StepOptions = {
-    /** Semantic control that explicitly initiated this step; omitted when unknown. */
+    /** 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;
@@ -343,32 +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
@@ -402,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;
     /**
@@ -446,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;
@@ -979,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;
@@ -1018,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;
     /**
@@ -1049,13 +1047,7 @@ declare class CorbadoTracker {
     /** @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.
@@ -1088,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.
      */
@@ -1107,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
@@ -1136,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
@@ -1623,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
@@ -1692,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
@@ -1729,7 +1711,7 @@ declare class RequestQueue {
      * 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.
@@ -1787,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;
     /**
@@ -1833,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
@@ -1888,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;
 /**
@@ -1905,6 +1880,8 @@ 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. */
@@ -2016,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 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 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 };