@corbado/observe 0.2.0 → 0.3.0-next.34-a2ae3ef

package/dist/index.d.mts

@@ -23,9 +23,15 @@ declare enum AuthEventName {
     SubflowTrigger = "subflow_trigger",
     SubflowError = "subflow_error",
     SubflowStarted = "subflow_started",
-    SubflowFinished = "subflow_finished"
+    SubflowFinished = "subflow_finished",
+    Conversion = "conversion"
 }
 interface BaseEvent {
+    /**
+     * Client-generated idempotency id (uuidv7). Stamped once at capture and persisted with the event so
+     * resends (retry / durable outbox / unload beacon) reuse the same value and the server can dedupe.
+     */
+    id: string;
     timestamp: number;
     seq: number;
     type: EventType;
@@ -33,6 +39,7 @@ interface BaseEvent {
     contexts?: Record<string, unknown>;
     tags?: Record<string, string>;
     deviceInfo?: DeviceInfo;
+    meta?: EventMeta;
 }
 type UserReference = {
     userId?: string;
@@ -59,6 +66,16 @@ type MultiFlowStarted = {
 type FlowDecided = {
     flowName: FlowType;
 };
+/**
+ * A business/marketing conversion that is not part of an authentication flow,
+ * e.g. a completed purchase, a started subscription, or a newsletter signup.
+ */
+type Conversion = {
+    /** Name of the conversion, e.g. `"purchase"` or `"add-to-cart"`. */
+    name: string;
+    /** Where the conversion happened, e.g. `"checkout"` or `"product-page"`. */
+    touchpoint?: string;
+} & UserReference;
 type FlowFinished = {
     flowName: FlowType;
     explicitOutcome?: "skipped" | "invisible";
@@ -136,6 +153,18 @@ interface LowEvent {
 }
 interface EventBatchMeta {
     sent: number;
+    transport: "fetch" | "beacon";
+    /** Number of prior failed delivery attempts for this batch; omitted on the first attempt. */
+    retryCount?: number;
+    /**
+     * Version of the SDK reliability config this batch was captured under; omitted when running on
+     * built-in defaults. Lets server-side analyses segment by the config actually in effect (config
+     * changes propagate with page-load lag, so calendar-date cohorts are mixed).
+     */
+    configVersion?: string;
+}
+interface EventMeta {
+    trackingSourcePath: string;
 }
 interface EventBatch {
     sessionId: string;
@@ -149,7 +178,13 @@ interface DeviceInfo {
     type: DeviceType;
     clientEnvHandle: string;
     clientEnvHandleMeta: ClientEnvHandleMeta;
+    /**
+     * Per-tab id (uuidv7) stored in `sessionStorage`. Distinguishes two tabs that share one
+     * `localStorage`-backed session when session continuity is enabled.
+     */
+    tabId?: string;
     data: DeviceInfoDataWeb;
+    collectionErrors?: DeviceInfoCollectionError[];
 }
 interface DeviceInfoDataWeb {
     bluetoothAvailable?: boolean;
@@ -160,6 +195,11 @@ interface DeviceInfoDataWeb {
     privateMode?: boolean;
     webdriver?: boolean;
 }
+type DeviceInfoCollectionError = {
+    field: keyof DeviceInfoDataWeb;
+    source: string;
+    error: NormalizedError;
+};
 type ClientCapabilities = Record<string, string>;
 type JavaScriptHighEntropy = {
     platform?: string;
@@ -171,6 +211,70 @@ type ClientEnvHandleMeta = {
     source: ClientEnvHandleMetaSource;
 };
 type ClientEnvHandleMetaSource = "localstorage" | "cookie" | "native";
+/**
+ * Client-side retry configuration (exponential backoff) for failed event flushes.
+ * Mirrors the server `observeEventCreateResRetry` schema.
+ */
+interface SdkRetryConfig {
+    /** Maximum number of send attempts, including the first one. `1` disables retries. */
+    maxAttempts: number;
+    /** Base backoff delay between attempts, in milliseconds. */
+    baseDelayMs: number;
+    /** Maximum backoff delay between attempts, in milliseconds. */
+    maxDelayMs: number;
+}
+/**
+ * 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.
+ */
+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).
+     */
+    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. */
+    durableOutbox: 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. */
+    sessionContinuity: boolean;
+    /**
+     * Inactivity threshold for continuity sessions, in milliseconds. When more time than this has
+     * passed since the last tracked activity, the session id is rotated on the next load. Only
+     * relevant when `sessionContinuity` is enabled.
+     */
+    sessionInactivityMs: number;
+    /**
+     * Flush-trigger switch: flush pending events when the document becomes hidden
+     * (`visibilitychange`). Defaults to true — a missing value can never disable delivery.
+     */
+    tvc: boolean;
+    /** Flush-trigger switch: flush pending events on `pagehide` (navigation/close). Defaults to true. */
+    tph: boolean;
+    /** Flush-trigger switch: flush pending events when the integrator calls `destroy()`. Defaults to true. */
+    td: 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).
+     */
+    flushOnEventNames: string[];
+    /** Retry configuration for failed event flushes. */
+    retry: SdkRetryConfig;
+}
 
 type StepHelper<TStart = {}, TFinished = {}, TTypedError = never> = {
     start: (data: TStart, options?: StepOptions) => void;
@@ -373,18 +477,16 @@ interface TrackerOptions {
     deviceInfoDebounceTime?: number;
     defaultTags?: Record<string, string>;
     applicationId?: string;
+    /**
+     * @deprecated The flush interval is server-controlled via the SDK reliability config
+     * (`flushIntervalMs`). 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.
+     */
     flushInterval?: number;
+    /** Generates new Observe session ids; returned values must be UUID-compatible. Existing stored sessions are still reused. */
+    sessionIdGenerator?: () => string;
 }
-/**
- * @remarks
- * **Constructor**
- * - If `apiBaseUrl` is non-empty and missing `http://` or `https://`: logs via `logger.critical` (does not throw).
- * - If `apiBaseUrl` is non-empty and ends with `/`: logs via `logger.critical` (does not throw).
- * - Session bootstrap (`getSessionId`): on failure logs `Failed to get session id` and continues with an empty session id (does not throw).
- *
- * **Typed tracking helpers** (`flowStarted`, `flowDecided`, and the other public methods that call `track`)
- * - Error handling for queued events is defined on {@link CorbadoTracker.track}.
- */
 declare class CorbadoTracker {
     private options;
     private logger;
@@ -392,19 +494,48 @@ declare class CorbadoTracker {
     private sessionId;
     private storage;
     private sessionStorage;
+    /** Dedicated localStorage engine for reliability state (config cache, outbox, continuity session, seq). */
+    private persistentStorage;
+    /** Boot snapshot of the reliability config; immutable for the lifetime of this page load. */
+    private readonly config;
     private deviceInfoCollector;
     private deviceInfoDebounceTime;
     private deviceInfoTransmittedLastTime;
     private seq;
     constructor(options: TrackerOptions);
+    /**
+     * Cache fresh server config as last-known. Boot-snapshot model: the config is NOT applied to this
+     * load — `this.config` stays the construction-time snapshot — it takes effect on the next page
+     * load via {@link loadCachedConfig}.
+     */
+    private handleConfig;
     /**
      * Returns the logger used by this tracker.
      */
     getLogger(): Logger;
     private applicationTag;
     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.
+     */
+    private getContinuitySessionId;
+    /**
+     * 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 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).
+     */
+    private nextSeq;
     private updateDeviceDebounced;
+    private resolveTrackingSourcePath;
     trackSubflowStarted(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowTrigger(subflowType: SubflowType, data: Record<string, any>, options?: StepOptions): void;
     trackSubflowStepStarted(subflowType: SubflowType, stepName: string, data: Record<string, any>, options?: StepOptions, ignoreAsInteraction?: boolean): void;
@@ -457,6 +588,29 @@ declare class CorbadoTracker {
      * ```
      */
     flowDecided(data: FlowDecided, tags?: Record<string, string>): void;
+    /**
+     * Track a business/marketing conversion that is not part of an authentication flow.
+     *
+     * @remarks
+     * Use this for outcomes you care about beyond auth, such as a completed purchase,
+     * a started subscription, or a newsletter signup. Provide a stable `name` for the
+     * conversion and (optionally) the `touchpoint` where it happened so it can be
+     * segmented in the same way as flows. If available, include `userId` and/or
+     * `identifier` to link the conversion to a user.
+     *
+     * @param data - Conversion name, optional touchpoint, and optional user reference.
+     * @param tags - Optional key-value tags for filtering and segmentation.
+     *
+     * @example
+     * ```typescript
+     * tracker.conversion({
+     *   name: "purchase",
+     *   touchpoint: "checkout",
+     *   userId: "usr_123",
+     * });
+     * ```
+     */
+    conversion(data: Conversion, tags?: Record<string, string>): void;
     /**
      * Track when a flow successfully completes.
      *
@@ -571,10 +725,14 @@ declare class CorbadoTracker {
      * After calling destroy, the tracker must not be used. Operation objects
      * returned by factory methods (e.g. `passwordLoginFullOperation`) that hold
      * DOM references must be destroyed separately by the caller.
+     * The final flush is gated by the server-controlled trigger switch `td` (default true);
+     * resources are released either way.
      */
     destroy(): Promise<void>;
     /** @internal */
     resetSession(): string;
+    private resetContinuitySession;
+    private resetStorageSession;
 }
 
 declare const SDK_NAME = "@corbado/observe";
@@ -583,9 +741,11 @@ declare const SDK_VERSION: string;
 interface TransportMakeRequestResponse {
     statusCode?: number;
     headers?: Record<string, string | null>;
+    /** Parsed SDK reliability config, present only when the server returns it (HTTP 200). */
+    config?: SdkReliabilityConfig;
 }
 interface Transport {
-    send(batch: EventBatch): Promise<TransportMakeRequestResponse>;
+    send(batch: EventBatch, extraHeaders?: Record<string, string>): Promise<TransportMakeRequestResponse>;
     sendBeacon?(batch: EventBatch): boolean;
     flush(timeout?: number): Promise<boolean>;
 }
@@ -595,58 +755,6 @@ interface TransportOptions {
     headers?: Record<string, string>;
 }
 
-interface QueueOptions {
-    batchSize?: number;
-    flushInterval?: number;
-}
-/**
- * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide` trigger a synchronous beacon flush (`flushSync`). Any thrown error in that path is logged as "Unexpected error in queue flushSync".
- */
-declare class RequestQueue {
-    private readonly logger;
-    private transport;
-    private sessionId;
-    private readonly sdk;
-    private options;
-    private queue;
-    private lowsQueue;
-    private timer;
-    private isFlushing;
-    private onVisibilityChange;
-    private onPageHide;
-    constructor(logger: Logger, transport: Transport, sessionId: string, sdk: SdkInfo, options?: QueueOptions);
-    setSessionId(sessionId: string): void;
-    /**
-     * Error situations:
-     *  - Any error while enqueueing or scheduling flush (including a synchronous throw from `flush`): log "Failed to enqueue event"
-     */
-    enqueue(event: Event): void;
-    /**
-     * Error situations:
-     *  - Any error while enqueueing or scheduling flush (including a synchronous throw from `flush`): log "Failed to enqueue low event"
-     */
-    enqueueLow(low: LowEvent): void;
-    /**
-     * 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>;
-    private setupLifecycleHooks;
-    /**
-     * Synchronously flush both events and lows via `sendBeacon` if the transport supports it.
-     * Safe to call multiple times: a no-op when both queues are empty.
-     */
-    flushKeepalive(): void;
-    private flushSync;
-    /**
-     * Error situations:
-     *  - Timer clearance or event listener removal throws: log "Failed to destroy queue lifecycle hooks"
-     */
-    destroy(): void;
-}
-
 interface StorageEngine {
     getItem<T>(key: string): T | null;
     setItem<T>(key: string, value: T): void;
@@ -727,9 +835,282 @@ declare class SessionStorage implements StorageEngine {
     removeItem(key: string): void;
 }
 
+interface QueueOptions {
+    /**
+     * Maximum number of events per request (payload cap). A backlog larger than this is drained in
+     * sequential capped batches within one flush. Reaching this size does NOT trigger an early
+     * flush — delivery cadence is controlled solely by the flush interval.
+     */
+    batchSize?: number;
+    /**
+     * Explicit override of the flush timer interval; otherwise `config.flushIntervalMs` is used.
+     * Internal/test use only — the tracker does not pass this; the interval is server-controlled.
+     */
+    flushInterval?: number;
+    debug?: boolean;
+    /**
+     * Reliability config snapshot for this page load; defaults to all-features-OFF. Boot-snapshot
+     * model: 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.
+     */
+    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. */
+    requestConfig?: boolean;
+}
+/**
+ * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
+ * trigger a synchronous unload flush (`flushSync`). Any thrown error in that path is logged as
+ * "Unexpected error in queue flushSync". Sync flushes are deduplicated: once everything pending has
+ * been handed to a sync transport, further lifecycle signals are no-ops until something new is
+ * enqueued — otherwise a single navigation would resend the same batch several times
+ * (visibilitychange + pagehide + per-input flushKeepalive), since entries are intentionally kept
+ * under `durableOutbox`.
+ *
+ * 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.
+ *
+ * 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.
+ */
+declare class RequestQueue {
+    private readonly logger;
+    private transport;
+    private sessionId;
+    private readonly sdk;
+    private readonly storage?;
+    private pending;
+    private lowsQueue;
+    private timer;
+    private isFlushing;
+    /**
+     * True when something was enqueued (or recovered) since the last sync flush. visibilitychange,
+     * pagehide and per-input flushKeepalive calls all funnel into flushSync; this flag makes the
+     * duplicate calls no-ops. The async flush path ignores it.
+     */
+    private dirtySinceSyncFlush;
+    private onVisibilityChange;
+    private onPageHide;
+    private readonly batchSize;
+    private readonly flushIntervalOverride?;
+    private readonly debug;
+    private readonly requestConfig;
+    private readonly onConfigReceived?;
+    private readonly config;
+    /** Event names that trigger an immediate flush at enqueue time (config.flushOnEventNames). */
+    private readonly priorityNames;
+    private store?;
+    /**
+     * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
+     * next load, 204 = cached version still current) we stop sending the header for this load. A
+     * transport-level failure or error status keeps the request pending for the next flush.
+     */
+    private configResolved;
+    constructor(logger: Logger, transport: Transport, sessionId: string, sdk: SdkInfo, options?: QueueOptions, storage?: StorageEngine | undefined);
+    setSessionId(sessionId: string): void;
+    private flushInterval;
+    /**
+     * Error situations:
+     *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue event"
+     */
+    enqueue(event: Event): void;
+    /**
+     * Error situations:
+     *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue low event"
+     */
+    enqueueLow(low: LowEvent): void;
+    private scheduleAfterEnqueue;
+    private scheduleFlush;
+    private clearTimer;
+    /**
+     * 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>;
+    /**
+     * 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`.
+     */
+    private attachBatchMeta;
+    private getDuePending;
+    private takeLows;
+    private shouldRequestConfig;
+    /**
+     * Handle the server's answer to the config request. Boot-snapshot model: a fresh config is ONLY
+     * handed to `onConfigReceived` for caching — it is never applied to this load. The behavior the
+     * queue was constructed with stays in effect until the page unloads.
+     */
+    private handleConfigResponse;
+    /** Returns true when the batch was acknowledged with a 2xx (safe to keep draining). */
+    private handleSendResult;
+    private isRetryable;
+    /**
+     * Exponential backoff with equal jitter. The exponential ceiling is `baseDelayMs * 2^(attempt-1)`
+     * (capped at `maxDelayMs`); the actual delay is half that ceiling plus a random portion of the other
+     * half. The jitter spreads retries from many clients to avoid synchronized retry storms and needs no
+     * extra config. A `Retry-After` header, when present, acts as a lower bound.
+     */
+    private backoffForAttempt;
+    private parseRetryAfter;
+    private removeEntries;
+    private rescheduleIfPending;
+    private setupLifecycleHooks;
+    private writeLifecycleDebugOutput;
+    /**
+     * Synchronously flush pending events (and best-effort lows) during page unload.
+     *
+     * @remarks
+     * When `config.beaconKeepalive` is on, uses `sendBeacon` (falling back to fetch keepalive when
+     * the UA refuses the beacon); otherwise fires a fire-and-forget `fetch` keepalive request. The
+     * send is capped at one `batchSize` chunk per call (unload transports share an in-flight budget
+     * 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.
+     */
+    flushKeepalive(): void;
+    private flushSync;
+    /**
+     * Error situations:
+     *  - Timer clearance or event listener removal throws: log "Failed to destroy queue lifecycle hooks"
+     */
+    destroy(): void;
+}
+
+/** localStorage key under which the last-known server config is cached. */
+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
+ * is the config version the SDK is currently running, or "1" when none is cached yet. The server
+ * answers 204 when that version is still current and 200 + config body when it is stale.
+ */
+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;
+/**
+ * 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
+ * the same bounds as the first line of defense.
+ */
+declare const CONFIG_BOUNDS: {
+    readonly flushIntervalMs: {
+        readonly min: 100;
+        readonly max: 60000;
+    };
+    readonly retryMaxAttempts: {
+        readonly min: 1;
+        readonly max: 10;
+    };
+    readonly retryDelayMs: {
+        readonly min: 50;
+        readonly max: 120000;
+    };
+    readonly sessionInactivityMs: {
+        readonly min: 60000;
+        readonly max: 86400000;
+    };
+    readonly flushOnEventNames: {
+        readonly maxEntries: 20;
+        readonly maxNameLength: 100;
+    };
+};
+/** 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 then cached as last-known and
+ * applied on the NEXT page load — boot-snapshot model). The empty version means "nothing cached";
+ * the config request header sends "1" in that case.
+ */
+declare const DEFAULT_RELIABILITY_CONFIG: SdkReliabilityConfig;
+/**
+ * Coerce an arbitrary value (cached blob or parsed API body) into a {@link SdkReliabilityConfig}.
+ * Returns `null` if the input is not an object or carries no `version` (a config without identity
+ * cannot participate in the version handshake and must not be trusted). Missing fields fall back to
+ * the OFF defaults so a partial/older payload can never silently enable a feature; the
+ * flush-trigger switches (`tvc`/`tph`/`td`) invert this and default ON, so a partial payload can
+ * never silently disable delivery. Numeric values are clamped to {@link CONFIG_BOUNDS} so a bad
+ * server value cannot harm the client.
+ */
+declare function parseReliabilityConfig(raw: unknown): SdkReliabilityConfig | null;
+/** 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 {
+    /** Event idempotency id; primary key of the entry. */
+    id: string;
+    /** Session id snapshot taken at enqueue time (so session rotation never relabels old entries). */
+    sessionId: string;
+    /** Earliest timestamp (ms) at which this entry may be sent again (backoff). `0` = due now. */
+    flushAfter: number;
+    /** Number of completed send attempts so far. */
+    attempts: number;
+    /** The event payload. */
+    event: Event;
+}
+/** localStorage key under which the durable outbox is persisted. */
+declare const OUTBOX_STORAGE_KEY = "cbo_outbox";
+/** Web Lock name guarding outbox mutations across tabs. */
+declare const OUTBOX_LOCK_NAME = "cbo_outbox";
+/** Default maximum number of entries kept; oldest are evicted past this. */
+declare const DEFAULT_MAX_ENTRIES = 500;
+/**
+ * Default budget for the outbox's serialized size, in UTF-16 code units (the unit localStorage
+ * quotas are measured in; ~1 MB on disk). The entry-count cap alone does not bound bytes —
+ * `event.data` is arbitrary customer payload — and localStorage's ~5M-unit quota is shared with
+ * the HOST app: an unbounded outbox could make the host's own writes throw QuotaExceededError.
+ */
+declare const DEFAULT_MAX_SERIALIZED_LENGTH: number;
+/**
+ * Durable, localStorage-backed outbox of pending events, mirrored in memory.
+ *
+ * @remarks
+ * Every mutation is a read-merge-write against storage, executed under a cross-tab Web Lock
+ * ({@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
+ * between the read and the write (which would silently drop the other tab's entries). Where the
+ * Web Locks API is unavailable the mutation runs unlocked, matching the historical best-effort
+ * behavior. Mutations never reject; failures are logged.
+ * The store is size-capped; overflow evicts the oldest entries and logs the count.
+ */
+declare class EventStore {
+    private readonly storage;
+    private readonly logger;
+    private readonly maxEntries;
+    private readonly maxSerializedLength;
+    private entries;
+    /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
+    private reportedMalformed;
+    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number);
+    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>;
+    /** Re-read from storage and return all entries (memory mirror refreshed). */
+    all(): OutboxEntry[];
+    /** Entries whose `flushAfter` has elapsed, in insertion order. */
+    getDue(now: number): OutboxEntry[];
+    /** 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>;
+    size(): number;
+}
+
 declare function init(options: TrackerOptions): CorbadoTracker;
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
 declare function destroy(): Promise<void>;
 
-export { type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, type DeviceInfo, 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 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, OperationFull, OperationFullProvideIdentifierWithCUI, 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, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, SessionStorage, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, createLogger, destroy, getTracker, init, resetSession };
+export { type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, 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_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, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, 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 SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, createLogger, destroy, getTracker, init, loadCachedConfig, parseReliabilityConfig, resetSession };