@corbado/observe 0.8.0 → 0.9.0-next.67-2a142aa

package/dist/index.d.mts

@@ -85,7 +85,7 @@ type Conversion = {
 } & UserReference;
 type FlowFinished = {
     flowName: FlowType;
-    explicitOutcome?: "skipped" | "visible-auto-skip" | "invisble";
+    explicitOutcome?: "skipped" | "visible-auto-skip" | "invisible";
 } & UserReference;
 type FlowReset = {
     flowName?: FlowType;
@@ -160,6 +160,21 @@ interface LowEvent {
     ts: number;
     durationMs?: number;
 }
+type TelemetryLevel = "info" | "error";
+/**
+ * A diagnostic telemetry entry (a severity level + free-form message) recorded by the integrating
+ * app or by the SDK itself. Telemetry rides along in the `telemetry` array of the events endpoint
+ * payload, tied to the same session, and is never classified as an auth-flow event.
+ */
+interface TelemetryEntry {
+    /** Client-generated idempotency id (uuidv7) so safe resends (retry/beacon) dedupe server-side. */
+    id: string;
+    level: TelemetryLevel;
+    /** Free-form diagnostic message. Truncated client-side. Must not contain credentials or PII. */
+    message: string;
+    /** Capture time, unix ms. */
+    ts: number;
+}
 interface EventBatchMeta {
     sent: number;
     transport: "fetch" | "beacon";
@@ -180,6 +195,7 @@ interface EventBatch {
     events: Event[];
     sdk: SdkInfo;
     lows?: LowEvent[];
+    telemetry?: TelemetryEntry[];
     meta?: EventBatchMeta;
 }
 type DeviceType = "web" | "app" | "other";
@@ -214,6 +230,7 @@ type JavaScriptHighEntropy = {
     platform?: string;
     mobile?: boolean;
     platformVersion?: string;
+    model?: string;
 };
 type ClientEnvHandleMeta = {
     timestamp: number;
@@ -279,6 +296,18 @@ interface SdkReliabilityConfig {
      * the historical behavior; can be disabled server-side to rely solely on the queue's triggers.
      */
     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.
+     */
+    telemetry: boolean;
+    /**
+     * When true (and `telemetry` is enabled), enqueuing a telemetry entry triggers an immediate flush
+     * so diagnostics go out promptly (e.g. before a crash/navigation). Defaults to false: a telemetry
+     * entry alone never triggers a flush, it only rides the next flush caused by anything else.
+     */
+    flushOnTelemetry: boolean;
     /**
      * Event names that trigger an immediate flush when enqueued (e.g. `flow_finished`,
      * `conversion`), so high-value events go out via a normal fetch while the page is still alive
@@ -291,12 +320,22 @@ interface SdkReliabilityConfig {
     retry: SdkRetryConfig;
 }
 
+/** Sink that escalates a diagnostic message to the telemetry stream. */
+type TelemetrySink = (level: TelemetryLevel, message: string) => void;
 interface Logger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
     critical(message: string, ...args: unknown[]): void;
+    /**
+     * Escalate a diagnostic message to the telemetry stream, if a sink is attached (no-op otherwise).
+     * Unlike the level methods, telemetry is delivered to the backend regardless of the `debug` flag.
+     * Optional so an integrator-provided custom logger stays valid without implementing it.
+     */
+    reportTelemetry?(level: TelemetryLevel, message: string): void;
+    /** Attach (or clear) the telemetry sink. Called once by the tracker after the queue exists. */
+    setTelemetrySink?(sink: TelemetrySink | undefined): void;
 }
 interface CreateLoggerOptions {
     debug: boolean;
@@ -553,10 +592,11 @@ type PasswordEnrollmentTypedError = {
 type PasswordEnrollmentTypedErrorCode = "requirements_not_fulfilled";
 type PasswordEnrollmentExplicitSpecType = "password-set" | "password-reset";
 type PasswordEnrollmentAutoTrackConfig = {
-    explicitSpecType: PasswordEnrollmentExplicitSpecType;
-    inputHtmlField: HTMLInputElement;
+    explicitSpecType?: PasswordEnrollmentExplicitSpecType;
+    inputHtmlField?: HTMLInputElement;
 };
 declare class PasswordEnrollmentOperationFull extends OperationFull {
+    readonly clientValidation: StepHelper;
     readonly postResponse: StepHelper<{}, {}, PasswordEnrollmentTypedError>;
     private lowEventTracker?;
     constructor(tracker: CorbadoTracker, autoTrackConfig?: PasswordEnrollmentAutoTrackConfig);
@@ -641,6 +681,28 @@ declare class AppConfirmationOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
 }
 
+type ProvideDataOperationSpecType = "signup" | "login" | "recovery" | "enrollment";
+type ProvideDataOperationStart = {
+    /** Stable name of the data field collected by this subflow, when known. */
+    fieldName?: string;
+    explicitSpecType?: ProvideDataOperationSpecType;
+};
+type ProvideDataOperationConfig = ProvideDataOperationStart & {
+    /** The input field whose low-level interaction signals should be collected. */
+    inputHtmlField?: HTMLInputElement;
+};
+type ProvideDataOperationPostResponseStart = {
+    explicitSpecType?: ProvideDataOperationSpecType;
+};
+/** Tracks a user-triggered data submission and its server response. */
+declare class ProvideDataOperationFull extends OperationFull {
+    readonly clientValidation: StepHelper;
+    readonly postResponse: StepHelper<ProvideDataOperationPostResponseStart>;
+    private lowEventTracker?;
+    constructor(tracker: CorbadoTracker, config?: ProvideDataOperationConfig);
+    destroy(): void;
+}
+
 interface TrackerOptions {
     projectId: string;
     apiBaseUrl: string;
@@ -649,7 +711,10 @@ interface TrackerOptions {
     cookieDomain?: string;
     debug?: boolean;
     logger?: Logger;
+    /** Minimum time between attaching cached device info to events. */
     deviceInfoDebounceTime?: number;
+    /** Per-field collection timeout. Defaults to 200ms. */
+    deviceInfoCollectorTimeout?: number;
     defaultTags?: Record<string, string>;
     /**
      * Experiment assignments to seed at init (experiment key → variant). Merged over any persisted
@@ -664,6 +729,8 @@ interface TrackerOptions {
      * It will be removed in a future release.
      */
     flushInterval?: number;
+    /** Generates new Observe session ids; returned values must be UUID-compatible. Existing stored sessions are still reused. */
+    sessionIdGenerator?: () => string;
 }
 declare class CorbadoTracker {
     private options;
@@ -680,12 +747,15 @@ declare class CorbadoTracker {
      * (see {@link handleConfig}).
      */
     private config;
-    private deviceInfoCollector;
-    private deviceInfoDebounceTime;
-    private deviceInfoTransmittedLastTime;
+    private deviceInfoManager;
     private seq;
     /** Persistent experiment assignments (experiment key → variant), attached to every produced event. */
     private experiments;
+    /** Self-instrumentation state: re-entrancy guard, readiness, per-load dedupe, and pre-queue buffer. */
+    private telemetryReporting;
+    private telemetryReady;
+    private readonly reportedTelemetryKeys;
+    private pendingSelfTelemetry;
     constructor(options: TrackerOptions);
     /**
      * Cache fresh server config as last-known so the next page load boots with it. When this load
@@ -735,6 +805,7 @@ declare class CorbadoTracker {
      */
     private resolveExperiments;
     private isTrackingBlocked;
+    private createSessionId;
     private getSessionId;
     /**
      * Resolve the session id from localStorage so it survives reloads and is shared across tabs of the
@@ -746,8 +817,8 @@ declare class CorbadoTracker {
      * 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
+     * Locks are unavailable or take more than 5ms it degrades to the historical best-effort merge).
+     * Lock grants are FIFO, so seq order matches `track()` call order within a tab. Every tracked event also bumps the
      * continuity session's `lastActiveAt`, so the inactivity window measures real user inactivity
      * instead of time-since-page-load (a long-lived active tab must not rotate the session on the next
      * reload). An empty store while this load already has a session id means persistence is failing
@@ -755,7 +826,6 @@ declare class CorbadoTracker {
      * to one session per page load instead of one session per event.
      */
     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;
@@ -767,7 +837,7 @@ declare class CorbadoTracker {
     /**
      * Error situations:
      *  - Blocked user agent (see `isBlockedUserAgent`): skip with a debug log and return
-     *  - Any error before the event is enqueued (e.g. device info update, `JSON.stringify` in debug logging, `queue.enqueue`): log `Failed to process event "<name>" before enqueue`
+     *  - Any error before the event is enqueued (e.g. `JSON.stringify` in debug logging, `queue.enqueue`): log `Failed to process event "<name>" before enqueue`
      *
      * @internal
      */
@@ -926,6 +996,35 @@ declare class CorbadoTracker {
      * @internal
      */
     enqueueLowEvent(low: LowEvent): void;
+    /**
+     * Record a diagnostic telemetry entry (a `level` + free-form `message`) for the current session.
+     *
+     * @remarks
+     * Telemetry is delivered in the `telemetry` array of the events endpoint payload, tied to the same
+     * session, and is never classified as an auth-flow event. By default a telemetry entry piggybacks
+     * the next normal flush (it does not trigger one on its own); this is server-controlled. Collection
+     * can be turned off server-side via the `telemetry` config flag. Blocked user agents are skipped.
+     *
+     * The message is truncated to {@link TELEMETRY_MESSAGE_MAX} characters. Never pass credentials or
+     * PII — telemetry is for diagnostics only. Like all SDK entry points, this never throws.
+     */
+    telemetry(level: TelemetryLevel, message: string): void;
+    /** Convenience wrapper for {@link CorbadoTracker.telemetry} at `info` level. */
+    logInfo(message: string): void;
+    /** Convenience wrapper for {@link CorbadoTracker.telemetry} at `error` level. */
+    logError(message: string): void;
+    /**
+     * Escalate an internal SDK diagnostic to the telemetry stream (self-instrumentation). This is the
+     * sink behind {@link Logger.reportTelemetry}; chosen internal failure sites route here so faults
+     * that are otherwise only visible with `debug: true` become observable in the field.
+     *
+     * @remarks
+     * Bounded and deduped per load (a persistent fault — blocked storage, a downed endpoint — cannot
+     * flood the stream), re-entrancy-guarded so it can never recurse, and it never throws into the
+     * host. Diagnostics raised before the queue exists (early boot) are buffered and replayed once the
+     * queue is ready. Messages must be stable and low-cardinality (no raw error objects / PII).
+     */
+    private reportTelemetry;
     /**
      * Synchronously flush any pending events and low events via beacon. Use during page-unload
      * style teardown where async flushing is unreliable.
@@ -949,6 +1048,7 @@ declare class CorbadoTracker {
     emailOtpOperationFull(): EmailOtpOperationFull;
     smsOtpOperationFull(): SmsOtpOperationFull;
     provideIdentifierOperationFull(inputHtmlField?: HTMLInputElement): OperationFullProvideIdentifierWithCUI;
+    provideDataOperationFull(config?: ProvideDataOperationConfig): ProvideDataOperationFull;
     socialLoginOperationFull(): SocialLoginOperationFull;
     appConfirmationOperationFull(explicitSpecType?: AppConfirmationOperationSpecType): AppConfirmationOperationFull;
     /**
@@ -1116,6 +1216,12 @@ declare class RequestQueue {
     private readonly storage?;
     private pending;
     private lowsQueue;
+    /**
+     * 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
+     * the flush timer (it piggybacks), unless `config.flushOnTelemetry` escalates to an immediate flush.
+     */
+    private telemetryQueue;
     private timer;
     private isFlushing;
     private destroyed;
@@ -1160,6 +1266,19 @@ declare class RequestQueue {
      *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue low event"
      */
     enqueueLow(low: LowEvent): 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.
+     * 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.
+     *
+     * Error situations:
+     *  - Any error while enqueueing or triggering the flush: log "Failed to enqueue telemetry"
+     */
+    enqueueTelemetry(entry: TelemetryEntry): void;
     private scheduleAfterEnqueue;
     private scheduleFlush;
     private clearTimer;
@@ -1179,6 +1298,7 @@ declare class RequestQueue {
     private attachBatchMeta;
     private getDuePending;
     private takeLows;
+    private takeTelemetry;
     private shouldRequestConfig;
     /**
      * Handle the server's answer to the config request. With a cached boot config the boot-snapshot
@@ -1364,6 +1484,9 @@ declare function setExperiments(assignments: Record<string, string>): void;
 declare function clearExperiment(key: string): void;
 declare function clearExperiments(): void;
 declare function getExperiments(): Record<string, string>;
+declare function telemetry(level: TelemetryLevel, message: string): void;
+declare function logInfo(message: string): void;
+declare function logError(message: string): void;
 declare function destroy(): Promise<void>;
 
-export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, OperationFull, OperationFullProvideIdentifierWithCUI, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentOperationFull, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getTracker, init, loadCachedConfig, parseReliabilityConfig, resetSession, setExperiment, setExperiments };
+export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, OperationFull, OperationFullProvideIdentifierWithCUI, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentOperationFull, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };

package/dist/index.d.ts

@@ -85,7 +85,7 @@ type Conversion = {
 } & UserReference;
 type FlowFinished = {
     flowName: FlowType;
-    explicitOutcome?: "skipped" | "visible-auto-skip" | "invisble";
+    explicitOutcome?: "skipped" | "visible-auto-skip" | "invisible";
 } & UserReference;
 type FlowReset = {
     flowName?: FlowType;
@@ -160,6 +160,21 @@ interface LowEvent {
     ts: number;
     durationMs?: number;
 }
+type TelemetryLevel = "info" | "error";
+/**
+ * A diagnostic telemetry entry (a severity level + free-form message) recorded by the integrating
+ * app or by the SDK itself. Telemetry rides along in the `telemetry` array of the events endpoint
+ * payload, tied to the same session, and is never classified as an auth-flow event.
+ */
+interface TelemetryEntry {
+    /** Client-generated idempotency id (uuidv7) so safe resends (retry/beacon) dedupe server-side. */
+    id: string;
+    level: TelemetryLevel;
+    /** Free-form diagnostic message. Truncated client-side. Must not contain credentials or PII. */
+    message: string;
+    /** Capture time, unix ms. */
+    ts: number;
+}
 interface EventBatchMeta {
     sent: number;
     transport: "fetch" | "beacon";
@@ -180,6 +195,7 @@ interface EventBatch {
     events: Event[];
     sdk: SdkInfo;
     lows?: LowEvent[];
+    telemetry?: TelemetryEntry[];
     meta?: EventBatchMeta;
 }
 type DeviceType = "web" | "app" | "other";
@@ -214,6 +230,7 @@ type JavaScriptHighEntropy = {
     platform?: string;
     mobile?: boolean;
     platformVersion?: string;
+    model?: string;
 };
 type ClientEnvHandleMeta = {
     timestamp: number;
@@ -279,6 +296,18 @@ interface SdkReliabilityConfig {
      * the historical behavior; can be disabled server-side to rely solely on the queue's triggers.
      */
     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.
+     */
+    telemetry: boolean;
+    /**
+     * When true (and `telemetry` is enabled), enqueuing a telemetry entry triggers an immediate flush
+     * so diagnostics go out promptly (e.g. before a crash/navigation). Defaults to false: a telemetry
+     * entry alone never triggers a flush, it only rides the next flush caused by anything else.
+     */
+    flushOnTelemetry: boolean;
     /**
      * Event names that trigger an immediate flush when enqueued (e.g. `flow_finished`,
      * `conversion`), so high-value events go out via a normal fetch while the page is still alive
@@ -291,12 +320,22 @@ interface SdkReliabilityConfig {
     retry: SdkRetryConfig;
 }
 
+/** Sink that escalates a diagnostic message to the telemetry stream. */
+type TelemetrySink = (level: TelemetryLevel, message: string) => void;
 interface Logger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
     critical(message: string, ...args: unknown[]): void;
+    /**
+     * Escalate a diagnostic message to the telemetry stream, if a sink is attached (no-op otherwise).
+     * Unlike the level methods, telemetry is delivered to the backend regardless of the `debug` flag.
+     * Optional so an integrator-provided custom logger stays valid without implementing it.
+     */
+    reportTelemetry?(level: TelemetryLevel, message: string): void;
+    /** Attach (or clear) the telemetry sink. Called once by the tracker after the queue exists. */
+    setTelemetrySink?(sink: TelemetrySink | undefined): void;
 }
 interface CreateLoggerOptions {
     debug: boolean;
@@ -553,10 +592,11 @@ type PasswordEnrollmentTypedError = {
 type PasswordEnrollmentTypedErrorCode = "requirements_not_fulfilled";
 type PasswordEnrollmentExplicitSpecType = "password-set" | "password-reset";
 type PasswordEnrollmentAutoTrackConfig = {
-    explicitSpecType: PasswordEnrollmentExplicitSpecType;
-    inputHtmlField: HTMLInputElement;
+    explicitSpecType?: PasswordEnrollmentExplicitSpecType;
+    inputHtmlField?: HTMLInputElement;
 };
 declare class PasswordEnrollmentOperationFull extends OperationFull {
+    readonly clientValidation: StepHelper;
     readonly postResponse: StepHelper<{}, {}, PasswordEnrollmentTypedError>;
     private lowEventTracker?;
     constructor(tracker: CorbadoTracker, autoTrackConfig?: PasswordEnrollmentAutoTrackConfig);
@@ -641,6 +681,28 @@ declare class AppConfirmationOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker, explicitSpecType?: AppConfirmationOperationSpecType);
 }
 
+type ProvideDataOperationSpecType = "signup" | "login" | "recovery" | "enrollment";
+type ProvideDataOperationStart = {
+    /** Stable name of the data field collected by this subflow, when known. */
+    fieldName?: string;
+    explicitSpecType?: ProvideDataOperationSpecType;
+};
+type ProvideDataOperationConfig = ProvideDataOperationStart & {
+    /** The input field whose low-level interaction signals should be collected. */
+    inputHtmlField?: HTMLInputElement;
+};
+type ProvideDataOperationPostResponseStart = {
+    explicitSpecType?: ProvideDataOperationSpecType;
+};
+/** Tracks a user-triggered data submission and its server response. */
+declare class ProvideDataOperationFull extends OperationFull {
+    readonly clientValidation: StepHelper;
+    readonly postResponse: StepHelper<ProvideDataOperationPostResponseStart>;
+    private lowEventTracker?;
+    constructor(tracker: CorbadoTracker, config?: ProvideDataOperationConfig);
+    destroy(): void;
+}
+
 interface TrackerOptions {
     projectId: string;
     apiBaseUrl: string;
@@ -649,7 +711,10 @@ interface TrackerOptions {
     cookieDomain?: string;
     debug?: boolean;
     logger?: Logger;
+    /** Minimum time between attaching cached device info to events. */
     deviceInfoDebounceTime?: number;
+    /** Per-field collection timeout. Defaults to 200ms. */
+    deviceInfoCollectorTimeout?: number;
     defaultTags?: Record<string, string>;
     /**
      * Experiment assignments to seed at init (experiment key → variant). Merged over any persisted
@@ -664,6 +729,8 @@ interface TrackerOptions {
      * It will be removed in a future release.
      */
     flushInterval?: number;
+    /** Generates new Observe session ids; returned values must be UUID-compatible. Existing stored sessions are still reused. */
+    sessionIdGenerator?: () => string;
 }
 declare class CorbadoTracker {
     private options;
@@ -680,12 +747,15 @@ declare class CorbadoTracker {
      * (see {@link handleConfig}).
      */
     private config;
-    private deviceInfoCollector;
-    private deviceInfoDebounceTime;
-    private deviceInfoTransmittedLastTime;
+    private deviceInfoManager;
     private seq;
     /** Persistent experiment assignments (experiment key → variant), attached to every produced event. */
     private experiments;
+    /** Self-instrumentation state: re-entrancy guard, readiness, per-load dedupe, and pre-queue buffer. */
+    private telemetryReporting;
+    private telemetryReady;
+    private readonly reportedTelemetryKeys;
+    private pendingSelfTelemetry;
     constructor(options: TrackerOptions);
     /**
      * Cache fresh server config as last-known so the next page load boots with it. When this load
@@ -735,6 +805,7 @@ declare class CorbadoTracker {
      */
     private resolveExperiments;
     private isTrackingBlocked;
+    private createSessionId;
     private getSessionId;
     /**
      * Resolve the session id from localStorage so it survives reloads and is shared across tabs of the
@@ -746,8 +817,8 @@ declare class CorbadoTracker {
      * 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
+     * Locks are unavailable or take more than 5ms it degrades to the historical best-effort merge).
+     * Lock grants are FIFO, so seq order matches `track()` call order within a tab. Every tracked event also bumps the
      * continuity session's `lastActiveAt`, so the inactivity window measures real user inactivity
      * instead of time-since-page-load (a long-lived active tab must not rotate the session on the next
      * reload). An empty store while this load already has a session id means persistence is failing
@@ -755,7 +826,6 @@ declare class CorbadoTracker {
      * to one session per page load instead of one session per event.
      */
     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;
@@ -767,7 +837,7 @@ declare class CorbadoTracker {
     /**
      * Error situations:
      *  - Blocked user agent (see `isBlockedUserAgent`): skip with a debug log and return
-     *  - Any error before the event is enqueued (e.g. device info update, `JSON.stringify` in debug logging, `queue.enqueue`): log `Failed to process event "<name>" before enqueue`
+     *  - Any error before the event is enqueued (e.g. `JSON.stringify` in debug logging, `queue.enqueue`): log `Failed to process event "<name>" before enqueue`
      *
      * @internal
      */
@@ -926,6 +996,35 @@ declare class CorbadoTracker {
      * @internal
      */
     enqueueLowEvent(low: LowEvent): void;
+    /**
+     * Record a diagnostic telemetry entry (a `level` + free-form `message`) for the current session.
+     *
+     * @remarks
+     * Telemetry is delivered in the `telemetry` array of the events endpoint payload, tied to the same
+     * session, and is never classified as an auth-flow event. By default a telemetry entry piggybacks
+     * the next normal flush (it does not trigger one on its own); this is server-controlled. Collection
+     * can be turned off server-side via the `telemetry` config flag. Blocked user agents are skipped.
+     *
+     * The message is truncated to {@link TELEMETRY_MESSAGE_MAX} characters. Never pass credentials or
+     * PII — telemetry is for diagnostics only. Like all SDK entry points, this never throws.
+     */
+    telemetry(level: TelemetryLevel, message: string): void;
+    /** Convenience wrapper for {@link CorbadoTracker.telemetry} at `info` level. */
+    logInfo(message: string): void;
+    /** Convenience wrapper for {@link CorbadoTracker.telemetry} at `error` level. */
+    logError(message: string): void;
+    /**
+     * Escalate an internal SDK diagnostic to the telemetry stream (self-instrumentation). This is the
+     * sink behind {@link Logger.reportTelemetry}; chosen internal failure sites route here so faults
+     * that are otherwise only visible with `debug: true` become observable in the field.
+     *
+     * @remarks
+     * Bounded and deduped per load (a persistent fault — blocked storage, a downed endpoint — cannot
+     * flood the stream), re-entrancy-guarded so it can never recurse, and it never throws into the
+     * host. Diagnostics raised before the queue exists (early boot) are buffered and replayed once the
+     * queue is ready. Messages must be stable and low-cardinality (no raw error objects / PII).
+     */
+    private reportTelemetry;
     /**
      * Synchronously flush any pending events and low events via beacon. Use during page-unload
      * style teardown where async flushing is unreliable.
@@ -949,6 +1048,7 @@ declare class CorbadoTracker {
     emailOtpOperationFull(): EmailOtpOperationFull;
     smsOtpOperationFull(): SmsOtpOperationFull;
     provideIdentifierOperationFull(inputHtmlField?: HTMLInputElement): OperationFullProvideIdentifierWithCUI;
+    provideDataOperationFull(config?: ProvideDataOperationConfig): ProvideDataOperationFull;
     socialLoginOperationFull(): SocialLoginOperationFull;
     appConfirmationOperationFull(explicitSpecType?: AppConfirmationOperationSpecType): AppConfirmationOperationFull;
     /**
@@ -1116,6 +1216,12 @@ declare class RequestQueue {
     private readonly storage?;
     private pending;
     private lowsQueue;
+    /**
+     * 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
+     * the flush timer (it piggybacks), unless `config.flushOnTelemetry` escalates to an immediate flush.
+     */
+    private telemetryQueue;
     private timer;
     private isFlushing;
     private destroyed;
@@ -1160,6 +1266,19 @@ declare class RequestQueue {
      *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue low event"
      */
     enqueueLow(low: LowEvent): 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.
+     * 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.
+     *
+     * Error situations:
+     *  - Any error while enqueueing or triggering the flush: log "Failed to enqueue telemetry"
+     */
+    enqueueTelemetry(entry: TelemetryEntry): void;
     private scheduleAfterEnqueue;
     private scheduleFlush;
     private clearTimer;
@@ -1179,6 +1298,7 @@ declare class RequestQueue {
     private attachBatchMeta;
     private getDuePending;
     private takeLows;
+    private takeTelemetry;
     private shouldRequestConfig;
     /**
      * Handle the server's answer to the config request. With a cached boot config the boot-snapshot
@@ -1364,6 +1484,9 @@ declare function setExperiments(assignments: Record<string, string>): void;
 declare function clearExperiment(key: string): void;
 declare function clearExperiments(): void;
 declare function getExperiments(): Record<string, string>;
+declare function telemetry(level: TelemetryLevel, message: string): void;
+declare function logInfo(message: string): void;
+declare function logError(message: string): void;
 declare function destroy(): Promise<void>;
 
-export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, OperationFull, OperationFullProvideIdentifierWithCUI, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentOperationFull, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getTracker, init, loadCachedConfig, parseReliabilityConfig, resetSession, setExperiment, setExperiments };
+export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, OperationFull, OperationFullProvideIdentifierWithCUI, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentOperationFull, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };