@splitsoftware/openfeature-js-split-provider 1.1.0 → 1.3.0

package/lib/lib/parsers.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseValidJsonObject = exports.parseValidNumber = void 0;
+const server_sdk_1 = require("@openfeature/server-sdk");
+function parseValidNumber(stringValue) {
+    if (stringValue === undefined) {
+        throw new server_sdk_1.ParseError(`Invalid 'undefined' value.`);
+    }
+    const result = Number.parseFloat(stringValue);
+    if (Number.isNaN(result)) {
+        throw new server_sdk_1.ParseError(`Invalid numeric value ${stringValue}`);
+    }
+    return result;
+}
+exports.parseValidNumber = parseValidNumber;
+function parseValidJsonObject(stringValue) {
+    if (stringValue === undefined) {
+        throw new server_sdk_1.ParseError(`Invalid 'undefined' JSON value.`);
+    }
+    try {
+        const value = JSON.parse(stringValue);
+        if (typeof value !== 'object') {
+            throw new server_sdk_1.ParseError(`Flag value ${stringValue} had unexpected type ${typeof value}, expected "object"`);
+        }
+        return value;
+    }
+    catch (err) {
+        throw new server_sdk_1.ParseError(`Error parsing ${stringValue} as JSON, ${err}`);
+    }
+}
+exports.parseValidJsonObject = parseValidJsonObject;

package/lib/lib/readiness.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitReadyEvent = exports.waitUntilReady = exports.attachReadyEventHandlers = void 0;
+const server_sdk_1 = require("@openfeature/server-sdk");
+const types_1 = require("./types");
+/**
+ * Builds OpenFeature Ready event details including Split SDK ready metadata.
+ * Handles Split SDK not passing metadata (e.g. in consumer/Redis mode).
+ */
+function buildReadyEventDetails(providerName, splitMetadata, readyFromCache) {
+    const metadata = {
+        readyFromCache,
+        initialCacheLoad: splitMetadata?.initialCacheLoad ?? false,
+    };
+    if (splitMetadata?.lastUpdateTimestamp != null) {
+        metadata.lastUpdateTimestamp = splitMetadata.lastUpdateTimestamp;
+    }
+    return {
+        providerName: providerName || types_1.PROVIDER_NAME,
+        metadata,
+    };
+}
+/**
+ * Registers Split SDK_READY and SDK_READY_FROM_CACHE listeners and forwards them
+ * as OpenFeature ProviderEvents.Ready with event metadata (initialCacheLoad, lastUpdateTimestamp, readyFromCache).
+ * If the client is already ready when attaching (e.g. localhost or reused client), emits Ready once
+ * with best-effort metadata so handlers always receive at least one Ready when the client is ready.
+ */
+function attachReadyEventHandlers(client, events, providerName = types_1.PROVIDER_NAME) {
+    client.on(client.Event.SDK_READY_FROM_CACHE, (splitMetadata) => {
+        events.emit(server_sdk_1.ProviderEvents.Ready, buildReadyEventDetails(providerName, splitMetadata, true));
+    });
+    client.on(client.Event.SDK_READY, (splitMetadata) => {
+        events.emit(server_sdk_1.ProviderEvents.Ready, buildReadyEventDetails(providerName, splitMetadata, false));
+    });
+    const status = client.getStatus();
+    if (status.isReady) {
+        events.emit(server_sdk_1.ProviderEvents.Ready, buildReadyEventDetails(providerName, undefined, false));
+    }
+}
+exports.attachReadyEventHandlers = attachReadyEventHandlers;
+/**
+ * Returns a promise that resolves when the Split client is ready (SDK_READY),
+ * or rejects if the client has timed out (SDK_READY_TIMED_OUT).
+ * Used to gate evaluations until the SDK has synchronized with the backend.
+ */
+function waitUntilReady(client, events, providerName = types_1.PROVIDER_NAME) {
+    return new Promise((resolve, reject) => {
+        const status = client.getStatus();
+        if (status.isReady) {
+            emitReadyEvent(client, events, providerName);
+            resolve();
+            return;
+        }
+        if (status.hasTimedout) {
+            reject();
+            return;
+        }
+        client.on(client.Event.SDK_READY_TIMED_OUT, reject);
+        client.on(client.Event.SDK_READY, () => {
+            emitReadyEvent(client, events, providerName);
+            resolve();
+        });
+    });
+}
+exports.waitUntilReady = waitUntilReady;
+function emitReadyEvent(client, events, providerName = types_1.PROVIDER_NAME) {
+    events.emit(server_sdk_1.ProviderEvents.Ready, buildReadyEventDetails(providerName, undefined, false));
+}
+exports.emitReadyEvent = emitReadyEvent;

