@launchdarkly/js-client-sdk-common 1.23.0 → 1.25.0

package/dist/cjs/index.cjs

@@ -293,10 +293,18 @@ function validateOptions(input, validatorMap, defaults, logger, prefix) {
  * Creates a validator for nested objects. When used in a validator map,
  * `validateOptions` will recursively validate the nested object's properties.
  * Defaults for nested fields are passed through from the parent.
+ *
+ * @param validators - Validator map for the nested object's fields.
+ * @param options - Optional configuration.
+ * @param options.defaults - Built-in defaults for nested fields.
+ * @param options.is - Custom `is` predicate. When provided, replaces the
+ *   default "is object" check. Use this to discriminate between object shapes
+ *   in an `anyOf` (e.g., matching on a `type` discriminant field).
  */
-function validatorOf(validators, builtInDefaults) {
+function validatorOf(validators, options) {
+    const builtInDefaults = options?.defaults;
     return {
-        is: (u) => jsSdkCommon.TypeValidators.Object.is(u),
+        is: options?.is ?? ((u) => jsSdkCommon.TypeValidators.Object.is(u)),
         getType: () => 'object',
         validate(value, name, logger, defaults) {
             if (!jsSdkCommon.TypeValidators.Object.is(value)) {
@@ -404,6 +412,10 @@ function anyOf(...validators) {
  *
  * @param keyValidator - Validates that each key is an allowed value.
  * @param valueValidator - Validates each value in the record.
+ * @param options - Optional configuration.
+ * @param options.defaults - Built-in defaults for the record entries. When
+ *   provided, takes priority over defaults passed from the parent at
+ *   validation time (same precedence as {@link validatorOf}).
  *
  * @example
  * ```ts
@@ -415,7 +427,8 @@ function anyOf(...validators) {
  * )
  * ```
  */
-function recordOf(keyValidator, valueValidator) {
+function recordOf(keyValidator, valueValidator, options) {
+    const builtInDefaults = options?.defaults;
     return {
         is: (u) => jsSdkCommon.TypeValidators.Object.is(u),
         getType: () => 'object',
@@ -440,14 +453,14 @@ function recordOf(keyValidator, valueValidator) {
                     logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, keyValidator.getType(), key));
                 }
             });
-            const recordDefaults = jsSdkCommon.TypeValidators.Object.is(defaults)
-                ? defaults
-                : {};
+            const recordDefaults = builtInDefaults ??
+                (jsSdkCommon.TypeValidators.Object.is(defaults) ? defaults : {});
             return { value: validateOptions(filtered, validatorMap, recordDefaults, logger, name) };
         },
     };
 }
 
+const DEFAULT_FDV1_FALLBACK_POLL_INTERVAL_SECONDS = 300;
 const BACKGROUND_POLL_INTERVAL_SECONDS = 3600;
 const dataSourceTypeValidator = jsSdkCommon.TypeValidators.oneOf('cache', 'polling', 'streaming');
 const connectionModeValidator = jsSdkCommon.TypeValidators.oneOf('streaming', 'polling', 'offline', 'one-shot', 'background');
@@ -477,19 +490,25 @@ const synchronizerEntryArrayValidator = arrayOf('type', {
     polling: pollingEntryValidators,
     streaming: streamingEntryValidators,
 });
+const fdv1FallbackValidators = {
+    pollInterval: jsSdkCommon.TypeValidators.numberWithMin(30),
+    endpoints: validatorOf(endpointValidators),
+};
 const modeDefinitionValidators = {
     initializers: initializerEntryArrayValidator,
     synchronizers: synchronizerEntryArrayValidator,
+    fdv1Fallback: validatorOf(fdv1FallbackValidators),
 };
-const connectionModesValidator = recordOf(connectionModeValidator, validatorOf(modeDefinitionValidators));
 const MODE_TABLE = {
     streaming: {
         initializers: [{ type: 'cache' }, { type: 'polling' }],
         synchronizers: [{ type: 'streaming' }, { type: 'polling' }],
+        fdv1Fallback: { pollInterval: DEFAULT_FDV1_FALLBACK_POLL_INTERVAL_SECONDS },
     },
     polling: {
         initializers: [{ type: 'cache' }],
         synchronizers: [{ type: 'polling' }],
+        fdv1Fallback: { pollInterval: DEFAULT_FDV1_FALLBACK_POLL_INTERVAL_SECONDS },
     },
     offline: {
         initializers: [{ type: 'cache' }],
@@ -502,24 +521,33 @@ const MODE_TABLE = {
     background: {
         initializers: [{ type: 'cache' }],
         synchronizers: [{ type: 'polling', pollInterval: BACKGROUND_POLL_INTERVAL_SECONDS }],
+        fdv1Fallback: { pollInterval: BACKGROUND_POLL_INTERVAL_SECONDS },
     },
 };
+const connectionModesValidator = recordOf(connectionModeValidator, validatorOf(modeDefinitionValidators));
 
-const modeSwitchingValidators = {
+function hasType(u, type) {
+    return jsSdkCommon.TypeValidators.Object.is(u) && u.type === type;
+}
+const automaticModeValidators = {
+    type: jsSdkCommon.TypeValidators.oneOf('automatic'),
     lifecycle: jsSdkCommon.TypeValidators.Boolean,
     network: jsSdkCommon.TypeValidators.Boolean,
 };
-const dataSystemValidators = {
+const manualModeValidators = {
+    type: jsSdkCommon.TypeValidators.oneOf('manual'),
     initialConnectionMode: connectionModeValidator,
+};
+const dataSystemValidators = {
     backgroundConnectionMode: connectionModeValidator,
-    automaticModeSwitching: anyOf(jsSdkCommon.TypeValidators.Boolean, validatorOf(modeSwitchingValidators)),
+    automaticModeSwitching: anyOf(jsSdkCommon.TypeValidators.Boolean, validatorOf(automaticModeValidators, { is: (u) => hasType(u, 'automatic') }), validatorOf(manualModeValidators, { is: (u) => hasType(u, 'manual') })),
     connectionModes: connectionModesValidator,
 };
 /**
  * Default FDv2 data system configuration for browser SDKs.
  */
 const BROWSER_DATA_SYSTEM_DEFAULTS = {
-    initialConnectionMode: 'one-shot',
+    foregroundConnectionMode: 'one-shot',
     backgroundConnectionMode: undefined,
     automaticModeSwitching: false,
 };
@@ -527,7 +555,7 @@ const BROWSER_DATA_SYSTEM_DEFAULTS = {
  * Default FDv2 data system configuration for mobile (React Native) SDKs.
  */
 const MOBILE_DATA_SYSTEM_DEFAULTS = {
-    initialConnectionMode: 'streaming',
+    foregroundConnectionMode: 'streaming',
     backgroundConnectionMode: 'background',
     automaticModeSwitching: true,
 };
@@ -535,10 +563,24 @@ const MOBILE_DATA_SYSTEM_DEFAULTS = {
  * Default FDv2 data system configuration for desktop SDKs (Electron, etc.).
  */
 const DESKTOP_DATA_SYSTEM_DEFAULTS = {
-    initialConnectionMode: 'streaming',
+    foregroundConnectionMode: 'streaming',
     backgroundConnectionMode: undefined,
     automaticModeSwitching: false,
 };
+function isManualModeSwitching(value) {
+    return typeof value === 'object' && value !== null && 'type' in value && value.type === 'manual';
+}
+/**
+ * Resolve the foreground connection mode from a validated data system config
+ * and platform defaults. Uses the mode from `ManualModeSwitching` when present,
+ * otherwise falls back to the platform default.
+ */
+function resolveForegroundMode(dataSystem, defaults) {
+    if (isManualModeSwitching(dataSystem.automaticModeSwitching)) {
+        return dataSystem.automaticModeSwitching.initialConnectionMode;
+    }
+    return dataSystem.foregroundConnectionMode ?? defaults.foregroundConnectionMode;
+}
 
 function createValidators(options) {
     return {
@@ -568,7 +610,12 @@ function createValidators(options) {
         inspectors: jsSdkCommon.TypeValidators.createTypeArray('LDInspection', {}),
         cleanOldPersistentData: jsSdkCommon.TypeValidators.Boolean,
         dataSystem: options?.dataSystemDefaults
-            ? validatorOf(dataSystemValidators, options.dataSystemDefaults)
+            ? validatorOf(dataSystemValidators, {
+                defaults: {
+                    ...options.dataSystemDefaults,
+                    connectionModes: MODE_TABLE,
+                },
+            })
             : jsSdkCommon.TypeValidators.Object,
     };
 }
@@ -970,6 +1017,46 @@ class EventFactory extends jsSdkCommon.internal.EventFactoryBase {
     }
 }
 
+function readFlagsFromBootstrap(logger, data) {
+    // If the bootstrap data came from an older server-side SDK, we'll have just a map of keys to values.
+    // Newer SDKs that have an allFlagsState method will provide an extra "$flagsState" key that contains
+    // the rest of the metadata we want. We do it this way for backward compatibility with older JS SDKs.
+    const keys = Object.keys(data);
+    const metadataKey = '$flagsState';
+    const validKey = '$valid';
+    const metadata = data[metadataKey];
+    if (!metadata && keys.length) {
+        logger.warn('LaunchDarkly client was initialized with bootstrap data that did not include flag' +
+            ' metadata. Events may not be sent correctly.');
+    }
+    if (data[validKey] === false) {
+        logger.warn('LaunchDarkly bootstrap data is not available because the back end could not read the flags.');
+    }
+    const ret = {};
+    keys.forEach((key) => {
+        if (key !== metadataKey && key !== validKey) {
+            let flag;
+            if (metadata && metadata[key]) {
+                flag = {
+                    value: data[key],
+                    ...metadata[key],
+                };
+            }
+            else {
+                flag = {
+                    value: data[key],
+                    version: 0,
+                };
+            }
+            ret[key] = {
+                version: flag.version,
+                flag,
+            };
+        }
+    });
+    return ret;
+}
+
 /**
  * Suffix appended to context storage keys to form the freshness storage key.
  */
@@ -1898,6 +1985,10 @@ class LDClientImpl {
         this._eventFactoryWithReasons = new EventFactory(true);
         this._eventSendingEnabled = false;
         this._identifyQueue = createAsyncTaskQueue();
+        // NOTE: this is used to ease the transition to the new initialization pattern.
+        // All client SDKs should set this to true with the exception of React Native which is
+        // still using the deprecated construct + identify pattern.
+        this._requiresStart = false;
         if (!sdkKey) {
             throw new Error('You must configure the client with a client-side SDK key');
         }
@@ -1906,6 +1997,8 @@ class LDClientImpl {
         }
         this._config = new ConfigurationImpl(options, internalOptions);
         this.logger = this._config.logger;
+        this._requiresStart = internalOptions?.requiresStart ?? false;
+        this.initialContext = internalOptions?.initialContext;
         this._baseHeaders = jsSdkCommon.defaultHeaders(this.sdkKey, this.platform.info, this._config.tags, this._config.serviceEndpoints.includeAuthorizationHeader, this._config.userAgentHeaderName);
         this._flagManager = new DefaultFlagManager(this.platform, sdkKey, this._config.maxCachedContexts, this._config.disableCache ?? false, this._config.logger);
         this._diagnosticsManager = createDiagnosticsManager(sdkKey, this._config, platform);
@@ -1923,6 +2016,8 @@ class LDClientImpl {
             });
         });
         this.dataManager = dataManagerFactory(this._flagManager, this._config, this._baseHeaders, this.emitter, this._diagnosticsManager);
+        this.isFDv2 = !!this._config.dataSystem;
+        this.dataSystemConfig = this._config.dataSystem;
         const hooks = [...this._config.hooks];
         this.environmentMetadata = createPluginEnvironmentMetadata(this.sdkKey, this.platform, this._config);
         this._config.getImplementationHooks(this.environmentMetadata).forEach((hook) => {
@@ -2000,6 +2095,57 @@ class LDClientImpl {
     presetFlags(newFlags) {
         this._flagManager.presetFlags(newFlags);
     }
+    /**
+     * Starts the client and returns a promise that resolves to the initialization result.
+     *
+     * This method is idempotent - calling it multiple times returns the same promise.
+     *
+     * @param options Optional configuration. See {@link LDStartOptions}.
+     * @returns A promise that resolves to the initialization result.
+     */
+    start(options) {
+        if (this.initializeResult) {
+            return Promise.resolve(this.initializeResult);
+        }
+        if (this.startPromise) {
+            return this.startPromise;
+        }
+        if (!this.initialContext) {
+            this.logger.error('Initial context not set');
+            return Promise.resolve({ status: 'failed', error: new Error('Initial context not set') });
+        }
+        const identifyOptions = {
+            ...(options?.identifyOptions ?? {}),
+            // Initial identify operations are not sheddable.
+            sheddable: false,
+        };
+        // If the bootstrap data is provided in the start options, and the identify options do not
+        // have bootstrap data, then use the bootstrap data from the start options.
+        if (options?.bootstrap && !identifyOptions.bootstrap) {
+            identifyOptions.bootstrap = options.bootstrap;
+        }
+        if (identifyOptions.bootstrap) {
+            try {
+                if (!identifyOptions.bootstrapParsed) {
+                    identifyOptions.bootstrapParsed = readFlagsFromBootstrap(this.logger, identifyOptions.bootstrap);
+                }
+                if (identifyOptions.bootstrapParsed) {
+                    this.presetFlags(identifyOptions.bootstrapParsed);
+                }
+            }
+            catch (error) {
+                this.logger.error('Failed to bootstrap data', error);
+            }
+        }
+        if (!this.initializedPromise) {
+            this.initializedPromise = new Promise((resolve) => {
+                this.initResolve = resolve;
+            });
+        }
+        this.startPromise = this._promiseWithTimeout(this.initializedPromise, options?.timeout ?? 5, 'start');
+        this.identifyResult(this.initialContext, identifyOptions);
+        return this.startPromise;
+    }
     /**
      * Identifies a context to LaunchDarkly. See {@link LDClient.identify}.
      *
@@ -2037,6 +2183,10 @@ class LDClientImpl {
         // If completed or shed, then we are done.
     }
     async identifyResult(pristineContext, identifyOptions) {
+        if (this._requiresStart && !this.startPromise) {
+            this.logger.error('The client must be started before a context can be identified. Call start() prior to identifying a context.');
+            return { status: 'error', error: new Error('Identify called before start') };
+        }
         const identifyTimeout = identifyOptions?.timeout ?? DEFAULT_IDENTIFY_TIMEOUT_SECONDS;
         const noTimeout = identifyOptions?.timeout === undefined && identifyOptions?.noTimeout === true;
         // When noTimeout is specified, and a timeout is not specified, then this condition cannot
@@ -2146,7 +2296,7 @@ class LDClientImpl {
         // If waitForInitialization was previously called, then return the promise with a timeout.
         // This condition should only be triggered if waitForInitialization was called multiple times.
         if (this.initializedPromise) {
-            return this.promiseWithTimeout(this.initializedPromise, timeout);
+            return this._promiseWithTimeout(this.initializedPromise, timeout);
         }
         // Create a new promise for tracking initialization
         if (!this.initializedPromise) {
@@ -2154,22 +2304,18 @@ class LDClientImpl {
                 this.initResolve = resolve;
             });
         }
-        return this.promiseWithTimeout(this.initializedPromise, timeout);
+        return this._promiseWithTimeout(this.initializedPromise, timeout);
     }
     /**
-     * Apply a timeout promise to a base promise. This is for use with waitForInitialization.
+     * Apply a timeout promise to a base promise. This is for use with waitForInitialization
+     * and start.
      *
      * @param basePromise The promise to race against a timeout.
      * @param timeout The timeout in seconds.
      * @returns A promise that resolves to the initialization result or timeout.
-     *
-     * @privateRemarks
-     * This method is protected because it is used by the browser SDK's `start` method.
-     * Eventually, the start method will be moved to this common implementation and this method will
-     * be made private.
      */
-    promiseWithTimeout(basePromise, timeout) {
-        const cancelableTimeout = jsSdkCommon.cancelableTimedPromise(timeout, 'waitForInitialization');
+    _promiseWithTimeout(basePromise, timeout, label = 'waitForInitialization') {
+        const cancelableTimeout = jsSdkCommon.cancelableTimedPromise(timeout, label);
         return Promise.race([
             basePromise.then((res) => {
                 cancelableTimeout.cancel();
@@ -2399,46 +2545,6 @@ function safeRegisterDebugOverridePlugins(logger, debugOverride, plugins) {
     });
 }
 
-function readFlagsFromBootstrap(logger, data) {
-    // If the bootstrap data came from an older server-side SDK, we'll have just a map of keys to values.
-    // Newer SDKs that have an allFlagsState method will provide an extra "$flagsState" key that contains
-    // the rest of the metadata we want. We do it this way for backward compatibility with older JS SDKs.
-    const keys = Object.keys(data);
-    const metadataKey = '$flagsState';
-    const validKey = '$valid';
-    const metadata = data[metadataKey];
-    if (!metadata && keys.length) {
-        logger.warn('LaunchDarkly client was initialized with bootstrap data that did not include flag' +
-            ' metadata. Events may not be sent correctly.');
-    }
-    if (data[validKey] === false) {
-        logger.warn('LaunchDarkly bootstrap data is not available because the back end could not read the flags.');
-    }
-    const ret = {};
-    keys.forEach((key) => {
-        if (key !== metadataKey && key !== validKey) {
-            let flag;
-            if (metadata && metadata[key]) {
-                flag = {
-                    value: data[key],
-                    ...metadata[key],
-                };
-            }
-            else {
-                flag = {
-                    value: data[key],
-                    version: 0,
-                };
-            }
-            ret[key] = {
-                version: flag.version,
-                flag,
-            };
-        }
-    });
-    return ret;
-}
-
 /**
  * Creates endpoint paths for browser (client-side ID) FDv1 evaluation.
  *
@@ -3161,12 +3267,12 @@ async function loadFromCache(config) {
     const { storage, crypto, environmentNamespace, context, logger } = config;
     if (!storage) {
         logger?.debug('No storage available for cache initializer');
-        return interrupted(errorInfoFromUnknown('No storage available'), false);
+        return changeSet({ version: 0, type: 'none', updates: [] }, false);
     }
     const cached = await loadCachedFlags(storage, crypto, environmentNamespace, context, logger);
     if (!cached) {
         logger?.debug('Cache miss for context');
-        return interrupted(errorInfoFromUnknown('Cache miss'), false);
+        return changeSet({ version: 0, type: 'none', updates: [] }, false);
     }
     const updates = Object.entries(cached.flags).map(([key, flag]) => ({
         kind: 'flag-eval',
@@ -3175,7 +3281,6 @@ async function loadFromCache(config) {
         object: flagToEvaluationResult(flag),
     }));
     const payload = {
-        id: 'cache',
         version: 0,
         // No `state` field. The orchestrator sees a changeSet without a selector,
         // records dataReceived=true, and continues to the next initializer.
@@ -3279,6 +3384,51 @@ function makeFDv2Requestor(plainContextString, serviceEndpoints, paths, requests
 function processFlagEval(object) {
     return object;
 }
+/**
+ * Converts an FDv2 {@link internal.Update} with `kind: 'flag-eval'` into an
+ * {@link ItemDescriptor} suitable for {@link FlagManager}.
+ *
+ * For put updates the envelope `version` is used as the {@link ItemDescriptor.version}
+ * and as {@link Flag.version}. The rest of the fields are spread from the
+ * {@link FlagEvaluationResult} object.
+ *
+ * For delete updates a tombstone descriptor is created with `deleted: true`.
+ */
+function flagEvalUpdateToItemDescriptor(update) {
+    if (update.deleted) {
+        return {
+            version: update.version,
+            flag: {
+                version: update.version,
+                deleted: true,
+                value: undefined,
+                trackEvents: false,
+            },
+        };
+    }
+    const evalResult = update.object;
+    return {
+        version: update.version,
+        flag: {
+            ...evalResult,
+            version: update.version,
+        },
+    };
+}
+/**
+ * Converts an array of FDv2 payload updates into a map of flag key to
+ * {@link ItemDescriptor}. Only `flag-eval` kind updates are processed;
+ * unrecognized kinds are silently ignored.
+ */
+function flagEvalPayloadToItemDescriptors(updates) {
+    const descriptors = {};
+    updates.forEach((update) => {
+        if (update.kind === 'flag-eval') {
+            descriptors[update.key] = flagEvalUpdateToItemDescriptor(update);
+        }
+    });
+    return descriptors;
+}
 
 function getFallback(headers) {
     const value = headers.get('x-ld-fd-fallback');
@@ -3295,7 +3445,7 @@ function getEnvironmentId(headers) {
  * it only forwards payloads and actionable errors. For polling results,
  * we need full control over all protocol action types.
  */
-function processEvents(events, oneShot, fdv1Fallback, environmentId, logger) {
+function processEvents(events, fdv1Fallback, environmentId, logger) {
     const handler = jsSdkCommon.internal.createProtocolHandler({
         'flag-eval': processFlagEval,
     }, logger);
@@ -3315,9 +3465,7 @@ function processEvents(events, oneShot, fdv1Fallback, environmentId, logger) {
             case 'serverError': {
                 const errorInfo = errorInfoFromUnknown(action.reason);
                 logger?.error(`Server error during polling: ${action.reason}`);
-                earlyResult = oneShot
-                    ? terminalError(errorInfo, fdv1Fallback)
-                    : interrupted(errorInfo, fdv1Fallback);
+                earlyResult = interrupted(errorInfo, fdv1Fallback);
                 break;
             }
             case 'error': {
@@ -3325,9 +3473,7 @@ function processEvents(events, oneShot, fdv1Fallback, environmentId, logger) {
                 if (action.kind === 'MISSING_PAYLOAD' || action.kind === 'PROTOCOL_ERROR') {
                     const errorInfo = errorInfoFromInvalidData(action.message);
                     logger?.warn(`Protocol error during polling: ${action.message}`);
-                    earlyResult = oneShot
-                        ? terminalError(errorInfo, fdv1Fallback)
-                        : interrupted(errorInfo, fdv1Fallback);
+                    earlyResult = interrupted(errorInfo, fdv1Fallback);
                 }
                 else {
                     // Non-actionable errors (UNKNOWN_EVENT) are logged but don't stop processing
@@ -3343,19 +3489,18 @@ function processEvents(events, oneShot, fdv1Fallback, environmentId, logger) {
     // Events didn't produce a result
     const errorInfo = errorInfoFromUnknown('Unexpected end of polling response');
     logger?.error('Unexpected end of polling response');
-    return oneShot ? terminalError(errorInfo, fdv1Fallback) : interrupted(errorInfo, fdv1Fallback);
+    return interrupted(errorInfo, fdv1Fallback);
 }
 /**
  * Performs a single FDv2 poll request, processes the protocol response, and
  * returns an {@link FDv2SourceResult}.
  *
- * The `oneShot` parameter controls error handling: when true (initializer),
- * all errors are terminal; when false (synchronizer), recoverable errors
- * produce interrupted results.
+ * Recoverable errors produce interrupted results; unrecoverable HTTP errors
+ * produce terminal errors.
  *
  * @internal
  */
-async function poll(requestor, basis, oneShot, logger) {
+async function poll(requestor, basis, logger) {
     let fdv1Fallback = false;
     let environmentId;
     try {
@@ -3366,7 +3511,6 @@ async function poll(requestor, basis, oneShot, logger) {
         // (Spec Requirement 10.1.2)
         if (response.status === 304) {
             const nonePayload = {
-                id: '',
                 version: 0,
                 type: 'none',
                 updates: [],
@@ -3377,9 +3521,6 @@ async function poll(requestor, basis, oneShot, logger) {
         if (response.status < 200 || response.status >= 300) {
             const errorInfo = errorInfoFromHttpError(response.status);
             logger?.error(`Polling request failed with HTTP error: ${response.status}`);
-            if (oneShot) {
-                return terminalError(errorInfo, fdv1Fallback);
-            }
             const recoverable = response.status <= 0 || jsSdkCommon.isHttpRecoverable(response.status);
             return recoverable
                 ? interrupted(errorInfo, fdv1Fallback)
@@ -3389,9 +3530,7 @@ async function poll(requestor, basis, oneShot, logger) {
         if (!response.body) {
             const errorInfo = errorInfoFromInvalidData('Empty response body');
             logger?.error('Polling request received empty response body');
-            return oneShot
-                ? terminalError(errorInfo, fdv1Fallback)
-                : interrupted(errorInfo, fdv1Fallback);
+            return interrupted(errorInfo, fdv1Fallback);
         }
         let parsed;
         try {
@@ -3400,34 +3539,36 @@ async function poll(requestor, basis, oneShot, logger) {
         catch {
             const errorInfo = errorInfoFromInvalidData('Malformed JSON data in polling response');
             logger?.error('Polling request received malformed data');
-            return oneShot
-                ? terminalError(errorInfo, fdv1Fallback)
-                : interrupted(errorInfo, fdv1Fallback);
+            return interrupted(errorInfo, fdv1Fallback);
         }
         if (!Array.isArray(parsed.events)) {
             const errorInfo = errorInfoFromInvalidData('Invalid polling response: missing or invalid events array');
             logger?.error('Polling response does not contain a valid events array');
-            return oneShot
-                ? terminalError(errorInfo, fdv1Fallback)
-                : interrupted(errorInfo, fdv1Fallback);
+            return interrupted(errorInfo, fdv1Fallback);
         }
-        return processEvents(parsed.events, oneShot, fdv1Fallback, environmentId, logger);
+        return processEvents(parsed.events, fdv1Fallback, environmentId, logger);
     }
     catch (err) {
         // Network or other I/O error from the fetch itself
         const message = err?.message ?? String(err);
         logger?.error(`Polling request failed with network error: ${message}`);
         const errorInfo = errorInfoFromNetworkError(message);
-        return oneShot ? terminalError(errorInfo, fdv1Fallback) : interrupted(errorInfo, fdv1Fallback);
+        return interrupted(errorInfo, fdv1Fallback);
     }
 }
 
+const SHUTDOWN = Symbol('shutdown');
 /**
- * Creates a one-shot polling initializer that performs a single FDv2 poll
- * request and returns the result.
+ * Creates a polling initializer that performs an FDv2 poll request with
+ * retry logic. Retries up to 3 times on recoverable errors with a 1-second
+ * delay between attempts.
  *
- * All errors are treated as terminal (oneShot=true). If `close()` is called
- * before the poll completes, the result will be a shutdown status.
+ * Unrecoverable errors (401, 403, etc.) are returned immediately as terminal
+ * errors. After exhausting retries on recoverable errors, the result is
+ * converted to a terminal error.
+ *
+ * If `close()` is called during a poll or retry delay, the result will be
+ * a shutdown status.
  *
  * @internal
  */
@@ -3438,12 +3579,40 @@ function createPollingInitializer(requestor, logger, selectorGetter) {
     });
     return {
         async run() {
-            const pollResult = poll(requestor, selectorGetter(), true, logger);
-            // Race the poll against the shutdown signal
-            return Promise.race([shutdownPromise, pollResult]);
+            const maxRetries = 3;
+            const retryDelayMs = 1000;
+            const selector = selectorGetter();
+            let lastResult;
+            for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+                // eslint-disable-next-line no-await-in-loop
+                const result = await Promise.race([shutdownPromise, poll(requestor, selector, logger)]);
+                if (result === SHUTDOWN) {
+                    return shutdown();
+                }
+                if (result.type === 'changeSet') {
+                    return result;
+                }
+                // Non-retryable status (terminal_error, goodbye) -> return immediately
+                if (result.state !== 'interrupted') {
+                    return result;
+                }
+                // Recoverable error — save and potentially retry
+                lastResult = result;
+                if (attempt < maxRetries) {
+                    logger?.warn(`Recoverable polling error (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${retryDelayMs}ms...`);
+                    // eslint-disable-next-line no-await-in-loop
+                    const sleepResult = await Promise.race([shutdownPromise, jsSdkCommon.sleep(retryDelayMs)]);
+                    if (sleepResult === SHUTDOWN) {
+                        return shutdown();
+                    }
+                }
+            }
+            // Convert final interrupted -> terminal_error
+            const status = lastResult;
+            return terminalError(status.errorInfo, status.fdv1Fallback);
         },
         close() {
-            shutdownResolve?.(shutdown());
+            shutdownResolve?.(SHUTDOWN);
             shutdownResolve = undefined;
         },
     };
@@ -3506,7 +3675,7 @@ function createPollingSynchronizer(requestor, logger, selectorGetter, pollInterv
         }
         const startTime = Date.now();
         try {
-            const result = await poll(requestor, selectorGetter(), false, logger);
+            const result = await poll(requestor, selectorGetter(), logger);
             if (stopped) {
                 return;
             }
@@ -3583,6 +3752,100 @@ function createSynchronizerSlot(factory, options) {
     const state = options?.initialState ?? (isFDv1Fallback ? 'blocked' : 'available');
     return { factory, isFDv1Fallback, state };
 }
+/**
+ * Creates a {@link SourceManager} that coordinates initializer and
+ * synchronizer lifecycle.
+ *
+ * @param initializerFactories Ordered list of initializer factories.
+ * @param synchronizerSlots Ordered list of synchronizer slots with state.
+ * @param selectorGetter Closure that returns the current selector string.
+ */
+function createSourceManager(initializerFactories, synchronizerSlots, selectorGetter) {
+    let activeSource;
+    let initializerIndex = -1;
+    let synchronizerIndex = -1;
+    let isShutdown = false;
+    function closeActiveSource() {
+        if (activeSource) {
+            activeSource.close();
+            activeSource = undefined;
+        }
+    }
+    function findFirstAvailableIndex() {
+        return synchronizerSlots.findIndex((slot) => slot.state === 'available');
+    }
+    return {
+        get isShutdown() {
+            return isShutdown;
+        },
+        getNextInitializerAndSetActive() {
+            if (isShutdown) {
+                return undefined;
+            }
+            initializerIndex += 1;
+            if (initializerIndex >= initializerFactories.length) {
+                return undefined;
+            }
+            closeActiveSource();
+            const initializer = initializerFactories[initializerIndex](selectorGetter);
+            activeSource = initializer;
+            return initializer;
+        },
+        getNextAvailableSynchronizerAndSetActive() {
+            if (isShutdown || synchronizerSlots.length === 0) {
+                return undefined;
+            }
+            // Scan all slots starting from the position after the current one,
+            // wrapping around to the beginning if needed. This matches the Java
+            // SourceManager behavior where synchronizers cycle rather than exhausting.
+            let visited = 0;
+            while (visited < synchronizerSlots.length) {
+                synchronizerIndex += 1;
+                if (synchronizerIndex >= synchronizerSlots.length) {
+                    synchronizerIndex = 0;
+                }
+                const candidate = synchronizerSlots[synchronizerIndex];
+                if (candidate.state === 'available') {
+                    closeActiveSource();
+                    const synchronizer = candidate.factory(selectorGetter);
+                    activeSource = synchronizer;
+                    return synchronizer;
+                }
+                visited += 1;
+            }
+            return undefined;
+        },
+        blockCurrentSynchronizer() {
+            if (synchronizerIndex >= 0 && synchronizerIndex < synchronizerSlots.length) {
+                // eslint-disable-next-line no-param-reassign
+                synchronizerSlots[synchronizerIndex].state = 'blocked';
+            }
+        },
+        resetSourceIndex() {
+            synchronizerIndex = -1;
+        },
+        fdv1Fallback() {
+            synchronizerSlots.forEach((slot) => {
+                // eslint-disable-next-line no-param-reassign
+                slot.state = slot.isFDv1Fallback ? 'available' : 'blocked';
+            });
+            synchronizerIndex = -1;
+        },
+        isPrimeSynchronizer() {
+            return synchronizerIndex === findFirstAvailableIndex();
+        },
+        getAvailableSynchronizerCount() {
+            return synchronizerSlots.filter((slot) => slot.state === 'available').length;
+        },
+        hasFDv1Fallback() {
+            return synchronizerSlots.some((slot) => slot.isFDv1Fallback);
+        },
+        close() {
+            isShutdown = true;
+            closeActiveSource();
+        },
+    };
+}
 
 /**
  * FDv2 event names to listen for on the EventSource. This must stay in sync
@@ -3746,6 +4009,7 @@ function createStreamingBase(config) {
                 initialRetryDelayMillis: config.initialRetryDelayMillis,
                 readTimeoutMillis: 5 * 60 * 1000,
                 retryResetIntervalMillis: 60 * 1000,
+                urlBuilder: buildStreamUri,
             });
             eventSource = es;
             attachFDv2Listeners(es);
@@ -3877,7 +4141,7 @@ function createStreamingSynchronizer(base) {
 
 function createPingHandler(requestor, selectorGetter, logger) {
     return {
-        handlePing: () => poll(requestor, selectorGetter(), false, logger),
+        handlePing: () => poll(requestor, selectorGetter(), logger),
     };
 }
 /**
@@ -3968,6 +4232,930 @@ function createDefaultSourceFactoryProvider() {
     };
 }
 
+function flagsToPayload(flags) {
+    const updates = Object.entries(flags).map(([key, flag]) => ({
+        kind: 'flag',
+        key,
+        version: flag.version ?? 1,
+        object: flag,
+    }));
+    return {
+        version: 1,
+        type: 'full',
+        updates,
+    };
+}
+/**
+ * Creates a polling synchronizer that polls an FDv1 endpoint and produces
+ * results in the FDv2 {@link Synchronizer} pull model.
+ *
+ * This is a standalone implementation (not a wrapper around the existing FDv1
+ * `PollingProcessor`) because the FDv1 fallback is temporary and will be
+ * removed in the next major version. A focused implementation is simpler than
+ * an adapter layer.
+ *
+ * Polling starts lazily on the first call to `next()`. Each poll returns the
+ * complete flag set as a `changeSet` result with `type: 'full'` and an empty
+ * selector.
+ *
+ * @param requestor FDv1 requestor configured with the appropriate endpoint.
+ * @param pollIntervalMs Interval between polls in milliseconds.
+ * @param logger Optional logger.
+ * @internal
+ */
+function createFDv1PollingSynchronizer(requestor, pollIntervalMs, logger) {
+    const resultQueue = createAsyncQueue();
+    let shutdownResolve;
+    const shutdownPromise = new Promise((resolve) => {
+        shutdownResolve = resolve;
+    });
+    let timeoutHandle;
+    let stopped = false;
+    let started = false;
+    function scheduleNextPoll(startTime) {
+        if (!stopped) {
+            const elapsed = Date.now() - startTime;
+            const sleepFor = Math.min(Math.max(pollIntervalMs - elapsed, 0), pollIntervalMs);
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            timeoutHandle = setTimeout(doPoll, sleepFor);
+        }
+    }
+    async function doPoll() {
+        if (stopped) {
+            return;
+        }
+        logger?.debug('Polling FDv1 endpoint for feature flag updates');
+        const startTime = Date.now();
+        try {
+            const body = await requestor.requestPayload();
+            if (stopped) {
+                return;
+            }
+            let payload;
+            try {
+                const flags = JSON.parse(body);
+                payload = flagsToPayload(flags);
+            }
+            catch {
+                logger?.error('FDv1 polling received malformed data');
+                resultQueue.put({
+                    type: 'status',
+                    state: 'interrupted',
+                    errorInfo: errorInfoFromInvalidData('Malformed data in FDv1 polling response'),
+                    fdv1Fallback: false,
+                });
+                scheduleNextPoll(startTime);
+                return;
+            }
+            resultQueue.put(changeSet(payload, false));
+        }
+        catch (err) {
+            if (stopped) {
+                return;
+            }
+            const requestError = err;
+            if (requestError.status !== undefined) {
+                if (!jsSdkCommon.isHttpRecoverable(requestError.status)) {
+                    logger?.error(jsSdkCommon.httpErrorMessage(err, 'FDv1 polling request'));
+                    stopped = true;
+                    shutdownResolve?.(terminalError(errorInfoFromHttpError(requestError.status), false));
+                    shutdownResolve = undefined;
+                    return;
+                }
+            }
+            logger?.warn(jsSdkCommon.httpErrorMessage(err, 'FDv1 polling request', 'will retry'));
+            resultQueue.put({
+                type: 'status',
+                state: 'interrupted',
+                errorInfo: requestError.status
+                    ? errorInfoFromHttpError(requestError.status)
+                    : errorInfoFromNetworkError(requestError.message),
+                fdv1Fallback: false,
+            });
+        }
+        scheduleNextPoll(startTime);
+    }
+    return {
+        next() {
+            if (!started) {
+                started = true;
+                doPoll();
+            }
+            return Promise.race([shutdownPromise, resultQueue.take()]);
+        },
+        close() {
+            stopped = true;
+            if (timeoutHandle !== undefined) {
+                clearTimeout(timeoutHandle);
+                timeoutHandle = undefined;
+            }
+            shutdownResolve?.(shutdown());
+            shutdownResolve = undefined;
+        },
+    };
+}
+
+const DEFAULT_FALLBACK_TIMEOUT_MS = 2 * 60 * 1000; // 120 seconds
+const DEFAULT_RECOVERY_TIMEOUT_MS = 5 * 60 * 1000; // 300 seconds
+/**
+ * Creates a cancelable timer that resolves with the given {@link ConditionType}
+ * when it fires. Wraps {@link cancelableTimedPromise} to convert its
+ * reject-on-timeout semantics into resolve-with-type semantics.
+ */
+function conditionTimer(timeoutMs, type, taskName) {
+    const timed = jsSdkCommon.cancelableTimedPromise(timeoutMs / 1000, taskName);
+    return {
+        promise: timed.promise.then(() => new Promise(() => { }), // cancelled — never settle
+        () => type),
+        cancel: timed.cancel,
+    };
+}
+/**
+ * Creates a timed {@link Condition}.
+ *
+ * @param timeoutMs Time in milliseconds before the condition fires.
+ * @param type The {@link ConditionType} to resolve with when the timer fires.
+ * @param informHandler Optional callback invoked on each `inform()` call.
+ *   When omitted, the timer starts immediately and `inform()` is a no-op.
+ *   When provided, the timer must be started explicitly via `controls.start()`.
+ */
+function createCondition(timeoutMs, type, informHandler) {
+    let resolve;
+    let timer;
+    let closed = false;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    function startTimer() {
+        if (!timer && !closed) {
+            timer = conditionTimer(timeoutMs, type, `${type} condition`);
+            timer.promise.then((t) => {
+                timer = undefined;
+                resolve?.(t);
+            });
+        }
+    }
+    function cancelTimer() {
+        timer?.cancel();
+        timer = undefined;
+    }
+    // No inform handler — start immediately (recovery behavior).
+    if (!informHandler) {
+        startTimer();
+    }
+    return {
+        promise,
+        inform(result) {
+            if (closed) {
+                return;
+            }
+            informHandler?.(result, { start: startTimer, cancel: cancelTimer });
+        },
+        close() {
+            closed = true;
+            cancelTimer();
+        },
+    };
+}
+/**
+ * Creates a fallback condition. The condition starts a timer when an
+ * `interrupted` status is received and cancels it when a `changeSet` is
+ * received. If the timer fires, the condition resolves with `'fallback'`.
+ */
+function createFallbackCondition(timeoutMs) {
+    return createCondition(timeoutMs, 'fallback', (result, { start, cancel }) => {
+        if (result.type === 'changeSet') {
+            cancel();
+        }
+        else if (result.type === 'status' && result.state === 'interrupted') {
+            start();
+        }
+    });
+}
+/**
+ * Creates a recovery condition. The condition starts a timer immediately
+ * and resolves with `'recovery'` when it fires. It ignores all `inform()`
+ * calls.
+ */
+function createRecoveryCondition(timeoutMs) {
+    return createCondition(timeoutMs, 'recovery');
+}
+/**
+ * Creates a group of conditions that are managed together.
+ *
+ * @param conditions The conditions to group.
+ */
+function createConditionGroup(conditions) {
+    return {
+        promise: conditions.length === 0 ? undefined : Promise.race(conditions.map((c) => c.promise)),
+        inform(result) {
+            conditions.forEach((condition) => condition.inform(result));
+        },
+        close() {
+            conditions.forEach((condition) => condition.close());
+        },
+    };
+}
+/**
+ * Determines which conditions to create based on the synchronizer's position
+ * and availability.
+ *
+ * - If there is only one available synchronizer, no conditions are needed
+ *   (there is nowhere to fall back to).
+ * - If the current synchronizer is the primary (first available), only a
+ *   fallback condition is created.
+ * - If the current synchronizer is non-primary, both fallback and recovery
+ *   conditions are created.
+ *
+ * @param availableSyncCount Number of available (non-blocked) synchronizers.
+ * @param isPrime Whether the current synchronizer is the primary.
+ * @param fallbackTimeoutMs Fallback condition timeout.
+ * @param recoveryTimeoutMs Recovery condition timeout.
+ */
+function getConditions(availableSyncCount, isPrime, fallbackTimeoutMs = DEFAULT_FALLBACK_TIMEOUT_MS, recoveryTimeoutMs = DEFAULT_RECOVERY_TIMEOUT_MS) {
+    if (availableSyncCount <= 1) {
+        return createConditionGroup([]);
+    }
+    if (isPrime) {
+        return createConditionGroup([createFallbackCondition(fallbackTimeoutMs)]);
+    }
+    return createConditionGroup([
+        createFallbackCondition(fallbackTimeoutMs),
+        createRecoveryCondition(recoveryTimeoutMs),
+    ]);
+}
+
+/**
+ * Creates an {@link FDv2DataSource} orchestrator.
+ */
+function createFDv2DataSource(config) {
+    const { initializerFactories, synchronizerSlots, dataCallback, statusManager, selectorGetter, logger, fallbackTimeoutMs = DEFAULT_FALLBACK_TIMEOUT_MS, recoveryTimeoutMs = DEFAULT_RECOVERY_TIMEOUT_MS, } = config;
+    let initialized = false;
+    let closed = false;
+    let dataReceived = false;
+    let initResolve;
+    let initReject;
+    const sourceManager = createSourceManager(initializerFactories, synchronizerSlots, selectorGetter);
+    function markInitialized() {
+        if (!initialized) {
+            initialized = true;
+            initResolve?.();
+            initResolve = undefined;
+            initReject = undefined;
+        }
+    }
+    function applyChangeSet(result) {
+        dataCallback(result.payload);
+        statusManager.requestStateUpdate('VALID');
+    }
+    function reportStatusError(result) {
+        if (result.errorInfo) {
+            statusManager.reportError(result.errorInfo.kind, result.errorInfo.message, result.errorInfo.statusCode, result.state === 'interrupted');
+        }
+    }
+    function handleFdv1Fallback(result) {
+        if (result.fdv1Fallback && sourceManager.hasFDv1Fallback()) {
+            sourceManager.fdv1Fallback();
+            return true;
+        }
+        return false;
+    }
+    /* eslint-disable no-await-in-loop */
+    // The orchestration loops intentionally use await-in-loop for sequential
+    // state machine processing — one result at a time.
+    async function runInitializers() {
+        while (!closed) {
+            const initializer = sourceManager.getNextInitializerAndSetActive();
+            if (initializer === undefined) {
+                break;
+            }
+            const result = await initializer.run();
+            if (closed) {
+                return;
+            }
+            if (result.type === 'changeSet' && result.payload.type !== 'none') {
+                applyChangeSet(result);
+                if (handleFdv1Fallback(result)) {
+                    // FDv1 fallback triggered during initialization -- data was received
+                    // but we should move to synchronizers where the FDv1 adapter will run.
+                    dataReceived = true;
+                    break;
+                }
+                if (result.payload.state) {
+                    // Got basis data with a selector -- initialization is complete.
+                    markInitialized();
+                    return;
+                }
+                // Got data but no selector (e.g., cache). Record that data was
+                // received and continue to the next initializer.
+                dataReceived = true;
+            }
+            else if (result.type === 'status') {
+                switch (result.state) {
+                    case 'interrupted':
+                    case 'terminal_error':
+                        logger?.warn(`Initializer failed: ${result.errorInfo?.message ?? 'unknown error'}`);
+                        reportStatusError(result);
+                        break;
+                    case 'shutdown':
+                        return;
+                }
+                handleFdv1Fallback(result);
+            }
+        }
+        // All initializers exhausted.
+        if (dataReceived) {
+            markInitialized();
+        }
+    }
+    async function runSynchronizers() {
+        while (!closed) {
+            const synchronizer = sourceManager.getNextAvailableSynchronizerAndSetActive();
+            if (synchronizer === undefined) {
+                if (!initialized) {
+                    initReject?.(new Error('All data sources exhausted without receiving data.'));
+                    initResolve = undefined;
+                    initReject = undefined;
+                }
+                return;
+            }
+            const conditions = getConditions(sourceManager.getAvailableSynchronizerCount(), sourceManager.isPrimeSynchronizer(), fallbackTimeoutMs, recoveryTimeoutMs);
+            if (conditions.promise) {
+                logger?.debug('Fallback condition active for current synchronizer.');
+            }
+            // try/finally ensures conditions are closed on all code paths.
+            let synchronizerRunning = true;
+            try {
+                while (!closed && synchronizerRunning) {
+                    const syncPromise = synchronizer
+                        .next()
+                        .then((value) => ({ source: 'sync', value }));
+                    const racers = [syncPromise];
+                    if (conditions.promise !== undefined) {
+                        racers.push(conditions.promise.then((value) => ({ source: 'condition', value })));
+                    }
+                    const winner = await Promise.race(racers);
+                    if (closed) {
+                        return;
+                    }
+                    if (winner.source === 'condition') {
+                        const conditionType = winner.value;
+                        if (conditionType === 'fallback') {
+                            logger?.warn('Fallback condition fired, moving to next synchronizer.');
+                        }
+                        else if (conditionType === 'recovery') {
+                            logger?.info('Recovery condition fired, resetting to primary synchronizer.');
+                            sourceManager.resetSourceIndex();
+                        }
+                        synchronizerRunning = false;
+                    }
+                    else {
+                        // Synchronizer produced a result.
+                        const syncResult = winner.value;
+                        conditions.inform(syncResult);
+                        if (syncResult.type === 'changeSet') {
+                            applyChangeSet(syncResult);
+                            if (!initialized) {
+                                markInitialized();
+                            }
+                        }
+                        else if (syncResult.type === 'status') {
+                            switch (syncResult.state) {
+                                case 'interrupted':
+                                    logger?.warn(`Synchronizer interrupted: ${syncResult.errorInfo?.message ?? 'unknown error'}`);
+                                    reportStatusError(syncResult);
+                                    break;
+                                case 'terminal_error':
+                                    logger?.error(`Synchronizer terminal error: ${syncResult.errorInfo?.message ?? 'unknown error'}`);
+                                    reportStatusError(syncResult);
+                                    sourceManager.blockCurrentSynchronizer();
+                                    synchronizerRunning = false;
+                                    break;
+                                case 'shutdown':
+                                    return;
+                                case 'goodbye':
+                                    // The synchronizer will handle reconnection internally.
+                                    break;
+                                default:
+                                    break;
+                            }
+                        }
+                        // Check for FDv1 fallback after all result handling — single location.
+                        if (handleFdv1Fallback(syncResult)) {
+                            synchronizerRunning = false;
+                        }
+                    }
+                }
+            }
+            finally {
+                conditions.close();
+            }
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    async function runOrchestration() {
+        // No sources configured at all — nothing to wait for, immediately valid.
+        if (initializerFactories.length === 0 && synchronizerSlots.length === 0) {
+            statusManager.requestStateUpdate('VALID');
+            markInitialized();
+            return;
+        }
+        await runInitializers();
+        if (!closed) {
+            await runSynchronizers();
+        }
+    }
+    return {
+        start() {
+            return new Promise((resolve, reject) => {
+                initResolve = resolve;
+                initReject = reject;
+                statusManager.requestStateUpdate('INITIALIZING');
+                runOrchestration()
+                    .then(() => {
+                    // Orchestration completed without error. If the init promise was
+                    // never resolved (e.g., close() called during init, or all sources
+                    // exhausted without data and no synchronizers), resolve it now.
+                    // This prevents the start() promise from hanging forever.
+                    if (!initialized) {
+                        initReject?.(new Error('Data source closed before initialization completed.'));
+                        initResolve = undefined;
+                        initReject = undefined;
+                    }
+                })
+                    .catch((err) => {
+                    if (!initialized) {
+                        initReject?.(err instanceof Error ? err : new Error(String(err)));
+                        initResolve = undefined;
+                        initReject = undefined;
+                    }
+                    else {
+                        logger?.error(`Orchestration error: ${err}`);
+                    }
+                });
+            });
+        },
+        close() {
+            closed = true;
+            sourceManager.close();
+        },
+    };
+}
+
+/** Default debounce window duration in milliseconds. */
+const DEFAULT_DEBOUNCE_MS = 1000;
+/**
+ * Creates a {@link StateDebounceManager}.
+ *
+ * The manager accumulates state changes from network, lifecycle, and
+ * connection mode events. Each event updates the relevant component
+ * of the pending state and resets the debounce timer. When the timer
+ * fires, the reconciliation callback receives the final combined state.
+ *
+ * @param config Configuration for the debounce manager.
+ */
+function createStateDebounceManager(config) {
+    const { initialState, onReconcile, debounceMs = DEFAULT_DEBOUNCE_MS } = config;
+    let { networkState, lifecycleState, requestedMode } = initialState;
+    let timer;
+    let closed = false;
+    function getPendingState() {
+        return { networkState, lifecycleState, requestedMode };
+    }
+    function resetTimer() {
+        if (closed) {
+            return;
+        }
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (!closed) {
+                onReconcile(getPendingState());
+            }
+        }, debounceMs);
+    }
+    return {
+        setNetworkState(state) {
+            if (networkState === state) {
+                return;
+            }
+            networkState = state;
+            resetTimer();
+        },
+        setLifecycleState(state) {
+            if (lifecycleState === state) {
+                return;
+            }
+            lifecycleState = state;
+            resetTimer();
+        },
+        setRequestedMode(mode) {
+            if (requestedMode === mode) {
+                return;
+            }
+            requestedMode = mode;
+            resetTimer();
+        },
+        close() {
+            closed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}
+
+const logTag = '[FDv2DataManagerBase]';
+/**
+ * Creates a shared FDv2 data manager that owns mode resolution, debouncing,
+ * selector state, and FDv2DataSource lifecycle. Platform SDKs (browser, RN)
+ * wrap this with platform-specific config and event wiring.
+ */
+function createFDv2DataManagerBase(baseConfig) {
+    const { platform, flagManager, config, baseHeaders, emitter, transitionTable, foregroundMode: configuredForegroundMode, backgroundMode, modeTable, sourceFactoryProvider, buildQueryParams, fdv1Endpoints, fallbackTimeoutMs, recoveryTimeoutMs, } = baseConfig;
+    const { logger } = config;
+    const statusManager = createDataSourceStatusManager(emitter);
+    const endpoints = fdv2Endpoints();
+    // Merge user-provided connection mode overrides into the mode table.
+    const effectiveModeTable = config.dataSystem?.connectionModes
+        ? { ...modeTable, ...config.dataSystem.connectionModes }
+        : modeTable;
+    // --- Mutable state ---
+    let selector;
+    let currentResolvedMode = configuredForegroundMode;
+    let foregroundMode = configuredForegroundMode;
+    let dataSource;
+    let debounceManager;
+    let identifiedContext;
+    let factoryContext;
+    let initialized = false;
+    let bootstrapped = false;
+    let closed = false;
+    let flushCallback;
+    // Explicit connection mode override — bypasses transition table entirely.
+    let connectionModeOverride;
+    // Forced/automatic streaming state for browser listener-driven streaming.
+    let forcedStreaming;
+    let automaticStreamingState = false;
+    // Outstanding identify promise callbacks — needed so that mode switches
+    // during identify can wire the new data source's completion to the
+    // original identify promise.
+    let pendingIdentifyResolve;
+    let pendingIdentifyReject;
+    // Current debounce input state.
+    let networkState = 'available';
+    let lifecycleState = 'foreground';
+    // --- Helpers ---
+    function getModeDefinition(mode) {
+        return effectiveModeTable[mode];
+    }
+    function buildModeState() {
+        return {
+            lifecycle: lifecycleState,
+            networkAvailable: networkState === 'available',
+            foregroundMode,
+            backgroundMode: backgroundMode ?? 'offline',
+        };
+    }
+    /**
+     * Resolve the current effective connection mode.
+     *
+     * Priority:
+     * 1. connectionModeOverride (set via setConnectionMode) — bypasses everything
+     * 2. Transition table (network/lifecycle state + foreground/background modes)
+     */
+    function resolveMode() {
+        if (connectionModeOverride !== undefined) {
+            return connectionModeOverride;
+        }
+        return resolveConnectionMode(transitionTable, buildModeState());
+    }
+    /**
+     * Resolve the foreground mode input for the transition table based on
+     * forced/automatic streaming state.
+     *
+     * Priority: forcedStreaming > automaticStreaming > configuredForegroundMode
+     */
+    function resolveStreamingForeground() {
+        if (forcedStreaming === true) {
+            return 'streaming';
+        }
+        if (forcedStreaming === false) {
+            return configuredForegroundMode === 'streaming' ? 'one-shot' : configuredForegroundMode;
+        }
+        return automaticStreamingState ? 'streaming' : configuredForegroundMode;
+    }
+    /**
+     * Compute the effective foreground mode from streaming state and push it
+     * through the debounce manager. Used by setForcedStreaming and
+     * setAutomaticStreamingState.
+     */
+    function pushForegroundMode() {
+        foregroundMode = resolveStreamingForeground();
+        debounceManager?.setRequestedMode(foregroundMode);
+    }
+    /**
+     * Convert a ModeDefinition's entries into concrete InitializerFactory[]
+     * and SynchronizerSlot[] using the source factory provider.
+     */
+    function buildFactories(modeDef, ctx, includeInitializers) {
+        const initializerFactories = [];
+        if (includeInitializers) {
+            modeDef.initializers
+                // Skip cache when bootstrapped — bootstrap data was applied to the
+                // flag store before identify, so the cache would only load older data.
+                .filter((entry) => !(bootstrapped && entry.type === 'cache'))
+                .forEach((entry) => {
+                const factory = sourceFactoryProvider.createInitializerFactory(entry, ctx);
+                if (factory) {
+                    initializerFactories.push(factory);
+                }
+                else {
+                    logger.warn(`${logTag} Unsupported initializer type '${entry.type}'. It will be skipped.`);
+                }
+            });
+        }
+        const synchronizerSlots = [];
+        modeDef.synchronizers.forEach((entry) => {
+            const slot = sourceFactoryProvider.createSynchronizerSlot(entry, ctx);
+            if (slot) {
+                synchronizerSlots.push(slot);
+            }
+            else {
+                logger.warn(`${logTag} Unsupported synchronizer type '${entry.type}'. It will be skipped.`);
+            }
+        });
+        // Append a blocked FDv1 fallback synchronizer when configured and
+        // when there are FDv2 synchronizers to fall back from.
+        if (fdv1Endpoints && synchronizerSlots.length > 0) {
+            const fallbackConfig = modeDef.fdv1Fallback;
+            const fallbackPollIntervalMs = (fallbackConfig?.pollInterval ?? config.pollInterval) * 1000;
+            const fallbackServiceEndpoints = fallbackConfig?.endpoints?.pollingBaseUri || fallbackConfig?.endpoints?.streamingBaseUri
+                ? new jsSdkCommon.ServiceEndpoints(fallbackConfig.endpoints.streamingBaseUri ?? ctx.serviceEndpoints.streaming, fallbackConfig.endpoints.pollingBaseUri ?? ctx.serviceEndpoints.polling, ctx.serviceEndpoints.events, ctx.serviceEndpoints.analyticsEventPath, ctx.serviceEndpoints.diagnosticEventPath, ctx.serviceEndpoints.includeAuthorizationHeader, ctx.serviceEndpoints.payloadFilterKey)
+                : ctx.serviceEndpoints;
+            const fdv1RequestorFactory = () => makeRequestor(ctx.plainContextString, fallbackServiceEndpoints, fdv1Endpoints.polling(), ctx.requests, ctx.encoding, ctx.baseHeaders, ctx.queryParams, config.withReasons, config.useReport);
+            const fdv1SyncFactory = () => createFDv1PollingSynchronizer(fdv1RequestorFactory(), fallbackPollIntervalMs, logger);
+            synchronizerSlots.push(createSynchronizerSlot(fdv1SyncFactory, { isFDv1Fallback: true }));
+        }
+        return { initializerFactories, synchronizerSlots };
+    }
+    /**
+     * The data callback shared across all FDv2DataSource instances for
+     * the current identify. Handles selector tracking and flag updates.
+     */
+    function dataCallback(payload) {
+        logger.debug(`${logTag} dataCallback: type=${payload.type}, updates=${payload.updates.length}, state=${payload.state}`);
+        selector = payload.state;
+        const context = identifiedContext;
+        if (!context) {
+            logger.warn(`${logTag} dataCallback called without an identified context.`);
+            return;
+        }
+        const descriptors = flagEvalPayloadToItemDescriptors(payload.updates ?? []);
+        // Flag updates and change events happen synchronously inside applyChanges.
+        // The returned promise is only for async cache persistence — we intentionally
+        // do not await it so the data source pipeline is not blocked by storage I/O.
+        flagManager.applyChanges(context, descriptors, payload.type).catch((e) => {
+            logger.warn(`${logTag} Failed to persist flag cache: ${e}`);
+        });
+    }
+    /**
+     * Create and start a new FDv2DataSource for the given mode.
+     *
+     * @param mode The connection mode to use.
+     * @param includeInitializers Whether to include initializers (true on
+     *   first identify, false on mode switch after initialization).
+     */
+    function createAndStartDataSource(mode, includeInitializers) {
+        if (!factoryContext) {
+            logger.warn(`${logTag} Cannot create data source without factory context.`);
+            return;
+        }
+        const modeDef = getModeDefinition(mode);
+        const { initializerFactories, synchronizerSlots } = buildFactories(modeDef, factoryContext, includeInitializers);
+        currentResolvedMode = mode;
+        // If there are no sources at all (e.g., offline or one-shot mode
+        // post-initialization), don't create a data source.
+        if (initializerFactories.length === 0 && synchronizerSlots.length === 0) {
+            logger.debug(`${logTag} Mode '${mode}' has no sources. No data source created.`);
+            if (!initialized && pendingIdentifyResolve) {
+                // Offline mode during initial identify — resolve immediately.
+                // The SDK will use cached data if any.
+                initialized = true;
+                pendingIdentifyResolve();
+                pendingIdentifyResolve = undefined;
+                pendingIdentifyReject = undefined;
+            }
+            return;
+        }
+        const selectorGetter = () => selector;
+        dataSource = createFDv2DataSource({
+            initializerFactories,
+            synchronizerSlots,
+            dataCallback,
+            statusManager,
+            selectorGetter,
+            logger,
+            fallbackTimeoutMs,
+            recoveryTimeoutMs,
+        });
+        dataSource
+            .start()
+            .then(() => {
+            initialized = true;
+            if (pendingIdentifyResolve) {
+                pendingIdentifyResolve();
+                pendingIdentifyResolve = undefined;
+                pendingIdentifyReject = undefined;
+            }
+        })
+            .catch((err) => {
+            if (pendingIdentifyReject) {
+                pendingIdentifyReject(err instanceof Error ? err : new Error(String(err)));
+                pendingIdentifyResolve = undefined;
+                pendingIdentifyReject = undefined;
+            }
+        });
+    }
+    /**
+     * Reconciliation callback invoked when the debounce timer fires.
+     * Resolves the new mode and switches data sources if needed.
+     */
+    function onReconcile(pendingState) {
+        if (closed || !factoryContext) {
+            return;
+        }
+        // Update local state from the debounced pending state.
+        networkState = pendingState.networkState;
+        lifecycleState = pendingState.lifecycleState;
+        foregroundMode = pendingState.requestedMode;
+        const newMode = resolveMode();
+        if (newMode === currentResolvedMode) {
+            logger.debug(`${logTag} Reconcile: mode unchanged (${newMode}). No action.`);
+            return;
+        }
+        logger.debug(`${logTag} Reconcile: mode switching from '${currentResolvedMode}' to '${newMode}'.`);
+        // Close the current data source.
+        dataSource?.close();
+        dataSource = undefined;
+        // Include initializers if we don't have a selector yet. This covers:
+        // - Not yet initialized (normal case)
+        // - Initialized from bootstrap (no selector) — need initializers to
+        //   get a full payload via poll before starting synchronizers
+        // When we have a selector, only synchronizers change (spec 5.3.8).
+        const includeInitializers = !selector;
+        createAndStartDataSource(newMode, includeInitializers);
+    }
+    // --- Public interface ---
+    return {
+        get configuredForegroundMode() {
+            return configuredForegroundMode;
+        },
+        async identify(identifyResolve, identifyReject, context, identifyOptions) {
+            if (closed) {
+                logger.debug(`${logTag} Identify called after close.`);
+                return;
+            }
+            // Tear down previous state.
+            dataSource?.close();
+            dataSource = undefined;
+            debounceManager?.close();
+            debounceManager = undefined;
+            selector = undefined;
+            initialized = false;
+            bootstrapped = false;
+            identifiedContext = context;
+            pendingIdentifyResolve = identifyResolve;
+            pendingIdentifyReject = identifyReject;
+            const plainContextString = JSON.stringify(jsSdkCommon.Context.toLDContext(context));
+            const queryParams = buildQueryParams(identifyOptions);
+            if (config.withReasons) {
+                queryParams.push({ key: 'withReasons', value: 'true' });
+            }
+            const streamingEndpoints = endpoints.streaming();
+            const pollingEndpoints = endpoints.polling();
+            const requestor = makeFDv2Requestor(plainContextString, config.serviceEndpoints, pollingEndpoints, platform.requests, platform.encoding, baseHeaders, queryParams);
+            const environmentNamespace = await namespaceForEnvironment(platform.crypto, baseConfig.credential);
+            // Re-check after the await — close() may have been called while
+            // namespaceForEnvironment was pending.
+            if (closed) {
+                logger.debug(`${logTag} Identify aborted: closed during async setup.`);
+                return;
+            }
+            factoryContext = {
+                requestor,
+                requests: platform.requests,
+                encoding: platform.encoding,
+                serviceEndpoints: config.serviceEndpoints,
+                baseHeaders,
+                queryParams,
+                plainContextString,
+                logger,
+                polling: {
+                    paths: pollingEndpoints,
+                    intervalSeconds: config.pollInterval,
+                },
+                streaming: {
+                    paths: streamingEndpoints,
+                    initialReconnectDelaySeconds: config.streamInitialReconnectDelay,
+                },
+                storage: platform.storage,
+                crypto: platform.crypto,
+                environmentNamespace,
+                context,
+            };
+            // Ensure foreground mode reflects current streaming state before resolving.
+            foregroundMode = resolveStreamingForeground();
+            // Resolve the initial mode.
+            const mode = resolveMode();
+            logger.debug(`${logTag} Identify: initial mode resolved to '${mode}'.`);
+            bootstrapped = identifyOptions?.bootstrap !== undefined;
+            if (bootstrapped) {
+                // Bootstrap data was already applied to the flag store by the
+                // caller (BrowserClient.start → presetFlags) before identify
+                // was called. Resolve immediately — flag evaluations will use
+                // the bootstrap data synchronously.
+                initialized = true;
+                statusManager.requestStateUpdate('VALID');
+                // selector remains undefined — bootstrap data has no selector.
+                pendingIdentifyResolve?.();
+                pendingIdentifyResolve = undefined;
+                pendingIdentifyReject = undefined;
+                // Only create a data source if the mode has synchronizers.
+                // For one-shot (no synchronizers), there's nothing more to do.
+                const modeDef = getModeDefinition(mode);
+                if (modeDef.synchronizers.length > 0) {
+                    // Start synchronizers without initializers — we already have
+                    // data from bootstrap. Initializers will run on mode switches
+                    // if selector is still undefined (see onReconcile).
+                    createAndStartDataSource(mode, false);
+                }
+            }
+            else {
+                // Normal identify — create and start the data source with full pipeline.
+                createAndStartDataSource(mode, true);
+            }
+            // Set up debouncing for subsequent state changes.
+            debounceManager = createStateDebounceManager({
+                initialState: {
+                    networkState,
+                    lifecycleState,
+                    requestedMode: foregroundMode,
+                },
+                onReconcile,
+            });
+        },
+        close() {
+            closed = true;
+            dataSource?.close();
+            dataSource = undefined;
+            debounceManager?.close();
+            debounceManager = undefined;
+            pendingIdentifyResolve = undefined;
+            pendingIdentifyReject = undefined;
+        },
+        setNetworkState(state) {
+            networkState = state;
+            debounceManager?.setNetworkState(state);
+        },
+        setLifecycleState(state) {
+            // Flush immediately when going to background — the app may be
+            // about to close. This is not debounced (CONNMODE spec 3.3.1).
+            if (state === 'background' && lifecycleState !== 'background') {
+                flushCallback?.();
+            }
+            lifecycleState = state;
+            debounceManager?.setLifecycleState(state);
+        },
+        setConnectionMode(mode) {
+            connectionModeOverride = mode;
+            if (mode !== undefined) {
+                debounceManager?.setRequestedMode(mode);
+            }
+            else {
+                pushForegroundMode();
+            }
+        },
+        getCurrentMode() {
+            return currentResolvedMode;
+        },
+        setFlushCallback(callback) {
+            flushCallback = callback;
+        },
+        setForcedStreaming(streaming) {
+            forcedStreaming = streaming;
+            pushForegroundMode();
+        },
+        setAutomaticStreamingState(streaming) {
+            automaticStreamingState = streaming;
+            pushForegroundMode();
+        },
+    };
+}
+
 exports.platform = jsSdkCommon__namespace;
 exports.BROWSER_DATA_SYSTEM_DEFAULTS = BROWSER_DATA_SYSTEM_DEFAULTS;
 exports.BROWSER_TRANSITION_TABLE = BROWSER_TRANSITION_TABLE;
@@ -3982,12 +5170,15 @@ exports.MODE_TABLE = MODE_TABLE;
 exports.browserFdv1Endpoints = browserFdv1Endpoints;
 exports.createDataSourceStatusManager = createDataSourceStatusManager;
 exports.createDefaultSourceFactoryProvider = createDefaultSourceFactoryProvider;
+exports.createFDv2DataManagerBase = createFDv2DataManagerBase;
+exports.createStateDebounceManager = createStateDebounceManager;
 exports.dataSystemValidators = dataSystemValidators;
 exports.fdv2Endpoints = fdv2Endpoints;
 exports.makeRequestor = makeRequestor;
 exports.mobileFdv1Endpoints = mobileFdv1Endpoints;
 exports.readFlagsFromBootstrap = readFlagsFromBootstrap;
 exports.resolveConnectionMode = resolveConnectionMode;
+exports.resolveForegroundMode = resolveForegroundMode;
 exports.safeRegisterDebugOverridePlugins = safeRegisterDebugOverridePlugins;
 exports.validateOptions = validateOptions;
 Object.keys(jsSdkCommon).forEach(function (k) {