feat: add server-side TestHook and migrate server-node/shopify-oxygen to shared utils [SDK-2009] (#1168)

**Requirements**

- [ ] I have added test coverage for new or changed functionality
- [ ] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [ ] I have validated my changes against all supported platform
versions

**Related issues**

- [SDK-2009](https://launchdarkly.atlassian.net/browse/SDK-2009) — Add
server-side TestHook and ClientPool to contract-test-utils
- Subtask 2 of
[SDK-1866](https://launchdarkly.atlassian.net/browse/SDK-1866)

**Describe the solution you've provided**

Moves the server-node `TestHook` (which uses `got` for HTTP callbacks)
into the shared `@launchdarkly/js-contract-test-utils` package and
migrates both server-node and Shopify Oxygen contract tests to use
shared infrastructure. Also deduplicates shared types (command params,
config params) so both client and server contract tests consume them
from the shared package.

**Changes to `packages/tooling/contract-test-utils/`:**

- `src/server-side/TestHook.ts` — moved from server-node contract tests
(exact rename, no content changes)
- `src/server.ts` — barrel re-exporting from `./index.js` plus
`ServerSideTestHook` (mirrors `client.ts` pattern)
- `src/client.ts` / `src/index.ts` — barrel exports using `.js`
extensions (required for compiled ESM output)
- `src/types/compat.ts` — minimal `LDContext`, `LDEvaluationReason`, and
`LDLogger` type definitions compatible with both client and server SDKs,
allowing shared code to avoid importing from either SDK directly
- `src/types/CommandParams.ts` — imports from `compat.ts`; includes both
client and server command fields (e.g. `migrationVariation`,
`registerFlagChangeListener`)
- `src/types/ConfigParams.ts` — same pattern; includes both `clientSide`
and server-specific fields (`bigSegments`, `dataSystem`)
- `src/logging/makeLogger.ts` — now imports `LDLogger` from `compat.ts`
instead of `@launchdarkly/js-client-sdk-common`
- `package.json`:
- All three subpath exports (`.`, `./client`, `./server`) point to
compiled `dist/` output
- Three build scripts: `build` (universal only), `build:client` (client
+ universal), `build:server` (server + universal)
- `got` and `@launchdarkly/node-server-sdk` added as **optional peer
dependencies**

**Three-tier TypeScript build configuration:**

- `tsconfig.json` (base) — excludes **both** TestHook files and barrel
files (`client.ts`, `server.ts`). Compiles only universal code with zero
SDK dependencies. Used by `build` script.
- `tsconfig.client.json` — extends base, re-includes client files,
excludes server files. Requires `@launchdarkly/js-client-sdk-common`.
Used by `build:client` script.
- `tsconfig.server.json` — extends base, re-includes server files,
excludes client files. Requires `@launchdarkly/node-server-sdk` + `got`.
Used by `build:server` script.

**Migrations:**

- **server-node**: 
- Deleted local `TestHook.ts`; imports `ServerSideTestHook` from shared
package
- Replaced inline `clientCounter` + `Record<string, SdkClientEntity>` in
`index.ts` with shared `ClientPool<SdkClientEntity>`
- Imported `CommandParams`, `CreateInstanceParams`, `SDKConfigParams`
from shared package (~130 lines of duplicated local type definitions
removed)
- Added type casts where shared types use `unknown` or `string` but SDK
expects specific types (e.g., `pe.defaultValue as boolean`,
`migrationVariation.context as LDContext`,
`migrationVariation.defaultStage as LDMigrationStage`)
- **Shopify Oxygen**: 
- Replaced inline `Record<string, LDClient>` + counter with shared
`ClientPool<LDClient>`
  - Updated JSDoc comment to be more general (not Shopify-specific)
- Added `noExternal` to `tsup.config.ts` to bundle shared package inline
- Client IDs changed from `"client-1"` to `"1"` (auto-generated by
`ClientPool.add()`)

**CI Workflow Updates:**


- `.github/workflows/browser.yml` — added `build:client` step before
contract test adapter build
- `.github/workflows/electron.yaml` — added `build:client` step before
contract tests entity build
- `.github/workflows/react-native-contract-tests.yml` — added
`build:client` step before contract test adapter build
- `.github/workflows/react.yaml` — added `build:client` step **before**
topological build (must run before Next.js/Turbopack resolves imports)
- `.github/workflows/server-node.yml` — added `build:server` step before
contract test build
- `.github/workflows/shopify-oxygen.yml` — added `build` step before
contract test build

**Build command matrix by CI environment:**
- **Universal only** (`build`): shopify-oxygen — has no SDK dependencies
- **Client + universal** (`build:client`): browser, electron,
react-native, react — have `@launchdarkly/js-client-sdk-common` but not
`got`/`node-server-sdk`
- **Server + universal** (`build:server`): server-node — has
`@launchdarkly/node-server-sdk` + `got` but may lack client SDK

**Updates since last revision:**

Implemented three-tier TypeScript build configuration to handle
different SDK dependency profiles across CI environments:

1. **Split `tsconfig.json` into three configs**: Base config now
excludes both client and server TestHook files, making it universal-only
(zero SDK dependencies). New `tsconfig.client.json` and
`tsconfig.server.json` extend base and selectively re-include their
respective files.

2. **Added `build:client` script**: Browser/Electron/React-Native/React
CI workflows now explicitly run `build:client` to compile
`dist/client.js`, which was missing when they ran the default `build`
script (universal only).

3. **Shopify Oxygen uses universal build**: Changed from `build:server`
to `build` since Shopify Oxygen only imports from the base package (no
subpath), not `/server`.

4. **Fixed React workflow build ordering**: Moved `build:client` to run
**before** the topological `yarn workspaces foreach ... run build`
because the React contract tests' Next.js/Turbopack build happens during
that step and needs `dist/client.js` to already exist when resolving
`@launchdarkly/js-contract-test-utils/client` imports.

This fixes CI failures where different environments tried to compile
code that imported SDKs not installed in their focused dependency trees
(e.g., React CI trying to compile server-side TestHook which imports
`got`).

**⚠️ Items for reviewer attention:**

1. **Compat types pattern**: Types use minimal compatible definitions
(`LDContext = Record<string, any>`, `LDLogger = { error(...), warn(...),
... }`) to avoid importing from SDK packages directly. This allows one
unified set of type files to work for both client and server, but
requires consumers to add explicit casts when passing values to SDK
methods.

2. **Type safety tradeoff**: The casts in `sdkClientEntity.ts` could
mask real type errors if the contract test harness sends incorrect
types. However, this follows the pattern from PR #1151 which was already
merged and validated. Notable casts:
   - `pe.defaultValue as boolean | number | string` (3 locations)
   - `migrationVariation.context as LDContext` (1 location)
   - `migrationOperation.context as LDContext` (2 locations)
   - `params.identifyEvent!.context as LDContext` (1 location)
   - `migrationVariation.defaultStage as LDMigrationStage` (3 locations)

3. **Three-tsconfig approach**: Each CI environment must use its
appropriate build script. Using the wrong script causes "Cannot find
module" errors. Future files must be added to the appropriate tsconfig
exclusion lists.

4. **CI environment requirements**: 
- Browser/Electron/React-Native/React: use `build:client` (client deps
available, server deps missing)
- Server-node: use `build:server` (server deps available, client deps
may be missing)
   - Shopify-oxygen: use `build` (universal only, minimal deps)

5. **ClientPool API change**: `ClientPool.add(client)` now
auto-generates and returns the client ID instead of requiring an
explicit ID. Shopify Oxygen client IDs changed from `"client-1"` to
`"1"`. CI contract tests pass, confirming the test harness handles this
correctly.

6. **`got` path mapping**: `tsconfig.json` uses a hardcoded relative
path (`"../../../node_modules/got/dist/source"`) which is fragile and
depends on Yarn's hoisting layout. This is a workaround because
`@launchdarkly/js-client-sdk-common` doesn't work with `node16` module
resolution while `got` v14 requires it.

7. **React workflow build ordering is critical**: The `build:client`
step must run **before** the topological `yarn workspaces foreach ...
run build` because Next.js/Turbopack resolves the
`@launchdarkly/js-contract-test-utils/client` import during the contract
tests build. If `dist/client.js` doesn't exist yet, Turbopack fails with
"Module not found".


**Describe alternatives you've considered**

- **Three-tier type architecture** (universal/client/server split into
separate directories) — initially implemented but reverted in favor of
the simpler compat.ts pattern from PR #1151, which uses one unified set
of type files with minimal compatible type definitions
- **Asymmetric exports** (client from source, server from dist) —
attempted but couldn't make it work reliably across all CI environments;
unified dist/ approach with explicit build steps is more maintainable
- **Two-tsconfig approach** (just base + server) — didn't work because
client CI environments tried to compile universal files that imported
from `@launchdarkly/js-client-sdk-common`, causing peer dependency
warnings and potential issues. Three tiers (universal/client/server)
cleanly separates concerns.

**Additional context**


Link to Devin Session:
https://app.devin.ai/sessions/f0a2bd3c755e49c3b639bd3ee770effe
Requested by: @joker23

No test coverage added in this PR — the existing contract test suites
serve as integration tests for the shared utilities.

**CI Status:** ✅ All 41/41 checks passing


[SDK-2009]:
https://launchdarkly.atlassian.net/browse/SDK-2009?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
[SDK-1866]:
https://launchdarkly.atlassian.net/browse/SDK-1866?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1168"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Moderate risk due to changes in contract-test build/export plumbing
and runtime wiring (new compiled `dist` exports, new `ClientPool` IDs,
moved hook implementation) that can break CI or contract test harness
interactions if misconfigured.
> 
> **Overview**
> Centralizes contract test shared code by turning
`@launchdarkly/js-contract-test-utils` into a compiled `dist/` package
with new `./client` and `./server` entrypoints, a shared `BaseTestHook`,
a new server-side `TestHook` (using `got`), and expanded shared
config/command types using SDK-agnostic *compat* types.
> 
> Migrates server-side contract test services (`server-node` and
`shopify-oxygen`) to use the shared `ClientPool` and shared types/hooks,
removing the server-node local `TestHook` and updating client ID
generation/handling.
> 
> Updates multiple CI workflows to explicitly build the appropriate
contract-test-utils variant (`build:client` or `build:server`) before
building/running contract tests, and adjusts Shopify Oxygen bundling to
include the shared utils.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
850f7d5. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: joker23

.github/workflows/browser.yml

@@ -50,6 +50,9 @@ jobs:
       - name: Install Playwright browsers
         run: yarn workspace browser-contract-test-service install-playwright-browsers
 
+      - name: Build shared contract test utils
+        run: yarn workspace @launchdarkly/js-contract-test-utils build:client
+
       - name: Build contract test adapter
         run: yarn workspace browser-contract-test-adapter run build
 

.github/workflows/electron.yaml

@@ -40,6 +40,7 @@ jobs:
           ELECTRON_DISABLE_SANDBOX: '1'
         run: |
           yarn workspaces focus @internal/electron-contract-tests-entity
+          yarn workspace @launchdarkly/js-contract-test-utils build:client
           yarn workspace @internal/electron-contract-tests-entity build
           sudo apt-get install -y xvfb
           Xvfb :99 -screen 0 1024x768x24 > /tmp/xvfb.log 2>&1 &

.github/workflows/react-native-contract-tests.yml

@@ -33,6 +33,9 @@ jobs:
       - name: Build SDK and dependencies
         run: yarn workspaces foreach -pR --topological-dev --from '@launchdarkly/react-native-client-sdk' run build
 
+      - name: Build shared contract test utils
+        run: yarn workspace @launchdarkly/js-contract-test-utils build:client
+
       - name: Build contract test adapter
         run: yarn workspace react-native-contract-test-adapter run build
 

.github/workflows/react.yaml

@@ -39,8 +39,7 @@ jobs:
           yarn workspaces foreach -pR --topological-dev --from "@launchdarkly/react-sdk-contract-tests" install
           yarn workspaces foreach -pR --topological-dev --from 'browser-contract-test-adapter' run build
           yarn workspaces foreach -pR --topological-dev --from "@launchdarkly/react-sdk-contract-tests" run build
-      - name: Install Playwright browsers
-        run: yarn workspace @launchdarkly/react-sdk-contract-tests install-playwright-browsers
+          yarn workspace @launchdarkly/react-sdk-contract-tests install-playwright-browsers
       - name: Run test adapter
         run: |
           yarn workspace @launchdarkly/react-sdk-contract-tests run start:adapter > /tmp/adapter.log 2>&1 &

.github/workflows/server-node.yml

@@ -33,6 +33,8 @@ jobs:
           workspace_path: packages/sdk/server-node
       - name: Install contract test service dependencies
         run: yarn workspace node-server-sdk-contract-tests install --no-immutable
+      - name: Build shared contract test utils (server)
+        run: yarn workspace @launchdarkly/js-contract-test-utils build:server
       - name: Build the test service
         run: yarn workspace node-server-sdk-contract-tests build
       - name: Launch the test service in the background

.github/workflows/shopify-oxygen.yml

@@ -28,6 +28,8 @@ jobs:
           workspace_path: packages/sdk/shopify-oxygen
       - name: Install contract test service dependencies
         run: yarn workspace @launchdarkly/shopify-oxygen-contract-tests install --no-immutable
+      - name: Build shared contract test utils
+        run: yarn workspace @launchdarkly/js-contract-test-utils build:server
       - name: Build the test service
         run: yarn workspace @launchdarkly/shopify-oxygen-contract-tests build
       - name: Launch the test service in the background

packages/sdk/server-node/contract-tests/package.json

@@ -12,6 +12,7 @@
   "license": "Apache-2.0",
   "private": true,
   "dependencies": {
+    "@launchdarkly/js-contract-test-utils": "workspace:^",
     "@launchdarkly/node-server-sdk": "workspace:^",
     "body-parser": "^1.19.0",
     "express": "^4.17.1",

packages/sdk/server-node/contract-tests/src/TestHook.ts

@@ -2,6 +2,8 @@ import bodyParser from 'body-parser';
 import express, { Request, Response } from 'express';
 import { Server } from 'http';
 
+import { ClientPool } from '@launchdarkly/js-contract-test-utils/server';
+
 import { Log } from './log.js';
 import { badCommandError, newSdkClientEntity, SdkClientEntity } from './sdkClientEntity.js';
 
@@ -10,8 +12,7 @@ let server: Server | null = null;
 
 const port = 8000;
 
-let clientCounter = 0;
-const clients: Record<string, SdkClientEntity> = {};
+const clients = new ClientPool<SdkClientEntity>();
 
 const mainLog = Log('service');
 
@@ -66,16 +67,12 @@ app.delete('/', (req: Request, res: Response) => {
 app.post('/', async (req: Request, res: Response) => {
   const options = req.body;
 
-  clientCounter += 1;
-  const clientId = clientCounter.toString();
-  const resourceUrl = `/clients/${clientId}`;
-
   try {
     const client = await newSdkClientEntity(options);
-    clients[clientId] = client;
+    const clientId = clients.add(client);
 
     res.status(201);
-    res.set('Location', resourceUrl);
+    res.set('Location', `/clients/${clientId}`);
   } catch (e) {
     res.status(500);
     const message = e instanceof Error ? e.message : JSON.stringify(e);
@@ -86,7 +83,7 @@ app.post('/', async (req: Request, res: Response) => {
 });
 
 app.post('/clients/:id', async (req: Request, res: Response) => {
-  const client = clients[req.params.id];
+  const client = clients.get(req.params.id);
   if (!client) {
     res.status(404);
   } else {
@@ -113,13 +110,13 @@ app.post('/clients/:id', async (req: Request, res: Response) => {
 });
 
 app.delete('/clients/:id', async (req: Request, res: Response) => {
-  const client = clients[req.params.id];
+  const client = clients.get(req.params.id);
   if (!client) {
     res.status(404);
     res.send();
   } else {
     client.close();
-    delete clients[req.params.id];
+    clients.remove(req.params.id);
     res.status(204);
     res.send();
   }