feat: FDv2 contract test wiring, suppressions, and example app, cleanup configuration exports.

.gitignore

@@ -27,3 +27,4 @@ stats.html
 .env
 .env.local
 .env.*.local
+.claude/worktrees

package.json

@@ -53,7 +53,8 @@
     "packages/sdk/shopify-oxygen",
     "packages/sdk/shopify-oxygen/contract-tests",
     "packages/sdk/shopify-oxygen/example",
-    "packages/sdk/browser/example"
+    "packages/sdk/browser/example",
+    "packages/sdk/browser/example-fdv2"
   ],
   "private": true,
   "scripts": {

packages/sdk/browser/contract-tests/entity/src/ClientEntity.ts

@@ -1,9 +1,20 @@
-import { createClient, LDClient, LDLogger, LDOptions } from '@launchdarkly/js-client-sdk';
+import {
+  createClient,
+  InitializerEntry,
+  LDClient,
+  LDLogger,
+  LDOptions,
+  ModeDefinition,
+  SynchronizerEntry,
+} from '@launchdarkly/js-client-sdk';
 import {
   CommandParams,
   CommandType,
   CreateInstanceParams,
   makeLogger,
+  SDKConfigDataInitializer,
+  SDKConfigDataSynchronizer,
+  SDKConfigModeDefinition,
   SDKConfigParams,
   ClientSideTestHook as TestHook,
   ValueType,
@@ -12,6 +23,59 @@ import {
 export const badCommandError = new Error('unsupported command');
 export const malformedCommand = new Error('command was malformed');
 
+function translateInitializer(init: SDKConfigDataInitializer): InitializerEntry | undefined {
+  if (init.polling) {
+    return {
+      type: 'polling',
+      ...(init.polling.pollIntervalMs !== undefined && {
+        pollInterval: init.polling.pollIntervalMs / 1000,
+      }),
+      ...(init.polling.baseUri && {
+        endpoints: { pollingBaseUri: init.polling.baseUri },
+      }),
+    };
+  }
+  return undefined;
+}
+
+function translateSynchronizer(sync: SDKConfigDataSynchronizer): SynchronizerEntry | undefined {
+  if (sync.streaming) {
+    return {
+      type: 'streaming',
+      ...(sync.streaming.initialRetryDelayMs !== undefined && {
+        initialReconnectDelay: sync.streaming.initialRetryDelayMs / 1000,
+      }),
+      ...(sync.streaming.baseUri && {
+        endpoints: { streamingBaseUri: sync.streaming.baseUri },
+      }),
+    };
+  }
+  if (sync.polling) {
+    return {
+      type: 'polling',
+      ...(sync.polling.pollIntervalMs !== undefined && {
+        pollInterval: sync.polling.pollIntervalMs / 1000,
+      }),
+      ...(sync.polling.baseUri && {
+        endpoints: { pollingBaseUri: sync.polling.baseUri },
+      }),
+    };
+  }
+  return undefined;
+}
+
+function translateModeDefinition(modeDef: SDKConfigModeDefinition): ModeDefinition {
+  const initializers: InitializerEntry[] = (modeDef.initializers ?? [])
+    .map(translateInitializer)
+    .filter((x): x is InitializerEntry => x !== undefined);
+
+  const synchronizers: SynchronizerEntry[] = (modeDef.synchronizers ?? [])
+    .map(translateSynchronizer)
+    .filter((x): x is SynchronizerEntry => x !== undefined);
+
+  return { initializers, synchronizers };
+}
+
 function makeSdkConfig(options: SDKConfigParams, tag: string) {
   if (!options.clientSide) {
     throw new Error('configuration did not include clientSide options');
@@ -23,7 +87,7 @@ function makeSdkConfig(options: SDKConfigParams, tag: string) {
   const cf: LDOptions = {
     withReasons: options.clientSide.evaluationReasons,
     logger: makeLogger(`${tag}.sdk`),
-    useReport: options.clientSide.useReport,
+    useReport: options.clientSide.useReport ?? undefined,
   };
 
   if (options.serviceEndpoints) {
@@ -32,21 +96,60 @@ function makeSdkConfig(options: SDKConfigParams, tag: string) {
     cf.eventsUri = options.serviceEndpoints.events;
   }
 
-  if (options.polling) {
-    if (options.polling.baseUri) {
-      cf.baseUri = options.polling.baseUri;
-    }
+  if (options.dataSystem?.payloadFilter) {
+    cf.payloadFilterKey = options.dataSystem.payloadFilter;
   }
 
-  // Can contain streaming and polling, if streaming is set override the initial connection
-  // mode. This can be removed when we add JS specific initialization that uses polling
-  // and then streaming.
-  if (options.streaming) {
-    if (options.streaming.baseUri) {
-      cf.streamUri = options.streaming.baseUri;
+  if (options.dataSystem) {
+    const dataSystem: any = {};
+
+    if (options.dataSystem.connectionModeConfig) {
+      const connMode = options.dataSystem.connectionModeConfig;
+      dataSystem.automaticModeSwitching = connMode.initialConnectionMode
+        ? { type: 'manual', initialConnectionMode: connMode.initialConnectionMode }
+        : false;
+
+      if (connMode.customConnectionModes) {
+        const connectionModes: Record<string, any> = {};
+        Object.entries(connMode.customConnectionModes).forEach(([modeName, modeDef]) => {
+          connectionModes[modeName] = translateModeDefinition(modeDef);
+
+          // Per-entry endpoint overrides also set global URIs for ServiceEndpoints
+          // compatibility. These override the serviceEndpoints values above.
+          (modeDef.synchronizers ?? []).forEach((sync) => {
+            if (sync.streaming?.baseUri) {
+              cf.streamUri = sync.streaming.baseUri;
+              cf.streamInitialReconnectDelay = maybeTime(sync.streaming.initialRetryDelayMs);
+            }
+            if (sync.polling?.baseUri) {
+              cf.baseUri = sync.polling.baseUri;
+            }
+          });
+          (modeDef.initializers ?? []).forEach((init) => {
+            if (init.polling?.baseUri) {
+              cf.baseUri = init.polling.baseUri;
+            }
+          });
+        });
+        dataSystem.connectionModes = connectionModes;
+      }
+    }
+
+    (cf as any).dataSystem = dataSystem;
+  } else {
+    if (options.polling) {
+      if (options.polling.baseUri) {
+        cf.baseUri = options.polling.baseUri;
+      }
+    }
+
+    if (options.streaming) {
+      if (options.streaming.baseUri) {
+        cf.streamUri = options.streaming.baseUri;
+      }
+      cf.streaming = true;
+      cf.streamInitialReconnectDelay = maybeTime(options.streaming.initialRetryDelayMs);
     }
-    cf.streaming = true;
-    cf.streamInitialReconnectDelay = maybeTime(options.streaming.initialRetryDelayMs);
   }
 
   if (options.events) {

packages/sdk/browser/contract-tests/suppressions_datamode_changes.txt

@@ -0,0 +1,45 @@
+streaming/requests/method and headers/REPORT/http
+streaming/requests/URL path is computed correctly/no environment filter/base URI has no trailing slash/REPORT
+streaming/requests/URL path is computed correctly/no environment filter/base URI has a trailing slash/REPORT
+streaming/requests/query parameters/evaluationReasons set to [none]/REPORT
+streaming/requests/query parameters/evaluationReasons set to false/REPORT
+streaming/requests/query parameters/evaluationReasons set to true/REPORT
+streaming/requests/context properties/single kind minimal/REPORT
+streaming/requests/context properties/single kind with all attributes/REPORT
+streaming/requests/context properties/multi-kind/REPORT
+polling/requests/method and headers/REPORT/http
+polling/requests/URL path is computed correctly/no environment filter/base URI has no trailing slash/REPORT
+polling/requests/URL path is computed correctly/no environment filter/base URI has a trailing slash/REPORT
+polling/requests/query parameters/evaluationReasons set to [none]/REPORT
+polling/requests/query parameters/evaluationReasons set to false/REPORT
+polling/requests/query parameters/evaluationReasons set to true/REPORT
+polling/requests/context properties/single kind minimal/REPORT
+polling/requests/context properties/single kind with all attributes/REPORT
+polling/requests/context properties/multi-kind/REPORT
+tags/stream requests/{"applicationId":null,"applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":null,"applicationVersion":"________________________________________________________________"}
+tags/stream requests/{"applicationId":"","applicationVersion":null}
+tags/stream requests/{"applicationId":"","applicationVersion":""}
+tags/stream requests/{"applicationId":"","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":"","applicationVersion":"________________________________________________________________"}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":null}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":""}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":"________________________________________________________________"}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":null}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":""}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":"________________________________________________________________"}
+tags/poll requests/{"applicationId":null,"applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/poll requests/{"applicationId":null,"applicationVersion":"________________________________________________________________"}
+tags/poll requests/{"applicationId":"","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/poll requests/{"applicationId":"","applicationVersion":"________________________________________________________________"}
+tags/poll requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":null}
+tags/poll requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":""}
+tags/poll requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/poll requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":"________________________________________________________________"}
+tags/poll requests/{"applicationId":"________________________________________________________________","applicationVersion":null}
+tags/poll requests/{"applicationId":"________________________________________________________________","applicationVersion":""}
+tags/poll requests/{"applicationId":"________________________________________________________________","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/poll requests/{"applicationId":"________________________________________________________________","applicationVersion":"________________________________________________________________"}
+tags/disallowed characters

packages/sdk/browser/example-fdv2/.env.template

@@ -0,0 +1,5 @@
+# Set LAUNCHDARKLY_CLIENT_SIDE_ID to your LaunchDarkly client-side ID
+LAUNCHDARKLY_CLIENT_SIDE_ID=
+
+# Set LAUNCHDARKLY_FLAG_KEY to the feature flag key you want to evaluate
+LAUNCHDARKLY_FLAG_KEY=

packages/sdk/browser/example-fdv2/README.md

@@ -0,0 +1,44 @@
+# LaunchDarkly sample javascript application
+
+We've built a simple browser application that demonstrates how this LaunchDarkly SDK works.
+
+Below, you'll find the build procedure. For more comprehensive instructions, you can visit your [Quickstart page](https://app.launchdarkly.com/quickstart#/) or
+the [{name of SDK} reference guide](https://docs.launchdarkly.com/sdk/client-side/javascript).
+
+## Prerequisites
+
+Nodejs 20.6.0 or later
+
+## Build instructions
+
+1. Make a copy of the `.env.template` and name it `.env`
+    ```
+    cp .env.template .env
+    ```
+
+2. Set the variables in `.env` to your specific LD values
+    ```
+    # Set LAUNCHDARKLY_CLIENT_SIDE_ID to your LaunchDarkly client-side ID
+    LAUNCHDARKLY_CLIENT_SIDE_ID=
+
+    # Set LAUNCHDARKLY_FLAG_KEY to the feature flag key you want to evaluate
+    LAUNCHDARKLY_FLAG_KEY=
+    ```
+    > [!NOTE]
+    > Setting these values is equivilent to modifying the `clientSideID` and `flagKey`
+    > in [app.ts](./src/app.ts).
+
+3. Install and build the project:
+    ```bash
+    yarn && yarn build
+    ```
+
+4. On the command line, run `yarn start`
+    ```bash
+    yarn start
+    ```
+    > [!NOTE]
+    > The `yarn start` script simply runs `open index.html`. If that is not working for you,
+    > you can open the `index.html` file in a browser for the same results.
+
+The application will run continuously and react to the flag changes in LaunchDarkly.

packages/sdk/browser/example-fdv2/e2e/verify.spec.ts

@@ -0,0 +1,9 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { expect, test as it } from '@playwright/test';
+
+it('evaluates the feature flag to true', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('body')).toContainText('feature flag evaluates to true', {
+    timeout: 20_000,
+  });
+});

packages/sdk/browser/example-fdv2/index.css

@@ -0,0 +1,69 @@
+body {
+  margin: 0;
+  padding: 20px;
+  background: #373841;
+  color: white;
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell',
+    'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+#status {
+  padding: 10px;
+  margin-bottom: 10px;
+  background: rgba(255,255,255,0.1);
+  border-radius: 4px;
+}
+
+#flag {
+  font-size: 1.4em;
+  padding: 15px;
+  margin-bottom: 20px;
+  background: rgba(255,255,255,0.05);
+  border-radius: 4px;
+}
+
+#controls {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 15px;
+}
+
+#controls > div {
+  padding: 10px;
+  background: rgba(255,255,255,0.05);
+  border-radius: 4px;
+}
+
+#controls h3 {
+  margin: 0 0 8px 0;
+  font-size: 0.9em;
+  text-transform: uppercase;
+  opacity: 0.7;
+}
+
+button {
+  padding: 6px 14px;
+  margin: 3px 2px;
+  border: 1px solid rgba(255,255,255,0.3);
+  border-radius: 4px;
+  background: rgba(255,255,255,0.1);
+  color: white;
+  cursor: pointer;
+  font-size: 0.9em;
+}
+
+button:hover {
+  background: rgba(255,255,255,0.2);
+}
+
+#log {
+  max-height: 200px;
+  overflow-y: auto;
+  font-family: monospace;
+  font-size: 0.8em;
+  line-height: 1.5;
+  opacity: 0.8;
+}

packages/sdk/browser/example-fdv2/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge;chrome=1">
+    <title>LaunchDarkly tutorial</title>
+     <script src="./dist/app.js" defer></script>
+    <link rel="stylesheet" href="./index.css">
+  </head>
+  <body></body>
+</html>

packages/sdk/browser/example-fdv2/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@launchdarkly/browser-example-fdv2",
+  "version": "0.0.0",
+  "private": true,
+  "description": "LaunchDarkly example for JavaScript Browser SDK",
+  "homepage": "https://github.com/launchdarkly/js-core/tree/main/packages/sdk/browser/example-fdv2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/launchdarkly/js-core.git"
+  },
+  "license": "Apache-2.0",
+  "packageManager": "yarn@3.4.1",
+  "type": "module",
+  "scripts": {
+    "start": "open index.html",
+    "clean": "rm -rf dist dist-static",
+    "build": "npm run clean && tsdown",
+    "test": "playwright test"
+  },
+  "dependencies": {
+    "@launchdarkly/js-client-sdk": "workspace:^"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.1",
+    "playwright": "^1.49.1",
+    "tsdown": "^0.17.0-beta.4",
+    "typescript": "^5.9.3"
+  }
+}