chore: Add Node platform abstraction for node-client (#1393)

## Summary
- Adds the Node platform abstraction layer for
`@launchdarkly/node-client-sdk`: `HeaderWrapper`, `NodeCrypto`,
`NodeEncoding`, `NodeInfo`, `NodePlatform`, `NodeRequests`,
`NodeResponse`, `NodeStorage`. These implement the `Platform` contract
from `@launchdarkly/js-client-sdk-common`.
- Adds runtime dependencies the platform code imports:
`@launchdarkly/js-client-sdk-common`, `https-proxy-agent`,
`launchdarkly-eventsource`.
- Modernizes `packages/sdk/node-client/tsconfig.json` to `module:
ESNext` + `moduleResolution: bundler` (tsup handles emit), adds
`esModuleInterop`, `types: ["jest", "node"]`, `skipLibCheck`. Matches
the pattern used by `packages/sdk/server-ai`.
- Part of the SDK-2195 stacked migration of
`launchdarkly-node-client-sdk` into js-core. Follows PR #1352
(scaffold).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> New TLS, HTTP streaming, and on-disk cache behavior affect runtime
networking and local persistence, though it is isolated behind platform
interfaces and covered by unit tests; the public client API is not wired
yet.
> 
> **Overview**
> Adds the **Node platform layer** for `@launchdarkly/node-client-sdk`
so the package can plug into `@launchdarkly/js-client-sdk-common`:
`NodePlatform` wires **info**, **crypto**, **encoding**, **file-backed
storage**, and **HTTP/HTTPS + EventSource** requests. New `NodeOptions`
covers **TLS** (`tlsParams`), optional **POST gzip** for events, and
**`localStoragePath`** (default `ldclient-user-cache`).
> 
> `NodeRequests` / `NodeResponse` implement fetch-like behavior
(timeouts, gzip on GET, optional body compression, custom CA for HTTPS)
via `launchdarkly-eventsource`. `NodeStorage` persists a JSON cache with
atomic writes and a process singleton.
> 
> Also adds **Jest** coverage for the platform modules, a
**`sdk/node-client` GitHub Actions** job (Node 18 & 22), package
**test** script and dependencies, **tsconfig** shift to `ESNext` /
`bundler`, and **release-please** bumping `NodeInfo.ts` for version
stamps.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
eb89832. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joker23

.github/workflows/node-client.yml

@@ -0,0 +1,34 @@
+name: sdk/node-client
+
+on:
+  push:
+    branches: [main, 'feat/**']
+    paths-ignore:
+      - '**.md' #Do not need to run CI for markdown changes.
+  pull_request:
+    branches: [main, 'feat/**']
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build-test-node-client:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        # Node versions to run on.
+        version: [18, 22]
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.version }}
+          registry-url: 'https://registry.npmjs.org'
+      - id: shared
+        name: Shared CI Steps
+        uses: ./actions/ci
+        with:
+          workspace_name: '@launchdarkly/node-client-sdk'
+          workspace_path: packages/sdk/node-client
+      # TODO: Add contract tests

packages/sdk/node-client/.gitignore

@@ -0,0 +1,2 @@
+# Default cache directory name
+ldclient-user-cache/

packages/sdk/node-client/__tests__/platform/HeaderWrapper.test.ts