package/lib/lib/types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_NAME = exports.DEFAULT_TRAFFIC_TYPE = exports.CONTROL_VALUE_ERROR_MESSAGE = exports.CONTROL_TREATMENT = void 0;
+exports.CONTROL_TREATMENT = 'control';
+exports.CONTROL_VALUE_ERROR_MESSAGE = 'Received the "control" value from Split.';
+exports.DEFAULT_TRAFFIC_TYPE = 'user';
+exports.PROVIDER_NAME = 'split';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/openfeature-js-split-provider",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Split OpenFeature Provider",
   "files": [
     "README.md",
@@ -34,14 +34,16 @@
       "import": "./es/index.js"
     }
   },
+  "dependencies": {
+    "@splitsoftware/splitio": "^11.10.0"
+  },
   "peerDependencies": {
-    "@openfeature/server-sdk": "^1.19.0",
-    "@splitsoftware/splitio": "^11.4.1"
+    "@openfeature/server-sdk": "^1.20.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",
-    "@openfeature/server-sdk": "^1.19.0",
-    "@splitsoftware/splitio": "^11.4.1",
+    "@openfeature/server-sdk": "^1.20.0",
+    "@splitsoftware/splitio": "^11.10.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.3.1",
     "copyfiles": "^2.4.1",

package/src/__tests__/nodeSuites/client.spec.js

@@ -1,9 +1,8 @@
 /* eslint-disable jest/no-conditional-expect */
+import { OpenFeature, ProviderEvents } from '@openfeature/server-sdk';
 import { OpenFeatureSplitProvider } from '../../lib/js-split-provider';
 import { getLocalHostSplitClient, getSplitFactory } from '../testUtils';
 
-import { OpenFeature } from '@openfeature/server-sdk';
-
 const cases = [
   [
     'openfeature client tests mode: splitClient',
@@ -119,6 +118,22 @@ describe.each(cases)('%s', (label, getOptions) => {
     expect(client.metadata.name).toBe('test');
   });
 
+  test('Ready event includes Split metadata (readyFromCache, initialCacheLoad)', async () => {
+    const readyDetails = [];
+    const testProvider = new OpenFeatureSplitProvider(options);
+    testProvider.events.addHandler(ProviderEvents.Ready, (details) => readyDetails.push(details));
+    await OpenFeature.setProviderAndWait(testProvider);
+    expect(readyDetails.length).toBeGreaterThanOrEqual(1);
+    const withMetadata = readyDetails.find((d) => d && d.metadata);
+    expect(withMetadata).toBeDefined();
+    expect(withMetadata.providerName).toBe('split');
+    expect(typeof withMetadata.metadata.readyFromCache).toBe('boolean');
+    expect(typeof withMetadata.metadata.initialCacheLoad).toBe('boolean');
+    if (withMetadata.metadata.lastUpdateTimestamp != null) {
+      expect(typeof withMetadata.metadata.lastUpdateTimestamp).toBe('number');
+    }
+  });
+
   test('evaluate Boolean without details test', async () => {
     let details = await client.getBooleanDetails('some_other_feature', true);
     expect(details.flagKey).toBe('some_other_feature');

package/src/__tests__/nodeSuites/client_redis.spec.js

@@ -32,25 +32,24 @@ const startRedis = () => {
   return promise;
 };
 
-let redisServer
-let splitClient
+let redisServer;
+let splitClient;
+let client;
 
 beforeAll(async () => {
   redisServer = await startRedis();
+  splitClient = getRedisSplitClient(redisPort);
+  const provider = new OpenFeatureSplitProvider({ splitClient });
+  await OpenFeature.setProviderAndWait(provider);
+  client = OpenFeature.getClient();
 }, 30000);
 
 afterAll(async () => {
-  await redisServer.close();
-  await splitClient.destroy();
+  if (redisServer) await redisServer.close();
+  if (splitClient && typeof splitClient.destroy === 'function') await splitClient.destroy();
 });
 
 describe('Regular usage - DEBUG strategy', () => {
-  splitClient = getRedisSplitClient(redisPort);
-  const provider = new OpenFeatureSplitProvider({ splitClient });
-
-  OpenFeature.setProviderAndWait(provider);
-  const client = OpenFeature.getClient();
-  
   test('Evaluate always on flag', async () => {
     await client.getBooleanValue('always-on', false, {targetingKey: 'emma-ss'}).then(result => {
       expect(result).toBe(true);

package/src/__tests__/nodeSuites/provider.spec.js

@@ -1,4 +1,5 @@
 /* eslint-disable jest/no-conditional-expect */
+import { ProviderEvents } from '@openfeature/server-sdk';
 import { getLocalHostSplitClient, getSplitFactory } from '../testUtils';
 import { OpenFeatureSplitProvider } from '../../lib/js-split-provider';
 
@@ -239,3 +240,75 @@ describe.each(cases)('%s', (label, getOptions) => {
     expect(trackSpy).toHaveBeenCalledWith('u1', 'user', 'purchase', 9.99, { plan: 'pro', beta: true });
   });
 });
+
+describe('provider events metadata', () => {
+  const SDK_UPDATE = 'state::update';
+
+  function createMockSplitClient() {
+    const listeners = {};
+    const mock = {
+      Event: { SDK_UPDATE },
+      getStatus: jest.fn().mockReturnValue({ isReady: true, hasTimedout: false }),
+      getTreatmentWithConfig: jest.fn().mockResolvedValue({ treatment: 'on', config: '' }),
+      on: jest.fn((event, cb) => {
+        listeners[event] = listeners[event] || [];
+        listeners[event].push(cb);
+        return mock;
+      }),
+      track: jest.fn(),
+      destroy: jest.fn(),
+      _emit(event, payload) {
+        (listeners[event] || []).forEach((cb) => cb(payload));
+      },
+    };
+    return mock;
+  }
+
+  test('ConfigurationChanged event includes metadata (type) and flagsChanged when FLAGS_UPDATE', async () => {
+    const mockClient = createMockSplitClient();
+    const provider = new OpenFeatureSplitProvider({ splitClient: mockClient });
+    const configChangedDetails = [];
+    provider.events.addHandler(ProviderEvents.ConfigurationChanged, (details) => configChangedDetails.push(details));
+
+    mockClient._emit(SDK_UPDATE, { type: 'FLAGS_UPDATE', names: ['flag1', 'flag2'] });
+
+    expect(configChangedDetails.length).toBe(1);
+    expect(configChangedDetails[0].providerName).toBe('split');
+    expect(configChangedDetails[0].metadata).toEqual({ type: 'FLAGS_UPDATE' });
+    expect(configChangedDetails[0].flagsChanged).toEqual(['flag1', 'flag2']);
+
+    await provider.onClose();
+  });
+
+  test('ConfigurationChanged event includes metadata without flagsChanged when SEGMENTS_UPDATE', async () => {
+    const mockClient = createMockSplitClient();
+    const provider = new OpenFeatureSplitProvider({ splitClient: mockClient });
+    const configChangedDetails = [];
+    provider.events.addHandler(ProviderEvents.ConfigurationChanged, (details) => configChangedDetails.push(details));
+
+    mockClient._emit(SDK_UPDATE, { type: 'SEGMENTS_UPDATE' });
+
+    expect(configChangedDetails.length).toBe(1);
+    expect(configChangedDetails[0].providerName).toBe('split');
+    expect(configChangedDetails[0].metadata).toEqual({ type: 'SEGMENTS_UPDATE' });
+    expect(configChangedDetails[0].flagsChanged).toEqual([]);
+
+    await provider.onClose();
+  });
+
+  test('ConfigurationChanged event includes only providerName when SDK_UPDATE payload is undefined', async () => {
+    const mockClient = createMockSplitClient();
+    const provider = new OpenFeatureSplitProvider({ splitClient: mockClient });
+    const configChangedDetails = [];
+    provider.events.addHandler(ProviderEvents.ConfigurationChanged, (details) => configChangedDetails.push(details));
+
+    mockClient._emit(SDK_UPDATE, undefined);
+
+    expect(configChangedDetails.length).toBe(1);
+    expect(configChangedDetails[0].providerName).toBe('split');
+    expect(configChangedDetails[0].metadata).toBeUndefined();
+    expect(configChangedDetails[0].flagsChanged).toBeUndefined();
+
+    await provider.onClose();
+  });
+});

package/src/lib/__tests__/client-resolver.spec.ts

@@ -0,0 +1,64 @@
+import type SplitIO from '@splitsoftware/splitio/types/splitio';
+import { getSplitClient } from '../client-resolver';
+import { SplitProviderOptions } from '../types';
+
+function createMockSplitClient(): SplitIO.IClient {
+  return {
+    getTreatmentWithConfig: jest.fn(),
+    getStatus: jest.fn(),
+    on: jest.fn(),
+    track: jest.fn(),
+    destroy: jest.fn(),
+    Event: {
+      SDK_READY: 'init::ready',
+      SDK_READY_FROM_CACHE: 'init::cache-ready',
+      SDK_READY_TIMED_OUT: 'init::timeout',
+      SDK_UPDATE: 'state::update',
+    },
+  } as unknown as SplitIO.IClient;
+}
+
+describe('client-resolver', () => {
+  describe('getSplitClient', () => {
+    it('returns splitClient when options is SplitProviderOptions with splitClient', () => {
+      const mockClient = createMockSplitClient();
+      const options = { splitClient: mockClient };
+      const client = getSplitClient(options);
+      expect(client).toBe(mockClient);
+    });
+
+    it('returns client from factory when options has client() method', () => {
+      const mockClient = createMockSplitClient();
+      const mockFactory = {
+        client: jest.fn().mockReturnValue(mockClient),
+      };
+      const client = getSplitClient(mockFactory as unknown as SplitIO.ISDK);
+      expect(mockFactory.client).toHaveBeenCalled();
+      expect(client).toBe(mockClient);
+    });
+
+    it('falls back to splitClient when options.client() throws', () => {
+      const mockClient = createMockSplitClient();
+      const mockFactory = {
+        client: jest.fn().mockImplementation(() => {
+          throw new Error('not a real SDK');
+        }),
+      };
+      const options = { splitClient: mockClient, ...mockFactory };
+      const client = getSplitClient(options as SplitProviderOptions);
+      expect(client).toBe(mockClient);
+    });
+
+    it('creates client from API key when options is string', () => {
+      const client = getSplitClient('localhost');
+      expect(client).toBeDefined();
+      expect(typeof client.getTreatmentWithConfig).toBe('function');
+      expect(typeof client.getStatus).toBe('function');
+      expect(client.Event).toBeDefined();
+      expect(client.Event.SDK_READY).toBeDefined();
+      if (typeof client.destroy === 'function') {
+        client.destroy();
+      }
+    });
+  });
+});

package/src/lib/__tests__/context.spec.ts

@@ -0,0 +1,72 @@
+import { transformContext } from '../context';
+import { DEFAULT_TRAFFIC_TYPE } from '../types';
+
+describe('context', () => {
+  describe('transformContext', () => {
+    it('extracts targetingKey and uses default traffic type when missing', () => {
+      const context = { targetingKey: 'user-123' };
+      const result = transformContext(context);
+      expect(result.targetingKey).toBe('user-123');
+      expect(result.trafficType).toBe(DEFAULT_TRAFFIC_TYPE);
+      expect(result.attributes).toEqual({});
+    });
+
+    it('uses provided traffic type when present and non-empty', () => {
+      const context = {
+        targetingKey: 'user-1',
+        trafficType: 'account',
+      };
+      const result = transformContext(context);
+      expect(result.trafficType).toBe('account');
+      expect(result.targetingKey).toBe('user-1');
+      expect(result.attributes).toEqual({});
+    });
+
+    it('uses default traffic type when trafficType is empty string', () => {
+      const context = {
+        targetingKey: 'user-1',
+        trafficType: '',
+      };
+      const result = transformContext(context);
+      expect(result.trafficType).toBe(DEFAULT_TRAFFIC_TYPE);
+    });
+
+    it('uses default traffic type when trafficType is whitespace', () => {
+      const context = {
+        targetingKey: 'user-1',
+        trafficType: '   ',
+      };
+      const result = transformContext(context);
+      expect(result.trafficType).toBe(DEFAULT_TRAFFIC_TYPE);
+    });
+
+    it('passes remaining context as attributes', () => {
+      const context = {
+        targetingKey: 'user-1',
+        trafficType: 'user',
+        plan: 'premium',
+        region: 'us-east',
+      };
+      const result = transformContext(context);
+      expect(result.attributes).toEqual({ plan: 'premium', region: 'us-east' });
+    });
+
+    it('uses custom defaultTrafficType when provided', () => {
+      const context = { targetingKey: 'key' };
+      const result = transformContext(context, 'custom');
+      expect(result.trafficType).toBe('custom');
+    });
+
+    it('handles context with only targetingKey and extra attributes', () => {
+      const context = {
+        targetingKey: 'anon',
+        customAttr: 'value',
+        count: 42,
+      };
+      const result = transformContext(context);
+      expect(result.targetingKey).toBe('anon');
+      expect(result.trafficType).toBe(DEFAULT_TRAFFIC_TYPE);
+      expect(result.attributes).toEqual({ customAttr: 'value', count: 42 });
+    });
+  });
+});

package/src/lib/__tests__/parsers.spec.ts

@@ -0,0 +1,63 @@
+import { ParseError } from '@openfeature/server-sdk';
+import { parseValidNumber, parseValidJsonObject } from '../parsers';
+
+describe('parsers', () => {
+  describe('parseValidNumber', () => {
+    it('returns parsed number for valid string', () => {
+      expect(parseValidNumber('0')).toBe(0);
+      expect(parseValidNumber('42')).toBe(42);
+      expect(parseValidNumber('-1')).toBe(-1);
+      expect(parseValidNumber('3.14')).toBe(3.14);
+      expect(parseValidNumber('1e2')).toBe(100);
+    });
+
+    it('throws ParseError for undefined', () => {
+      expect(() => parseValidNumber(undefined)).toThrow(ParseError);
+      expect(() => parseValidNumber(undefined)).toThrow("Invalid 'undefined' value.");
+    });
+
+    it('throws ParseError for non-numeric string', () => {
+      expect(() => parseValidNumber('')).toThrow(ParseError);
+      expect(() => parseValidNumber('abc')).toThrow(ParseError);
+      expect(() => parseValidNumber('NaN')).toThrow(ParseError);
+    });
+
+    it('throws with message containing the invalid value', () => {
+      expect(() => parseValidNumber('foo')).toThrow('Invalid numeric value foo');
+    });
+  });
+
+  describe('parseValidJsonObject', () => {
+    it('returns parsed object for valid JSON object string', () => {
+      expect(parseValidJsonObject('{}')).toEqual({});
+      expect(parseValidJsonObject('{"a":1}')).toEqual({ a: 1 });
+      expect(parseValidJsonObject('{"nested":{"b":2}}')).toEqual({
+        nested: { b: 2 },
+      });
+      expect(parseValidJsonObject('[]')).toEqual([]);
+    });
+
+    it('throws ParseError for undefined', () => {
+      expect(() => parseValidJsonObject(undefined)).toThrow(ParseError);
+      expect(() => parseValidJsonObject(undefined)).toThrow(
+        "Invalid 'undefined' JSON value."
+      );
+    });
+
+    it('throws ParseError for non-object JSON (string, number, boolean)', () => {
+      expect(() => parseValidJsonObject('"hello"')).toThrow(ParseError);
+      expect(() => parseValidJsonObject('42')).toThrow(ParseError);
+      expect(() => parseValidJsonObject('true')).toThrow(ParseError);
+    });
+
+    it('throws with message indicating expected object type', () => {
+      expect(() => parseValidJsonObject('"x"')).toThrow('expected "object"');
+    });
+
+    it('throws ParseError for invalid JSON', () => {
+      expect(() => parseValidJsonObject('{')).toThrow(ParseError);
+      expect(() => parseValidJsonObject('not json')).toThrow(ParseError);
+      expect(() => parseValidJsonObject('{"unclosed":')).toThrow(ParseError);
+    });
+  });
+});

package/src/lib/__tests__/readiness.spec.ts

@@ -0,0 +1,159 @@
+import { OpenFeatureEventEmitter, ProviderEvents } from '@openfeature/server-sdk';
+import type SplitIO from '@splitsoftware/splitio/types/splitio';
+import { attachReadyEventHandlers, waitUntilReady } from '../readiness';
+import { PROVIDER_NAME } from '../types';
+
+interface MockSplitClient {
+  Event: { SDK_READY: string; SDK_READY_FROM_CACHE: string; SDK_READY_TIMED_OUT: string };
+  getStatus: jest.Mock;
+  on: jest.Mock;
+  _emit: (event: string, metadata?: unknown) => void;
+}
+
+function createMockClient(overrides: Partial<{
+  isReady: boolean;
+  hasTimedout: boolean;
+  readyMetadata: { initialCacheLoad?: boolean; lastUpdateTimestamp?: number };
+}> = {}): MockSplitClient {
+  const { isReady = false, hasTimedout = false } = overrides;
+  const listeners: Record<string, ((...args: unknown[]) => void)[]> = {
+    'init::ready': [],
+    'init::cache-ready': [],
+    'init::timeout': [],
+  };
+  const mock: MockSplitClient = {
+    Event: {
+      SDK_READY: 'init::ready',
+      SDK_READY_FROM_CACHE: 'init::cache-ready',
+      SDK_READY_TIMED_OUT: 'init::timeout',
+    },
+    getStatus: jest.fn().mockReturnValue({ isReady, hasTimedout }),
+    on: jest.fn((event: string, cb: (...args: unknown[]) => void) => {
+      if (!listeners[event]) listeners[event] = [];
+      listeners[event].push(cb);
+      return mock;
+    }),
+    _emit(event: string, metadata?: unknown) {
+      (listeners[event] || []).forEach((cb) => cb(metadata));
+    },
+  };
+  return mock;
+}
+
+describe('readiness', () => {
+  describe('attachReadyEventHandlers', () => {
+    it('emits ProviderEvents.Ready with readyFromCache true when SDK_READY_FROM_CACHE fires', () => {
+      const client = createMockClient();
+      const events = new OpenFeatureEventEmitter();
+      const handler = jest.fn();
+      events.addHandler(ProviderEvents.Ready, handler);
+
+      attachReadyEventHandlers(client as unknown as SplitIO.IClient, events, 'split');
+      expect(client.on).toHaveBeenCalledWith('init::cache-ready', expect.any(Function));
+      expect(client.on).toHaveBeenCalledWith('init::ready', expect.any(Function));
+
+      client._emit('init::cache-ready', {
+        initialCacheLoad: true,
+        lastUpdateTimestamp: 12345,
+      });
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler.mock.calls[0][0]).toMatchObject({
+        providerName: 'split',
+        metadata: {
+          readyFromCache: true,
+          initialCacheLoad: true,
+          lastUpdateTimestamp: 12345,
+        },
+      });
+    });
+
+    it('emits ProviderEvents.Ready with readyFromCache false when SDK_READY fires', () => {
+      const client = createMockClient();
+      const events = new OpenFeatureEventEmitter();
+      const handler = jest.fn();
+      events.addHandler(ProviderEvents.Ready, handler);
+
+      attachReadyEventHandlers(client as unknown as SplitIO.IClient, events);
+      client._emit('init::ready', {
+        initialCacheLoad: false,
+        lastUpdateTimestamp: 99999,
+      });
+
+      expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining({
+          providerName: PROVIDER_NAME,
+          metadata: expect.objectContaining({
+            readyFromCache: false,
+            initialCacheLoad: false,
+            lastUpdateTimestamp: 99999,
+          }),
+        })
+      );
+    });
+
+    it('handles undefined metadata (e.g. consumer/Redis mode)', () => {
+      const client = createMockClient();
+      const events = new OpenFeatureEventEmitter();
+      const handler = jest.fn();
+      events.addHandler(ProviderEvents.Ready, handler);
+
+      attachReadyEventHandlers(client as unknown as SplitIO.IClient, events);
+      client._emit('init::ready', undefined);
+
+      expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining({
+          providerName: PROVIDER_NAME,
+          metadata: expect.objectContaining({
+            readyFromCache: false,
+            initialCacheLoad: false,
+          }),
+        })
+      );
+    });
+
+    it('emits Ready immediately when client is already ready (e.g. localhost or reused client)', () => {
+      const client = createMockClient({ isReady: true });
+      const events = new OpenFeatureEventEmitter();
+      const handler = jest.fn();
+      events.addHandler(ProviderEvents.Ready, handler);
+
+      attachReadyEventHandlers(client as unknown as SplitIO.IClient, events);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler.mock.calls[0][0]).toMatchObject({
+        providerName: PROVIDER_NAME,
+        metadata: {
+          readyFromCache: false,
+          initialCacheLoad: false,
+        },
+      });
+    });
+  });
+
+  describe('waitUntilReady', () => {
+    it('resolves immediately when client is already ready', async () => {
+      const client = createMockClient({ isReady: true });
+      await expect(waitUntilReady(client as unknown as SplitIO.IClient, new OpenFeatureEventEmitter(), PROVIDER_NAME)).resolves.toBeUndefined();
+    });
+
+    it('rejects when client has timed out', async () => {
+      const client = createMockClient({ hasTimedout: true });
+      await expect(waitUntilReady(client as unknown as SplitIO.IClient, new OpenFeatureEventEmitter(), PROVIDER_NAME)).rejects.toBeUndefined();
+    });
+
+    it('resolves when SDK_READY fires', async () => {
+      const client = createMockClient({ isReady: false, hasTimedout: false });
+      const promise = waitUntilReady(client as unknown as SplitIO.IClient, new OpenFeatureEventEmitter(), PROVIDER_NAME);
+      client._emit('init::ready');
+      await expect(promise).resolves.toBeUndefined();
+    });
+
+    it('rejects when SDK_READY_TIMED_OUT fires', async () => {
+      const client = createMockClient({ isReady: false, hasTimedout: false });
+      const promise = waitUntilReady(client as unknown as SplitIO.IClient, new OpenFeatureEventEmitter(), PROVIDER_NAME);
+      client._emit('init::timeout');
+      await expect(promise).rejects.toBeUndefined();
+    });
+  });
+});

package/src/lib/client-resolver.ts

@@ -0,0 +1,22 @@
+import { SplitFactory } from '@splitsoftware/splitio';
+import type SplitIO from '@splitsoftware/splitio/types/splitio';
+import type { SplitProviderConstructorOptions, SplitProviderOptions } from './types';
+
+/**
+ * Resolves the Split client from the various supported constructor option shapes.
+ * Supports: API key (string), Split SDK/AsyncSDK (factory), or pre-built splitClient.
+ */
+export function getSplitClient(
+  options: SplitProviderConstructorOptions
+): SplitIO.IClient | SplitIO.IAsyncClient {
+  if (typeof options === 'string') {
+    const splitFactory = SplitFactory({ core: { authorizationKey: options } });
+    return splitFactory.client();
+  }
+
+  try {
+    return (options as SplitIO.ISDK | SplitIO.IAsyncSDK).client();
+  } catch {
+    return (options as SplitProviderOptions).splitClient;
+  }
+}