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

[joker23]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

• SDK-2009 — Add server-side TestHook and ClientPool to contract-test-utils
• Subtask 2 of 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 feat: create shared contract test utilities package (SDK-1866) #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 feat: create shared contract test utilities package (SDK-1866) #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

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25566 bytes
Compressed size limit: 26000
Uncompressed size: 125383 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 24534 bytes
Compressed size limit: 25000
Uncompressed size: 84907 bytes

[github-actions]

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 172466 bytes
Compressed size limit: 200000
Uncompressed size: 802026 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 22062 bytes
Compressed size limit: 24000
Uncompressed size: 114438 bytes