feat: expose setConnectionMode on browser SDK and restrict automatic mode switching

Remove the automatic connection mode option from the browser SDK's public
interface since it has no impact. Add setConnectionMode as an EAP method
on the browser LDClient, giving users direct control over the connection
mode with higher priority than setStreaming.

Author: kinyoklion

packages/sdk/browser/src/BrowserClient.ts

@@ -7,6 +7,7 @@ import {
   Configuration,
   createDefaultSourceFactoryProvider,
   createFDv2DataManagerBase,
+  FDv2ConnectionMode,
   FlagManager,
   Hook,
   internal,
@@ -318,6 +319,10 @@ class BrowserClientImpl extends LDClientImpl {
     return this._startPromise;
   }
 
+  setConnectionMode(mode?: FDv2ConnectionMode): void {
+    this.dataManager.setConnectionMode?.(mode);
+  }
+
   setStreaming(streaming?: boolean): void {
     this.dataManager.setForcedStreaming?.(streaming);
   }
@@ -376,6 +381,7 @@ export function makeClient(
     on: (key: LDEmitterEventName, callback: (...args: any[]) => void) => impl.on(key, callback),
     off: (key: LDEmitterEventName, callback: (...args: any[]) => void) => impl.off(key, callback),
     flush: () => impl.flush(),
+    setConnectionMode: (mode?: FDv2ConnectionMode) => impl.setConnectionMode(mode),
     setStreaming: (streaming?: boolean) => impl.setStreaming(streaming),
     identify: (pristineContext: LDContext, identifyOptions?: LDIdentifyOptions) =>
       impl.identifyResult(pristineContext, identifyOptions),

packages/sdk/browser/src/LDClient.ts

@@ -1,4 +1,5 @@
 import {
+  FDv2ConnectionMode,
   LDClient as CommonClient,
   LDContext,
   LDIdentifyResult,
@@ -34,15 +35,34 @@ export interface LDStartOptions extends LDWaitForInitializationOptions {
 
 export type LDClient = Omit<
   CommonClient,
-  'setConnectionMode' | 'getConnectionMode' | 'getOffline' | 'identify'
+  'getConnectionMode' | 'getOffline' | 'identify'
 > & {
   /**
    * @ignore
-   * Implementation Note: We are not supporting dynamically setting the connection mode on the LDClient.
    * Implementation Note: The SDK does not support offline mode. Instead bootstrap data can be used.
    * Implementation Note: The browser SDK has different identify options, so omits the base implementation
    * from the interface.
    */
+  /**
+   * Sets the connection mode for the SDK's data system.
+   *
+   * When set, this mode is used exclusively, overriding all automatic mode
+   * selection (including {@link setStreaming}). The {@link setStreaming} state
+   * is not modified -- {@link setConnectionMode} acts as a higher-priority
+   * override.
+   *
+   * Pass `undefined` (or call with no arguments) to clear the override and
+   * return to automatic mode selection.
+   *
+   * This method is not stable, and not subject to any backwards compatibility
+   * guarantees or semantic versioning. It is in early access. If you want access
+   * to this feature please join the EAP.
+   * https://launchdarkly.com/docs/sdk/features/data-saving-mode
+   *
+   * @param mode The connection mode to use, or `undefined` to clear the override.
+   */
+  setConnectionMode(mode?: FDv2ConnectionMode): void;
+
   /**
    * Specifies whether or not to open a streaming connection to LaunchDarkly for live flag updates.
    *

packages/sdk/browser/src/index.ts

@@ -18,6 +18,7 @@ import { BrowserOptions as LDOptions } from './options';
 
 export * from './common';
 export type { LDClient, LDOptions, LDStartOptions };
+export type { BrowserDataSystemOptions } from './options';
 export type { LDPlugin } from './LDPlugin';
 
 /**

packages/sdk/browser/src/options.ts

@@ -1,6 +1,8 @@
 import {
+  LDClientDataSystemOptions,
   LDLogger,
   LDOptions as LDOptionsBase,
+  ManualModeSwitching,
   OptionMessages,
   TypeValidator,
   TypeValidators,
@@ -10,10 +12,39 @@ import { LDPlugin } from './LDPlugin';
 
 const DEFAULT_FLUSH_INTERVAL_SECONDS = 2;
 
+/**
+ * Data system options for the browser SDK.
+ *
+ * The browser SDK does not support automatic mode switching (lifecycle or
+ * network-based). Use `false` (the default) to disable automatic switching,
+ * or {@link ManualModeSwitching} to specify an explicit initial connection mode.
+ *
+ * This interface is not stable, and not subject to any backwards compatibility
+ * guarantees or semantic versioning. It is in early access. If you want access
+ * to this feature please join the EAP.
+ * https://launchdarkly.com/docs/sdk/features/data-saving-mode
+ */
+export interface BrowserDataSystemOptions
+  extends Omit<LDClientDataSystemOptions, 'automaticModeSwitching'> {
+  automaticModeSwitching?: false | ManualModeSwitching;
+}
+
 /**
  * Initialization options for the LaunchDarkly browser SDK.
  */
 export interface BrowserOptions extends Omit<LDOptionsBase, 'initialConnectionMode'> {
+  /**
+   * @internal
+   *
+   * Configuration for the FDv2 data system. When present, the SDK uses
+   * the FDv2 protocol for flag delivery instead of the default FDv1
+   * protocol.
+   *
+   * The browser SDK restricts `automaticModeSwitching` to `false` or
+   * {@link ManualModeSwitching} only — automatic switching has no effect
+   * in browser environments.
+   */
+  dataSystem?: BrowserDataSystemOptions;
   /**
    * Whether the client should make a request to LaunchDarkly for Experimentation metrics (goals).
    *

packages/shared/sdk-client/src/DataManager.ts

@@ -10,6 +10,7 @@ import {
   subsystem,
 } from '@launchdarkly/js-sdk-common';
 
+import type FDv2ConnectionMode from './api/datasource/FDv2ConnectionMode';
 import { LDIdentifyOptions } from './api/LDIdentifyOptions';
 import { Configuration } from './configuration/Configuration';
 import {
@@ -73,6 +74,15 @@ export interface DataManager {
    */
   setAutomaticStreamingState?(streaming: boolean): void;
 
+  /**
+   * Set an explicit connection mode override. When set, only this mode is
+   * used, bypassing all automatic behavior. Pass undefined to clear the
+   * override.
+   *
+   * Optional — only FDv2 data managers implement this.
+   */
+  setConnectionMode?(mode?: FDv2ConnectionMode): void;
+
   /**
    * Set a callback to flush pending analytics events. Called immediately
    * (not debounced) when the lifecycle transitions to background.