@corbado/observe 0.5.0 → 0.5.2-next.41-054d51c

package/dist/index.d.mts

@@ -605,6 +605,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;
@@ -615,8 +617,12 @@ declare class CorbadoTracker {
     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;
+    /**
+     * Reliability config for this load. A boot with a cached server config is a snapshot (immutable
+     * mid-load); a boot on the built-in defaults upgrades once to the first server-returned config
+     * (see {@link handleConfig}).
+     */
+    private config;
     private deviceInfoCollector;
     private deviceInfoDebounceTime;
     private deviceInfoTransmittedLastTime;
@@ -625,9 +631,11 @@ declare class CorbadoTracker {
     private experiments;
     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}.
+     * Cache fresh server config as last-known so the next page load boots with it. When this load
+     * booted on the built-in defaults (no cached config), the config is additionally applied live:
+     * every field is read at use time, and a mid-load `sessionContinuity` flip is safe because
+     * `nextSeq` adopts the in-memory session id into the empty continuity store instead of minting
+     * (no session split). A load that booted on a cached config keeps its snapshot untouched.
      */
     private handleConfig;
     /**
@@ -670,6 +678,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
@@ -685,7 +694,9 @@ declare class CorbadoTracker {
      * 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).
+     * reload). An empty store while this load already has a session id means persistence is failing
+     * (or was cleared); the in-memory id is reused then — never re-minted — so a broken store degrades
+     * to one session per page load instead of one session per event.
      */
     private nextSeq;
     private updateDeviceDebounced;
@@ -1009,9 +1020,10 @@ interface QueueOptions {
     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.
+     * Reliability config for this page load; defaults to all-features-OFF. Boot-snapshot model: with
+     * a cached config the queue never changes its behavior mid-load — a fresh config returned by the
+     * server is only handed to {@link QueueOptions.onConfigReceived} for caching and applies on the
+     * next load. Only a defaults boot (no cached config) applies the first server config live.
      */
     config?: SdkReliabilityConfig;
     /** Called when the server returns a fresh config, so the client can cache it for the next load. */
@@ -1060,9 +1072,14 @@ declare class RequestQueue {
     private readonly debug;
     private readonly requestConfig;
     private readonly onConfigReceived?;
-    private readonly config;
+    /**
+     * Reliability config for this load. A boot with a cached server config is a snapshot that never
+     * changes mid-load; a boot on the built-in defaults upgrades once to the first server-returned
+     * config (see {@link handleConfigResponse}).
+     */
+    private config;
     /** Event names that trigger an immediate flush at enqueue time (config.flushOnEventNames). */
-    private readonly priorityNames;
+    private priorityNames;
     private store?;
     /**
      * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
@@ -1104,11 +1121,20 @@ declare class RequestQueue {
     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.
+     * Handle the server's answer to the config request. With a cached boot config the boot-snapshot
+     * model applies: a fresh config is ONLY handed to `onConfigReceived` for caching and takes effect
+     * on the next load. A load that booted on the built-in defaults (nothing cached) has no prior
+     * behavior to stay coherent with — there the first server config is additionally applied live,
+     * so cold-storage visits (first visit, cleared storage) don't run their whole load without the
+     * reliability features.
      */
     private handleConfigResponse;
+    /**
+     * Switch this load from the built-in defaults to the first server config (defaults boot only).
+     * Most fields are read at use time, so replacing the reference is enough; only the derived state
+     * (priority-name set, durable outbox store) needs rebuilding.
+     */
+    private applyConfigLive;
     /** Returns true when the batch was acknowledged with a 2xx (safe to keep draining). */
     private handleSendResult;
     private isRetryable;
@@ -1186,9 +1212,10 @@ declare const CONFIG_BOUNDS: {
 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.
+ * fetch-keepalive flusher until the server returns config, which is cached as last-known for the
+ * next load AND applied live to the current load (a defaults boot has no prior config to stay
+ * coherent with; loads booting on a cached config keep their snapshot — boot-snapshot model). The
+ * empty version means "nothing cached"; the config request header sends "1" in that case.
  */
 declare const DEFAULT_RELIABILITY_CONFIG: SdkReliabilityConfig;
 /**

package/dist/index.d.ts

@@ -605,6 +605,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;
@@ -615,8 +617,12 @@ declare class CorbadoTracker {
     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;
+    /**
+     * Reliability config for this load. A boot with a cached server config is a snapshot (immutable
+     * mid-load); a boot on the built-in defaults upgrades once to the first server-returned config
+     * (see {@link handleConfig}).
+     */
+    private config;
     private deviceInfoCollector;
     private deviceInfoDebounceTime;
     private deviceInfoTransmittedLastTime;
@@ -625,9 +631,11 @@ declare class CorbadoTracker {
     private experiments;
     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}.
+     * Cache fresh server config as last-known so the next page load boots with it. When this load
+     * booted on the built-in defaults (no cached config), the config is additionally applied live:
+     * every field is read at use time, and a mid-load `sessionContinuity` flip is safe because
+     * `nextSeq` adopts the in-memory session id into the empty continuity store instead of minting
+     * (no session split). A load that booted on a cached config keeps its snapshot untouched.
      */
     private handleConfig;
     /**
@@ -670,6 +678,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
@@ -685,7 +694,9 @@ declare class CorbadoTracker {
      * 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).
+     * reload). An empty store while this load already has a session id means persistence is failing
+     * (or was cleared); the in-memory id is reused then — never re-minted — so a broken store degrades
+     * to one session per page load instead of one session per event.
      */
     private nextSeq;
     private updateDeviceDebounced;
@@ -1009,9 +1020,10 @@ interface QueueOptions {
     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.
+     * Reliability config for this page load; defaults to all-features-OFF. Boot-snapshot model: with
+     * a cached config the queue never changes its behavior mid-load — a fresh config returned by the
+     * server is only handed to {@link QueueOptions.onConfigReceived} for caching and applies on the
+     * next load. Only a defaults boot (no cached config) applies the first server config live.
      */
     config?: SdkReliabilityConfig;
     /** Called when the server returns a fresh config, so the client can cache it for the next load. */
@@ -1060,9 +1072,14 @@ declare class RequestQueue {
     private readonly debug;
     private readonly requestConfig;
     private readonly onConfigReceived?;
-    private readonly config;
+    /**
+     * Reliability config for this load. A boot with a cached server config is a snapshot that never
+     * changes mid-load; a boot on the built-in defaults upgrades once to the first server-returned
+     * config (see {@link handleConfigResponse}).
+     */
+    private config;
     /** Event names that trigger an immediate flush at enqueue time (config.flushOnEventNames). */
-    private readonly priorityNames;
+    private priorityNames;
     private store?;
     /**
      * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
@@ -1104,11 +1121,20 @@ declare class RequestQueue {
     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.
+     * Handle the server's answer to the config request. With a cached boot config the boot-snapshot
+     * model applies: a fresh config is ONLY handed to `onConfigReceived` for caching and takes effect
+     * on the next load. A load that booted on the built-in defaults (nothing cached) has no prior
+     * behavior to stay coherent with — there the first server config is additionally applied live,
+     * so cold-storage visits (first visit, cleared storage) don't run their whole load without the
+     * reliability features.
      */
     private handleConfigResponse;
+    /**
+     * Switch this load from the built-in defaults to the first server config (defaults boot only).
+     * Most fields are read at use time, so replacing the reference is enough; only the derived state
+     * (priority-name set, durable outbox store) needs rebuilding.
+     */
+    private applyConfigLive;
     /** Returns true when the batch was acknowledged with a 2xx (safe to keep draining). */
     private handleSendResult;
     private isRetryable;
@@ -1186,9 +1212,10 @@ declare const CONFIG_BOUNDS: {
 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.
+ * fetch-keepalive flusher until the server returns config, which is cached as last-known for the
+ * next load AND applied live to the current load (a defaults boot has no prior config to stay
+ * coherent with; loads booting on a cached config keep their snapshot — boot-snapshot model). The
+ * empty version means "nothing cached"; the config request header sends "1" in that case.
  */
 declare const DEFAULT_RELIABILITY_CONFIG: SdkReliabilityConfig;
 /**