@@ -0,0 +1,51 @@
+import HeaderWrapper from '../../src/platform/HeaderWrapper';
+
+it('returns the header value when present', () => {
+  const wrapper = new HeaderWrapper({ 'content-type': 'application/json' });
+  expect(wrapper.get('content-type')).toBe('application/json');
+});
+
+it('returns null when the header is absent', () => {
+  const wrapper = new HeaderWrapper({});
+  expect(wrapper.get('missing')).toBeNull();
+});
+
+it('joins array-valued headers with a comma separator', () => {
+  const wrapper = new HeaderWrapper({ 'set-cookie': ['a=1', 'b=2'] });
+  expect(wrapper.get('set-cookie')).toBe('a=1, b=2');
+});
+
+it('returns null when a header is explicitly undefined', () => {
+  const wrapper = new HeaderWrapper({ 'x-empty': undefined });
+  expect(wrapper.get('x-empty')).toBeNull();
+});
+
+it('iterates keys, values, and entries', () => {
+  const wrapper = new HeaderWrapper({
+    'content-type': 'application/json',
+    'set-cookie': ['a=1', 'b=2'],
+  });
+
+  expect(Array.from(wrapper.keys()).sort()).toEqual(['content-type', 'set-cookie']);
+  expect(Array.from(wrapper.values()).sort()).toEqual(['a=1, b=2', 'application/json']);
+  expect(Array.from(wrapper.entries()).sort()).toEqual([
+    ['content-type', 'application/json'],
+    ['set-cookie', 'a=1, b=2'],
+  ]);
+});
+
+it('skips undefined headers when iterating values and entries', () => {
+  const wrapper = new HeaderWrapper({
+    'content-type': 'application/json',
+    'x-empty': undefined,
+  });
+
+  expect(Array.from(wrapper.values())).toEqual(['application/json']);
+  expect(Array.from(wrapper.entries())).toEqual([['content-type', 'application/json']]);
+});
+
+it('reports presence with has()', () => {
+  const wrapper = new HeaderWrapper({ 'content-type': 'application/json' });
+  expect(wrapper.has('content-type')).toBe(true);
+  expect(wrapper.has('missing')).toBe(false);
+});

packages/sdk/node-client/__tests__/platform/NodeCrypto.test.ts

@@ -0,0 +1,40 @@
+import NodeCrypto from '../../src/platform/NodeCrypto';
+
+it('produces a sha256 digest matching the known fixture', () => {
+  const crypto = new NodeCrypto();
+  const hasher = crypto.createHash('sha256');
+  hasher.update('the quick brown fox');
+  expect(hasher.digest!('hex')).toBe(
+    '9ecb36561341d18eb65484e833efea61edc74b84cf5e6ae1b81c63533e25fc8f',
+  );
+});
+
+it('produces a deterministic hmac digest for the same key and message', () => {
+  const crypto = new NodeCrypto();
+  const hmacA = crypto.createHmac!('sha256', 'key');
+  hmacA.update('message');
+  const hmacB = crypto.createHmac!('sha256', 'key');
+  hmacB.update('message');
+  expect(hmacA.digest('hex')).toBe(hmacB.digest('hex'));
+});
+
+it('produces different hmac digests for different keys', () => {
+  const crypto = new NodeCrypto();
+  const hmacA = crypto.createHmac!('sha256', 'keyA');
+  hmacA.update('message');
+  const hmacB = crypto.createHmac!('sha256', 'keyB');
+  hmacB.update('message');
+  expect(hmacA.digest('hex')).not.toBe(hmacB.digest('hex'));
+});
+
+it('generates a UUID matching the v4 format', () => {
+  const crypto = new NodeCrypto();
+  expect(crypto.randomUUID()).toMatch(
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  );
+});
+
+it('generates distinct UUIDs across calls', () => {
+  const crypto = new NodeCrypto();
+  expect(crypto.randomUUID()).not.toBe(crypto.randomUUID());
+});

packages/sdk/node-client/__tests__/platform/NodeEncoding.test.ts

@@ -0,0 +1,18 @@
+import NodeEncoding from '../../src/platform/NodeEncoding';
+
+it('can base64 a basic ASCII string', () => {
+  const encoding = new NodeEncoding();
+  expect(encoding.btoa('toaster')).toEqual('dG9hc3Rlcg==');
+});
+
+it('can base64 a unicode string containing multi-byte characters', () => {
+  const encoding = new NodeEncoding();
+  expect(encoding.btoa('✇⽊❽⾵⊚▴ⶊ↺➹≈⋟⚥⤅⊈ⲏⷨ⾭Ⲗ⑲▯ⶋₐℛ⬎⿌🦄')).toEqual(
+    '4pyH4r2K4p294r614oqa4pa04raK4oa64p654omI4ouf4pql4qSF4oqI4rKP4reo4r6t4rKW4pGy4pav4raL4oKQ4oSb4qyO4r+M8J+mhA==',
+  );
+});
+
+it('returns an empty string when input is empty', () => {
+  const encoding = new NodeEncoding();
+  expect(encoding.btoa('')).toEqual('');
+});

