@corbado/observe 1.4.0 → 1.5.1

package/dist/index.d.mts

@@ -560,20 +560,17 @@ interface SdkReliabilityConfig {
      */
     flushOnFlowTypeFinished: FlowType[];
     /**
-     * Per-field timeout for device info collection, in milliseconds. A field whose browser API does
-     * not answer within this budget is recorded as a `TimeoutError` in `collectionErrors` and left
-     * undefined; the remaining fields are unaffected. Defaults to 1000ms.
-     *
-     * Read at collection time, so a config that arrives mid-load applies from the next device info
-     * refresh onward. The very first collection of a load booting on the built-in defaults (nothing
-     * cached) always runs on the default.
+     * @deprecated No effect since device info is collected with built-in deadlines (a fast snapshot
+     * within 300 ms, slower fields as a later update within 6000 ms). Still parsed so older server
+     * configs keep loading; the backend keeps serving it for older SDK versions.
      */
     deviceInfoCollectorTimeoutMs: number;
     /**
-     * When true (and `telemetry` is enabled), every device info collection emits an `info` telemetry
-     * entry with the total duration and the per-field durations in milliseconds. Defaults to false:
-     * this is a diagnostic stream to switch on while investigating slow collection, not something to
-     * run permanently.
+     * When true (and `telemetry` is enabled), device info collection emits `info` telemetry entries:
+     * the fast snapshot's total and per-field durations in milliseconds, the late fields' outcome, the
+     * `privateMode` source (cache age, detection duration or timeout) and how the update was delivered
+     * (or that it was left undelivered at pagehide / destroy). Defaults to false: this is a diagnostic
+     * stream to switch on while investigating slow collection, not something to run permanently.
      */
     deviceInfoTiming: boolean;
     /** Serialize explicitly supplied raw error diagnostics. Defaults to true; refreshes apply to subsequent errors. Already queued events are unchanged. */
@@ -1589,10 +1586,9 @@ interface TrackerOptions {
     /** Minimum time between attaching cached device info to events. */
     deviceInfoDebounceTime?: number;
     /**
-     * @deprecated The device info collection timeout is server-controlled via the SDK reliability
-     * config (`deviceInfoCollectorTimeoutMs`). This option only applies as long as no server config
-     * has been received (i.e. before the first config response is cached); once a server config is
-     * cached it wins. It will be removed in a future release.
+     * @deprecated No effect: device info is collected with built-in deadlines (a fast snapshot within
+     * 300 ms, slower fields as a later update within 6000 ms). Still accepted so existing integrations
+     * keep compiling. It will be removed in a future release.
      */
     deviceInfoCollectorTimeout?: number;
     defaultTags?: Record<string, string>;
@@ -2094,6 +2090,17 @@ declare class CorbadoTracker {
     logInfo(message: string): void;
     /** Convenience wrapper for {@link CorbadoTracker.telemetry} at `error` level. */
     logError(message: string): void;
+    /**
+     * Queue hook run right before an event batch is sent: a device info snapshot that no event carried
+     * yet (typically the fast snapshot after a burst of events at page load, or the privateMode update)
+     * rides the first event of this page in the batch that has none. Events of other pages (outbox
+     * replays) are never touched, and nothing is sent just for device info. When the page goes away
+     * with a snapshot nothing could carry, that is reported (timing diagnostics only).
+     *
+     * Error situations:
+     *  - Any error: log "Failed to attach device info to batch" and send the batch unchanged
+     */
+    private attachUndeliveredDeviceInfo;
     /**
      * 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
@@ -2382,6 +2389,14 @@ interface QueueOptions {
      * none has ever been set. Read at send time so a change applies to the next batch without a flush.
      */
     getDataPolicy?: () => number | undefined;
+    /**
+     * Called with the events of every event batch right before it is sent (async and unload flushes),
+     * before the batch's telemetry is taken. The tracker uses it to attach a device info snapshot that
+     * no event carried yet to an event of the current page. It may mutate the events; the in-memory
+     * pending entries share them, so a retry on this page keeps the change. Never called for batches
+     * without events.
+     */
+    beforeEventBatchSend?: (events: Event[], reason: FlushReason) => void;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -2446,6 +2461,7 @@ declare class RequestQueue {
     private readonly requestConfig;
     private readonly onConfigReceived?;
     private readonly getDataPolicy?;
+    private readonly beforeEventBatchSend?;
     /** Current delivery policy, including live updates. */
     private config;
     /**
@@ -2545,6 +2561,8 @@ declare class RequestQueue {
      * The transport later merges in `sent`/`transport`.
      */
     private attachBatchMeta;
+    /** Run the beforeEventBatchSend hook; a throwing hook must never break a flush. */
+    private prepareEvents;
     /** The data policy code from the tracker, or undefined; a throwing getter must never break a flush. */
     private readDataPolicy;
     private getDuePending;
@@ -2621,9 +2639,8 @@ declare const CONFIG_REQUEST_HEADER = "X-Corbado-Observe-Config";
 declare const DEFAULT_FLUSH_INTERVAL_MS = 500;
 declare const DEFAULT_SEQ_LOCK_TIMEOUT_MS = 50;
 /**
- * Built-in per-field device info collection timeout. Also the timeout of the very first collection
- * of a load that booted without a cached config, since collection starts before the first server
- * response can arrive — generous enough that a slow-but-working browser API still answers.
+ * Default of the deprecated `deviceInfoCollectorTimeoutMs` config field. Only parsed for config
+ * compatibility: device info collection uses its own built-in deadlines (see `device.ts`).
  */
 declare const DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS = 1000;
 /**

package/dist/index.d.ts

@@ -560,20 +560,17 @@ interface SdkReliabilityConfig {
      */
     flushOnFlowTypeFinished: FlowType[];
     /**
-     * Per-field timeout for device info collection, in milliseconds. A field whose browser API does
-     * not answer within this budget is recorded as a `TimeoutError` in `collectionErrors` and left
-     * undefined; the remaining fields are unaffected. Defaults to 1000ms.
-     *
-     * Read at collection time, so a config that arrives mid-load applies from the next device info
-     * refresh onward. The very first collection of a load booting on the built-in defaults (nothing
-     * cached) always runs on the default.
+     * @deprecated No effect since device info is collected with built-in deadlines (a fast snapshot
+     * within 300 ms, slower fields as a later update within 6000 ms). Still parsed so older server
+     * configs keep loading; the backend keeps serving it for older SDK versions.
      */
     deviceInfoCollectorTimeoutMs: number;
     /**
-     * When true (and `telemetry` is enabled), every device info collection emits an `info` telemetry
-     * entry with the total duration and the per-field durations in milliseconds. Defaults to false:
-     * this is a diagnostic stream to switch on while investigating slow collection, not something to
-     * run permanently.
+     * When true (and `telemetry` is enabled), device info collection emits `info` telemetry entries:
+     * the fast snapshot's total and per-field durations in milliseconds, the late fields' outcome, the
+     * `privateMode` source (cache age, detection duration or timeout) and how the update was delivered
+     * (or that it was left undelivered at pagehide / destroy). Defaults to false: this is a diagnostic
+     * stream to switch on while investigating slow collection, not something to run permanently.
      */
     deviceInfoTiming: boolean;
     /** Serialize explicitly supplied raw error diagnostics. Defaults to true; refreshes apply to subsequent errors. Already queued events are unchanged. */
@@ -1589,10 +1586,9 @@ interface TrackerOptions {
     /** Minimum time between attaching cached device info to events. */
     deviceInfoDebounceTime?: number;
     /**
-     * @deprecated The device info collection timeout is server-controlled via the SDK reliability
-     * config (`deviceInfoCollectorTimeoutMs`). This option only applies as long as no server config
-     * has been received (i.e. before the first config response is cached); once a server config is
-     * cached it wins. It will be removed in a future release.
+     * @deprecated No effect: device info is collected with built-in deadlines (a fast snapshot within
+     * 300 ms, slower fields as a later update within 6000 ms). Still accepted so existing integrations
+     * keep compiling. It will be removed in a future release.
      */
     deviceInfoCollectorTimeout?: number;
     defaultTags?: Record<string, string>;
@@ -2094,6 +2090,17 @@ declare class CorbadoTracker {
     logInfo(message: string): void;
     /** Convenience wrapper for {@link CorbadoTracker.telemetry} at `error` level. */
     logError(message: string): void;
+    /**
+     * Queue hook run right before an event batch is sent: a device info snapshot that no event carried
+     * yet (typically the fast snapshot after a burst of events at page load, or the privateMode update)
+     * rides the first event of this page in the batch that has none. Events of other pages (outbox
+     * replays) are never touched, and nothing is sent just for device info. When the page goes away
+     * with a snapshot nothing could carry, that is reported (timing diagnostics only).
+     *
+     * Error situations:
+     *  - Any error: log "Failed to attach device info to batch" and send the batch unchanged
+     */
+    private attachUndeliveredDeviceInfo;
     /**
      * 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
@@ -2382,6 +2389,14 @@ interface QueueOptions {
      * none has ever been set. Read at send time so a change applies to the next batch without a flush.
      */
     getDataPolicy?: () => number | undefined;
+    /**
+     * Called with the events of every event batch right before it is sent (async and unload flushes),
+     * before the batch's telemetry is taken. The tracker uses it to attach a device info snapshot that
+     * no event carried yet to an event of the current page. It may mutate the events; the in-memory
+     * pending entries share them, so a retry on this page keeps the change. Never called for batches
+     * without events.
+     */
+    beforeEventBatchSend?: (events: Event[], reason: FlushReason) => void;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -2446,6 +2461,7 @@ declare class RequestQueue {
     private readonly requestConfig;
     private readonly onConfigReceived?;
     private readonly getDataPolicy?;
+    private readonly beforeEventBatchSend?;
     /** Current delivery policy, including live updates. */
     private config;
     /**
@@ -2545,6 +2561,8 @@ declare class RequestQueue {
      * The transport later merges in `sent`/`transport`.
      */
     private attachBatchMeta;
+    /** Run the beforeEventBatchSend hook; a throwing hook must never break a flush. */
+    private prepareEvents;
     /** The data policy code from the tracker, or undefined; a throwing getter must never break a flush. */
     private readDataPolicy;
     private getDuePending;
@@ -2621,9 +2639,8 @@ declare const CONFIG_REQUEST_HEADER = "X-Corbado-Observe-Config";
 declare const DEFAULT_FLUSH_INTERVAL_MS = 500;
 declare const DEFAULT_SEQ_LOCK_TIMEOUT_MS = 50;
 /**
- * Built-in per-field device info collection timeout. Also the timeout of the very first collection
- * of a load that booted without a cached config, since collection starts before the first server
- * response can arrive — generous enough that a slow-but-working browser API still answers.
+ * Default of the deprecated `deviceInfoCollectorTimeoutMs` config field. Only parsed for config
+ * compatibility: device info collection uses its own built-in deadlines (see `device.ts`).
  */
 declare const DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS = 1000;
 /**