@featureflare/sdk-js 0.0.84 → 0.0.86

package/README.md

@@ -62,6 +62,7 @@ const featureflare = new FeatureFlareClient({
   },
   realtime: {
     // optional: enabled defaults to true (SSE primary, polling fallback)
+    // optional: hidden tabs disconnect by default and reconnect on visibility restore
     pollingIntervalMs: 15_000,
     ssePath: '/api/v1/sdk/stream'
   }
@@ -72,6 +73,7 @@ const featureflare = new FeatureFlareClient({
 - `bool(...)` and `evaluate(...)` are outage-safe and return deterministic defaults for expected network failures.
 - Hard kill switches have highest precedence and return `false` even when the API is unreachable.
 - Realtime updates are enabled by default: SSE is primary transport; polling is used automatically as fallback when SSE is unavailable.
+- In browser runtimes, hidden tabs disconnect the realtime stream by default and reconnect with a fresh authenticated stream request when the tab becomes visible again.
 
 To explicitly disable realtime updates:
 

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 // src/index.ts
 var DEFAULT_FEATUREFLARE_API_BASE_URL = "https://api.featureflare.com";
+var DEFAULT_CACHE_TTL_MS = 30 * 60 * 1e3;
+var DEFAULT_STALE_TTL_MS = 10 * 60 * 1e3;
 function getApiBaseUrlFromEnv() {
   if (typeof process !== "undefined" && process.env) {
     return process.env.FEATUREFLARE_API_BASE_URL?.trim() || process.env.SHIPIT_API_BASE_URL?.trim() || null;
@@ -21,6 +23,54 @@ function getEnvKeyFromEnv() {
   }
   return null;
 }
+function normalizeHashInput(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeHashInput(entry));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== void 0).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    return Object.fromEntries(entries.map(([key, entryValue]) => [key, normalizeHashInput(entryValue)]));
+  }
+  return value;
+}
+function hashForStream(value) {
+  const input = JSON.stringify(normalizeHashInput(value));
+  let forward = 2166136261;
+  let backward = 2166136261;
+  for (let index = 0; index < input.length; index += 1) {
+    forward ^= input.charCodeAt(index);
+    forward = Math.imul(forward, 16777619);
+    const reverseIndex = input.length - 1 - index;
+    backward ^= input.charCodeAt(reverseIndex);
+    backward = Math.imul(backward, 16777619);
+  }
+  return `${(forward >>> 0).toString(16).padStart(8, "0")}${(backward >>> 0).toString(16).padStart(8, "0")}`;
+}
+function encodeBase64Url(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "utf8").toString("base64url");
+  }
+  const bytes = typeof TextEncoder !== "undefined" ? new TextEncoder().encode(value) : [];
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  const base64 = typeof btoa === "function" ? btoa(binary) : "";
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function buildHashedRealtimeUserContext(input) {
+  const payload = {
+    id: input.id ?? input.key
+  };
+  return {
+    payloadHash: hashForStream(payload),
+    fields: {
+      ...input.id ?? input.key ? { id: hashForStream(input.id ?? input.key) } : {}
+    },
+    metaEntries: [],
+    customEntries: []
+  };
+}
 function getSdkKeyFromEnv() {
   if (typeof process !== "undefined" && process.env) {
     return process.env.FEATUREFLARE_CLIENT_KEY?.trim() || process.env.FEATUREFLARE_SERVER_KEY?.trim() || process.env.SHIPIT_CLIENT_KEY?.trim() || process.env.SHIPIT_SERVER_KEY?.trim() || null;
@@ -33,6 +83,31 @@ function monotonicNow() {
   }
   return Date.now();
 }
+function isFeatureFlareDebugEnabled() {
+  const envDebug = typeof process !== "undefined" && process.env ? process.env.NEXT_PUBLIC_FEATUREFLARE_DEBUG?.trim() || process.env.FEATUREFLARE_DEBUG?.trim() : "";
+  if (envDebug === "1" || envDebug?.toLowerCase() === "true") {
+    return true;
+  }
+  if (typeof window !== "undefined") {
+    try {
+      const storageDebug = window.localStorage.getItem("featureflare:debug");
+      return storageDebug === "1" || storageDebug?.toLowerCase() === "true";
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function debugLog(message, details) {
+  if (!isFeatureFlareDebugEnabled()) {
+    return;
+  }
+  if (details) {
+    console.debug(`[FeatureFlare SDK] ${message}`, details);
+    return;
+  }
+  console.debug(`[FeatureFlare SDK] ${message}`);
+}
 function sleep(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
@@ -76,6 +151,7 @@ var FeatureFlareClient = class {
   projectKey;
   envKey;
   expectedEnvKey;
+  getRealtimeUser;
   timeoutMs;
   maxRetries;
   backoffMs;
@@ -100,11 +176,16 @@ var FeatureFlareClient = class {
   lastUser = null;
   lastDefaultValue = false;
   realtimeEnabled = true;
+  realtimePollingEnabled = true;
   realtimePollingMs = 15e3;
   realtimeSsePath = "/api/v1/sdk/stream";
+  realtimeDisconnectWhenHidden = true;
+  visibilityListenerAttached = false;
+  connectionState = { state: "offline", transport: "none" };
   pollTimer = null;
   reconnectTimer = null;
   eventSource = null;
+  streamConnectVersion = 0;
   constructor(options = {}) {
     this.apiBaseUrl = getApiBaseUrl(options.apiBaseUrl).replace(/\/$/, "");
     this.sdkKey = options.sdkKey?.trim() || getSdkKeyFromEnv();
@@ -112,6 +193,7 @@ var FeatureFlareClient = class {
     const explicitOrEnvKey = options.envKey?.trim() || getEnvKeyFromEnv() || null;
     this.envKey = explicitOrEnvKey ?? "production";
     this.expectedEnvKey = explicitOrEnvKey;
+    this.getRealtimeUser = options.getRealtimeUser;
     if (!this.sdkKey && !this.projectKey) {
       throw new Error(
         "FeatureFlareClient requires either sdkKey (recommended) or projectKey (legacy). Set FEATUREFLARE_CLIENT_KEY or FEATUREFLARE_SERVER_KEY env var, or pass sdkKey in options."
@@ -121,20 +203,57 @@ var FeatureFlareClient = class {
     this.maxRetries = Number.isFinite(options.maxRetries) && (options.maxRetries ?? 0) >= 0 ? Number(options.maxRetries) : 2;
     this.backoffMs = Number.isFinite(options.backoffMs) && (options.backoffMs ?? 0) > 0 ? Number(options.backoffMs) : 200;
     this.jitter = Number.isFinite(options.jitter) && (options.jitter ?? 0) >= 0 ? Number(options.jitter) : 0.25;
-    this.cacheTtlMs = Number.isFinite(options.cacheTtlMs) && (options.cacheTtlMs ?? 0) > 0 ? Number(options.cacheTtlMs) : 6e4;
-    const configuredStaleTtlMs = Number.isFinite(options.staleTtlMs) && (options.staleTtlMs ?? 0) > 0 ? Number(options.staleTtlMs) : 1e4;
+    this.cacheTtlMs = Number.isFinite(options.cacheTtlMs) && (options.cacheTtlMs ?? 0) > 0 ? Number(options.cacheTtlMs) : DEFAULT_CACHE_TTL_MS;
+    const configuredStaleTtlMs = Number.isFinite(options.staleTtlMs) && (options.staleTtlMs ?? 0) > 0 ? Number(options.staleTtlMs) : DEFAULT_STALE_TTL_MS;
     this.staleTtlMs = Math.min(configuredStaleTtlMs, this.cacheTtlMs);
     this.persistentCache = options.persistentCache;
     this.onMetric = options.onMetric;
     this.realtimeEnabled = options.realtime?.enabled ?? true;
-    this.realtimePollingMs = Number.isFinite(options.realtime?.pollingIntervalMs) && (options.realtime?.pollingIntervalMs ?? 0) > 0 ? Number(options.realtime?.pollingIntervalMs) : 15e3;
+    const configuredPollingIntervalMs = Number(options.realtime?.pollingIntervalMs ?? NaN);
+    if (Number.isFinite(configuredPollingIntervalMs) && configuredPollingIntervalMs === 0) {
+      this.realtimePollingEnabled = false;
+      this.realtimePollingMs = 0;
+    } else {
+      this.realtimePollingEnabled = true;
+      this.realtimePollingMs = Number.isFinite(configuredPollingIntervalMs) && configuredPollingIntervalMs > 0 ? configuredPollingIntervalMs : 15e3;
+    }
     this.realtimeSsePath = options.realtime?.ssePath ?? "/api/v1/sdk/stream";
+    this.realtimeDisconnectWhenHidden = options.realtime?.disconnectWhenHidden ?? true;
     this.applyBootstrap(options.bootstrap);
     this.persistentLoadPromise = this.loadPersistentCache();
     if (this.realtimeEnabled && this.sdkKey) {
+      this.attachVisibilityHandler();
+      if (this.realtimeDisconnectWhenHidden && typeof document !== "undefined" && document.visibilityState === "hidden") {
+        return;
+      }
       this.startRealtime();
     }
   }
+  handleVisibilityChange = () => {
+    if (!this.realtimeDisconnectWhenHidden || typeof document === "undefined") return;
+    debugLog("Visibility changed", {
+      visibilityState: document.visibilityState,
+      realtimeEnabled: this.realtimeEnabled,
+      hasEventSource: Boolean(this.eventSource)
+    });
+    if (document.visibilityState === "hidden") {
+      this.stopRealtime({ preserveEnabled: true });
+      return;
+    }
+    if (this.realtimeEnabled && this.sdkKey && !this.eventSource) {
+      this.connectSse(0);
+    }
+  };
+  attachVisibilityHandler() {
+    if (!this.realtimeDisconnectWhenHidden || this.visibilityListenerAttached || typeof document === "undefined") return;
+    document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    this.visibilityListenerAttached = true;
+  }
+  detachVisibilityHandler() {
+    if (!this.visibilityListenerAttached || typeof document === "undefined") return;
+    document.removeEventListener("visibilitychange", this.handleVisibilityChange);
+    this.visibilityListenerAttached = false;
+  }
   getCacheKey(flagKey) {
     return `${this.envKey}:${flagKey}`;
   }
@@ -146,20 +265,105 @@ var FeatureFlareClient = class {
       email: input.email,
       name: input.name,
       country: input.country,
-      custom: input.meta ?? input.custom
+      custom: input.meta ?? input.custom,
+      session: input.session,
+      metrics: input.metrics
     };
   }
+  resolveRealtimeUserPayload() {
+    const candidate = this.getRealtimeUser?.();
+    if (candidate) {
+      try {
+        const normalizedUser = this.normalizeUser(candidate);
+        this.lastUser = normalizedUser;
+        return candidate;
+      } catch {
+      }
+    }
+    if (!this.lastUser) {
+      return null;
+    }
+    return {
+      id: this.lastUser.key,
+      email: this.lastUser.email,
+      name: this.lastUser.name,
+      country: this.lastUser.country,
+      meta: this.lastUser.custom,
+      session: this.lastUser.session,
+      metrics: this.lastUser.metrics
+    };
+  }
+  resolveRealtimeUser() {
+    const candidate = this.resolveRealtimeUserPayload();
+    if (candidate) {
+      try {
+        const normalizedUser = this.normalizeUser(candidate);
+        this.lastUser = normalizedUser;
+        return normalizedUser;
+      } catch {
+      }
+    }
+    return this.lastUser;
+  }
+  getRealtimeStreamHashes() {
+    const realtimeUserPayload = this.resolveRealtimeUserPayload();
+    if (!realtimeUserPayload) {
+      return {};
+    }
+    const hashedContext = buildHashedRealtimeUserContext(realtimeUserPayload);
+    return {
+      userContextHash: encodeBase64Url(JSON.stringify(hashedContext)),
+      userPayloadHash: hashedContext.payloadHash
+    };
+  }
+  async fetchStreamToken() {
+    if (!this.sdkKey || typeof fetch !== "function") {
+      return null;
+    }
+    const { userContextHash, userPayloadHash } = this.getRealtimeStreamHashes();
+    try {
+      const response = await fetch(`${this.apiBaseUrl}/api/v1/sdk/stream-token`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-featureflare-sdk-key": this.sdkKey
+        },
+        body: JSON.stringify({
+          expectedEnvKey: this.expectedEnvKey ?? void 0,
+          userContextHash,
+          userPayloadHash
+        })
+      });
+      if (!response.ok) {
+        return null;
+      }
+      const payload = await response.json();
+      return typeof payload.key === "string" && payload.key.trim() ? payload.key : null;
+    } catch {
+      return null;
+    }
+  }
   emit(event, payload) {
     for (const listener of this.listeners[event]) {
       listener(payload);
     }
   }
+  emitConnectionState(state) {
+    this.connectionState = state;
+    this.emit("connectionState", state);
+  }
   on(event, listener) {
     this.listeners[event].add(listener);
+    if (event === "connectionState") {
+      listener(this.connectionState);
+    }
     return () => {
       this.listeners[event].delete(listener);
     };
   }
+  isRealtimeEnabled() {
+    return this.realtimeEnabled && Boolean(this.sdkKey);
+  }
   emitMetric(metricName, value, tags) {
     this.onMetric?.(metricName, value, tags);
   }
@@ -387,11 +591,17 @@ var FeatureFlareClient = class {
     this.emit("update", { changedKeys: [flagKey], source: "network" });
     return value;
   }
-  async fetchFlagsFromNetwork(normalizedUser, defaultValue, transport) {
+  async fetchFlagsFromNetwork(normalizedUser, defaultValue, transport, opts) {
     if (!this.sdkKey) {
       return null;
     }
     const started = monotonicNow();
+    debugLog("Fetching flags", {
+      transport,
+      fromSnapshotInvalidate: Boolean(opts?.fromSnapshotInvalidate),
+      userKey: normalizedUser.key,
+      defaultValue
+    });
     try {
       const response = await this.fetchWithRetry(
         `${this.apiBaseUrl}/api/v1/sdk/flags`,
@@ -432,7 +642,13 @@ var FeatureFlareClient = class {
         }
         this.setCacheItem(entry.key, entry.value, "network", revision);
       }
-      if (changed.size > 0) {
+      if (opts?.fromSnapshotInvalidate && list !== null) {
+        this.emit("update", {
+          changedKeys: list.map((e) => e.key),
+          source: "realtime",
+          snapshotInvalidate: true
+        });
+      } else if (changed.size > 0) {
         this.emit("update", { changedKeys: [...changed], source: "network" });
       }
       this.setCircuitState(false);
@@ -441,6 +657,12 @@ var FeatureFlareClient = class {
         env: this.envKey,
         transport
       });
+      debugLog("Fetched flags", {
+        transport,
+        fromSnapshotInvalidate: Boolean(opts?.fromSnapshotInvalidate),
+        flagsCount: list.length,
+        revision
+      });
       return list;
     } catch {
       this.emitMetric("ff_revalidate_latency_ms", monotonicNow() - started, {
@@ -448,13 +670,30 @@ var FeatureFlareClient = class {
         transport,
         result: "error"
       });
+      debugLog("Fetch flags failed", {
+        transport,
+        fromSnapshotInvalidate: Boolean(opts?.fromSnapshotInvalidate)
+      });
       return null;
     }
   }
-  revalidate(normalizedUser, defaultValue) {
+  revalidate(normalizedUser, defaultValue, opts) {
     const existing = this.inFlightRevalidate.get(this.envKey);
-    if (existing) return existing;
-    const promise = this.fetchFlagsFromNetwork(normalizedUser, defaultValue, "network").finally(() => {
+    if (existing) {
+      if (opts?.fromSnapshotInvalidate) {
+        void existing.then((list) => {
+          if (list !== null) {
+            this.emit("update", {
+              changedKeys: list.map((e) => e.key),
+              source: "realtime",
+              snapshotInvalidate: true
+            });
+          }
+        });
+      }
+      return existing;
+    }
+    const promise = this.fetchFlagsFromNetwork(normalizedUser, defaultValue, "network", opts).finally(() => {
       this.inFlightRevalidate.delete(this.envKey);
     });
     this.inFlightRevalidate.set(this.envKey, promise);
@@ -590,6 +829,11 @@ var FeatureFlareClient = class {
     const normalizedUser = this.normalizeUser(user);
     this.lastUser = normalizedUser;
     this.lastDefaultValue = defaultValue;
+    const cached = this.collectCachedFlags();
+    if (cached.length > 0) {
+      void this.revalidate(normalizedUser, defaultValue);
+      return cached;
+    }
     const list = await this.revalidate(normalizedUser, defaultValue);
     if (list && list.length > 0) {
       return list.map((entry) => ({
@@ -597,8 +841,6 @@ var FeatureFlareClient = class {
         value: this.killSwitches.has(entry.key) ? false : entry.value
       }));
     }
-    const cached = this.collectCachedFlags();
-    if (cached.length > 0) return cached;
     return [];
   }
   applyRealtimeMessage(message) {
@@ -643,9 +885,6 @@ var FeatureFlareClient = class {
         });
       }
     }
-    if (message.type === "snapshot.invalidate" && this.lastUser) {
-      void this.revalidate(this.lastUser, this.lastDefaultValue);
-    }
     const eventLagMs = Math.max(0, Date.now() - (message.timestamp ?? Date.now()));
     this.emitMetric("ff_realtime_lag_ms", eventLagMs, {
       env: this.envKey,
@@ -657,54 +896,162 @@ var FeatureFlareClient = class {
     }
   }
   startPolling(immediate = false) {
+    if (!this.realtimePollingEnabled) {
+      debugLog("Polling disabled", {
+        immediate,
+        reason: "realtimePollingEnabled=false"
+      });
+      return;
+    }
     if (this.pollTimer) {
       clearTimeout(this.pollTimer);
       this.pollTimer = null;
     }
     const tick = async () => {
-      if (!this.lastUser) {
-        this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+      if (this.eventSource) {
+        debugLog("Polling tick skipped", {
+          reason: "eventSource-active"
+        });
+        this.pollTimer = null;
+        return;
+      }
+      const realtimeUser = this.resolveRealtimeUser();
+      if (!realtimeUser) {
+        debugLog("Polling tick deferred", {
+          reason: "missing-realtime-user",
+          nextInMs: this.realtimePollingMs
+        });
+        if (!this.eventSource) {
+          this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+        }
         return;
       }
-      await this.fetchFlagsFromNetwork(this.lastUser, this.lastDefaultValue, "polling");
-      this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+      debugLog("Polling tick started", {
+        intervalMs: this.realtimePollingMs,
+        userKey: realtimeUser.key
+      });
+      await this.fetchFlagsFromNetwork(realtimeUser, this.lastDefaultValue, "polling");
+      if (!this.eventSource) {
+        this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+      } else {
+        this.pollTimer = null;
+      }
     };
     if (immediate) {
+      debugLog("Polling started immediately", {
+        intervalMs: this.realtimePollingMs
+      });
       void tick();
       return;
     }
+    debugLog("Polling scheduled", {
+      intervalMs: this.realtimePollingMs
+    });
     this.pollTimer = setTimeout(tick, this.realtimePollingMs);
   }
   connectSse(attempt = 0) {
+    void this.connectSseInternal(attempt);
+  }
+  async connectSseInternal(attempt = 0) {
     const EventSourceImpl = typeof EventSource !== "undefined" ? EventSource : null;
     if (!EventSourceImpl || !this.sdkKey) {
-      this.emit("connectionState", { state: "degraded", transport: "polling" });
-      this.startPolling(true);
+      debugLog("SSE unavailable, falling back", {
+        hasEventSourceImpl: Boolean(EventSourceImpl),
+        hasSdkKey: Boolean(this.sdkKey),
+        pollingEnabled: this.realtimePollingEnabled
+      });
+      this.emitConnectionState({ state: this.realtimePollingEnabled ? "degraded" : "offline", transport: this.realtimePollingEnabled ? "polling" : "none" });
+      if (this.realtimePollingEnabled) {
+        this.startPolling(true);
+      }
+      return;
+    }
+    const connectionVersion = ++this.streamConnectVersion;
+    const streamToken = await this.fetchStreamToken();
+    if (connectionVersion !== this.streamConnectVersion) {
       return;
     }
     const url = new URL(this.realtimeSsePath, this.apiBaseUrl);
-    url.searchParams.set("sdkKey", this.sdkKey);
-    url.searchParams.set("envKey", this.envKey);
+    if (streamToken) {
+      url.searchParams.set("key", streamToken);
+    } else {
+      url.searchParams.set("sdkKey", this.sdkKey);
+      if (this.expectedEnvKey) {
+        url.searchParams.set("envKey", this.expectedEnvKey);
+      }
+      const { userContextHash, userPayloadHash } = this.getRealtimeStreamHashes();
+      if (userContextHash) {
+        url.searchParams.set("userContextHash", userContextHash);
+      }
+      if (userPayloadHash) {
+        url.searchParams.set("userPayloadHash", userPayloadHash);
+      }
+    }
+    debugLog("Connecting SSE", {
+      attempt,
+      url: url.toString(),
+      pollingEnabled: this.realtimePollingEnabled,
+      authMode: streamToken ? "stream-token" : "sdk-key"
+    });
     this.eventSource = new EventSourceImpl(url.toString());
     this.eventSource.onopen = () => {
-      this.emit("connectionState", { state: "connected", transport: "sse" });
+      debugLog("SSE connected", {
+        attempt,
+        url: url.toString()
+      });
+      this.emitConnectionState({ state: "connected", transport: "sse" });
       if (this.pollTimer) {
         clearTimeout(this.pollTimer);
         this.pollTimer = null;
       }
     };
     this.eventSource.onmessage = (event) => {
+      if (this.connectionState.state !== "connected" || this.connectionState.transport !== "sse") {
+        debugLog("Promoting connection state to connected from SSE message", {
+          previousState: this.connectionState.state,
+          previousTransport: this.connectionState.transport
+        });
+        this.emitConnectionState({ state: "connected", transport: "sse" });
+      }
+      console.log("SSE message received", {
+        raw: String(event.data)
+      });
       try {
         const payload = JSON.parse(String(event.data));
+        if (payload.type === "snapshot.invalidate") {
+          const realtimeUser = this.resolveRealtimeUser();
+          console.log("Snapshot invalidate message received", {
+            payload
+          }, realtimeUser);
+          if (realtimeUser) {
+            console.log("Refetching flags from snapshot invalidate", {
+              userKey: realtimeUser.key,
+              defaultValue: this.lastDefaultValue
+            });
+            void this.revalidate(realtimeUser, this.lastDefaultValue, { fromSnapshotInvalidate: true });
+          } else {
+            debugLog("Snapshot invalidate ignored because no user has been evaluated yet");
+          }
+        }
         this.applyRealtimeMessage(payload);
       } catch {
       }
     };
     this.eventSource.onerror = () => {
-      this.emit("connectionState", { state: "degraded", transport: "polling" });
+      debugLog("SSE errored", {
+        attempt,
+        pollingEnabled: this.realtimePollingEnabled,
+        reconnectInMs: Math.min(this.backoffMs * (attempt + 1), 3e4)
+      });
+      this.emitConnectionState({
+        state: this.realtimePollingEnabled ? "degraded" : "offline",
+        transport: this.realtimePollingEnabled ? "polling" : "none"
+      });
       this.eventSource?.close();
       this.eventSource = null;
-      this.startPolling(true);
+      if (this.realtimePollingEnabled) {
+        this.startPolling(true);
+      }
       if (this.reconnectTimer) {
         clearTimeout(this.reconnectTimer);
       }
@@ -716,10 +1063,30 @@ var FeatureFlareClient = class {
   }
   startRealtime() {
     this.realtimeEnabled = true;
+    debugLog("Realtime start requested", {
+      disconnectWhenHidden: this.realtimeDisconnectWhenHidden,
+      visibilityState: typeof document !== "undefined" ? document.visibilityState : "unknown",
+      pollingEnabled: this.realtimePollingEnabled
+    });
+    this.attachVisibilityHandler();
+    if (this.realtimeDisconnectWhenHidden && typeof document !== "undefined" && document.visibilityState === "hidden") {
+      debugLog("Realtime start skipped because document is hidden");
+      return;
+    }
     this.connectSse(0);
   }
-  stopRealtime() {
-    this.realtimeEnabled = false;
+  stopRealtime(opts) {
+    this.streamConnectVersion += 1;
+    debugLog("Realtime stop requested", {
+      preserveEnabled: Boolean(opts?.preserveEnabled),
+      hadEventSource: Boolean(this.eventSource),
+      hadPollTimer: Boolean(this.pollTimer),
+      hadReconnectTimer: Boolean(this.reconnectTimer)
+    });
+    if (!opts?.preserveEnabled) {
+      this.realtimeEnabled = false;
+      this.detachVisibilityHandler();
+    }
     if (this.eventSource) {
       this.eventSource.close();
       this.eventSource = null;
@@ -732,7 +1099,7 @@ var FeatureFlareClient = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
-    this.emit("connectionState", { state: "offline", transport: "none" });
+    this.emitConnectionState({ state: "offline", transport: "none" });
   }
   /**
    * Report observed error metrics (error rate, latency) for a flag back to the FeatureFlare API.