packages/sdk/node-client/__tests__/platform/NodeInfo.test.ts

@@ -0,0 +1,61 @@
+import * as os from 'os';
+
+import NodeInfo from '../../src/platform/NodeInfo';
+
+const realOs = jest.requireActual('os');
+
+jest.mock('os', () => {
+  const actual = jest.requireActual('os');
+  return {
+    ...actual,
+    platform: jest.fn(actual.platform),
+    release: jest.fn(actual.release),
+    arch: jest.fn(actual.arch),
+  };
+});
+
+const mockedOs = jest.mocked(os);
+
+afterEach(() => {
+  mockedOs.platform.mockImplementation(realOs.platform);
+  mockedOs.release.mockImplementation(realOs.release);
+  mockedOs.arch.mockImplementation(realOs.arch);
+});
+
+it('returns sdk data with the package name, version, and user-agent base', () => {
+  const info = new NodeInfo();
+  expect(info.sdkData()).toEqual({
+    name: 'node-client-sdk',
+    version: '0.0.1',
+    userAgentBase: 'NodeClient',
+  });
+});
+
+it('reports the runtime node version under platformData additional', () => {
+  const info = new NodeInfo();
+  const data = info.platformData();
+  expect(data.name).toBe('Node');
+  expect(data.additional?.nodeVersion).toBe(process.versions.node);
+});
+
+it.each([
+  ['darwin', 'MacOS'],
+  ['win32', 'Windows'],
+  ['linux', 'Linux'],
+])('maps the %s os platform to %s', (raw, mapped) => {
+  mockedOs.platform.mockReturnValue(raw as NodeJS.Platform);
+  mockedOs.release.mockReturnValue('1.2.3');
+  mockedOs.arch.mockReturnValue('x64');
+
+  const info = new NodeInfo();
+  expect(info.platformData().os).toEqual({ name: mapped, version: '1.2.3', arch: 'x64' });
+});
+
+it('passes through an unknown os platform name', () => {
+  mockedOs.platform.mockReturnValue('freebsd' as NodeJS.Platform);
+  mockedOs.release.mockReturnValue('14.0');
+  mockedOs.arch.mockReturnValue('arm64');
+
+  const info = new NodeInfo();
+  expect(info.platformData().os).toEqual({ name: 'freebsd', version: '14.0', arch: 'arm64' });
+});

packages/sdk/node-client/__tests__/platform/NodePlatform.test.ts

@@ -0,0 +1,49 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+
+import { createMockLogger } from '../testHelpers';
+import { resetNodeStorage } from '../../src/platform/NodeStorage';
+import NodePlatform from '../../src/platform/NodePlatform';
+
+let tmpRoot: string;
+let logger: ReturnType<typeof createMockLogger>;
+
+beforeEach(async () => {
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'node-platform-test-'));
+  resetNodeStorage();
+  logger = createMockLogger();
+});
+
+afterEach(async () => {
+  resetNodeStorage();
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+it('exposes info, crypto, encoding, storage, and requests', () => {
+  const platform = new NodePlatform(logger, { localStoragePath: tmpRoot });
+  expect(platform.info).toBeDefined();
+  expect(platform.crypto).toBeDefined();
+  expect(platform.encoding).toBeDefined();
+  expect(platform.storage).toBeDefined();
+  expect(platform.requests).toBeDefined();
+});
+
+it('round-trips storage values through the file-backed NodeStorage', async () => {
+  const platform = new NodePlatform(logger, { localStoragePath: tmpRoot });
+  await platform.storage.set('alpha', 'one');
+  await expect(platform.storage.get('alpha')).resolves.toBe('one');
+  await platform.storage.clear('alpha');
+  await expect(platform.storage.get('alpha')).resolves.toBeNull();
+});
+
+it('forwards the logger to NodeStorage so storage failures surface', async () => {
+  const platform = new NodePlatform(logger, {
+    localStoragePath: path.join(tmpRoot, 'never-created', '\0bad'),
+  });
+  await expect(platform.storage.get('alpha')).resolves.toBeNull();
+  expect(logger.error).toHaveBeenCalledWith(
+    expect.stringContaining('Error getting key from storage'),
+  );
+});
+